1"""
  2# `exploration` library Journaling Guide
  3
  4This page explains the basics of the journaling language that's supported
  5via the `JournalObserver` class in `journal.py`. More detailed references
  6for specific types and methods are available in that file, but here we
  7attempt to summarize them.
  8
  9This document assumes you are familiar with the stuff described in the
 10`exploration.overview` file; you should read that first if you haven't
 11already.
 12
 13
 14## What is a journal?
 15
 16While the `exploration.core.DiscreteExploration` class has many methods
 17for creating and updating exploration records, it's cumbersome to use
 18them to actually create a full record of gameplay. To make it easier to
 19record the exploration process, the `exploration.journal` module (and in
 20particular, the `exploration.journal.JournalObserver` class) is provided
 21to parse a domain-specific language designed to record exploration
 22progress. There is a rough correspondence between the
 23`DiscreteExploration` API and the journal format entries, but there's
 24some additional automatic state that gets tracked by a `JournalObserver`
 25object that allows for even more concise specification of exploration
 26progress.
 27
 28Fundamentally, a "journal" is text, stored in a file or variable, which
 29consists of a series of entries, each on a single line (or spanning
 30multiple lines using `[` and `]` symbols as directional quotation marks).
 31The entry begins with an entry type, such as 'explore' or 'observe' and
 32then includes additional parameters which define what the player wants to
 33note down.
 34
 35
 36## Journal Entry Types
 37
 38### Core Entry Types
 39
 40The most common journal entry types are 'observe', 'explore',
 41'requirement', 'effect', and 'retrace':
 42
 431. 'observe', or 'o' for short, which indicates that a new *transition*
 44    has been noticed. The name of the transition is the only required
 45    parameter, if its destination and/or reciprocal name are known, these
 46    can be supplied as well. Observing a transition does not imply a new
 47    exploration step has been taken, and typically after exploring to a
 48    new decision point, multiple observations of options at that decision
 49    will follow immediately. For example:
 50
 51        `observe left`
 52
 53    states that a transition named 'left' has been observed, while
 54        
 55        `o right rightSide left`
 56
 57    states that a transition named 'right' has been observed, which
 58    connects to a decision named 'rightSide', with a reciprocal
 59    transition from 'rightSide' back to the current decision which is
 60    named 'left'.
 61
 622. 'explore', or 'x' for short, which indicates that a
 63    previously-unexplored transition is followed. The name of the
 64    transition taken is required. If the destination name for that
 65    transition has not yet been specified, that is required as well, and
 66    a reciprocal transition name may also be provided. For example:
 67
 68        `explore right rightSide left`
 69
 70    would indicate that the 'right' transition from the current decision
 71    was taken, leading to a decision named 'rightSide' with the
 72    reciprocal transition back to the previous decision being named
 73    'left'. (By default, if no reciprocal name is given the reciprocal
 74    transition will be named 'return'. If '-' is used as the reciprocal
 75    name, then a one-way transition without a reciprocal will be created.)
 76    The entry
 77    
 78        `x enterDoor innerRoom`
 79
 80    would thus denote exploring a transition 'enterDoor' to reach a room
 81    'innerRoom' with the reciprocal transition name defaulting to
 82    'return'.
 83
 84    Note that the transition taken need not have already been observed;
 85    the 'explore' entry will add it if necessary before exploring it.
 86    Also, if an 'observe' entry already specified at least the
 87    destination name, then it can be left out when exploring, so a pair
 88    of entries like:
 89
 90        ```txt
 91        o right rightSide left
 92        x right
 93        ```
 94
 95    would first establish the 'right' transition, its destination, and
 96    its reciprocal, and then explore that transition. This is actually
 97    useful when other entries happen between the two.
 98
 993. 'requirement', or 'q' for short, indicates that the
100    most-recently-mentioned transition has a requirement. This will apply
101    to the transition just mentioned via an 'observe' or 'explore' entry,
102    or possibly other entry types that mention a transition. As discussed
103    in the `exploration.overview` documentation, transitions may use
104    *capabilities*, *tokens*, and/or *mechanism* states as requirements,
105    and may combine these using boolean 'and', 'or', and 'not' operators.
106    After the entry type, a 'requirement' entry should include a single
107    expression specifying the requirement to apply, using `&` for and,
108    `|` for or, and `!` for not. Parentheses `()` can be used for
109    grouping sub-expressions, so an entry like:
110
111        `requirement boots|(sandals&!softFeet)`
112
113    would be satisfied by the 'boots' capability, or by the combination
114    of the 'sandals' capability and the lack of the 'softFeet' capability.
115    Brackets `[]` are necessary to enclose a requirement that includes
116    spaces in it, for example:
117
118        `q [ boots | ( sandals & !softFeet ) ]`
119
120    The requirement could even be split across multiple lines if brackets
121    are used, provided that the opening bracket is at the end of a line,
122    and the closing bracket is alone on a line (this use of brackets to
123    combine words into a single parameter applies to all entry types).
124
125    To require at least a certain number of tokens, use the token name,
126    followed by `*`, followed by an integer, so
127
128        `q !leaf*3`
129
130    would require that the player has 2 or fewer 'leaf' tokens (note the
131    `!`). Requiring a mechanism state uses the fully-specified or generic
132    mechanism name, followed by a colon `:` and then the required state,
133    for example:
134
135        `q gate:open`
136
137    requires that the 'gate' mechanism be in the 'open' state, whereas
138
139        `q RollingHills::greenHill::gate:open`
140
141    requires that the 'gate' mechanism which is at the 'greenHill'
142    decision within the 'RollingHills' zone is in the 'open' state. Note
143    the use of `::` to specify a decision name and preceding that a zone
144    name for the mechanism location; both are optional, and an additional
145    domain may be specified using `//` before the zone. This syntax for
146    specifying domain/zone/decision is used in other places as well.
147
148    Of course, token and/or mechanism requirements can be combined with
149    capability requirements using boolean operators, for example:
150
151        `q gate:open|coin*3|superJump`
152
153    requires that either the 'gate' mechanism is in the 'open' state, you
154    have three 'coin' tokens, or you have the 'superJump' capability.
155    This could be combined with a conditional effect stating that if you
156    don't have superJump and the gate is not open, you will lose three
157    coins and set the gate mechanism to open...
158
1594. 'effect', or 'e' for short, establishes a consequence of the
160    most-recently-mentioned transition. Note that it does not apply the
161    consequence, it merely establishes it as something that would apply
162    were that transition taken, so if you want to note a consequence that
163    was applied by the transition you just took, you should use 'apply'
164    with the 'transition' target (see below). Consequences are discussed
165    in more detail in the `exploration.overview` document and are
166    defined as `exploration.base.Consequence`. The syntax for defining
167    complex consequences is beyond the scope of this document (see
168    `exploration.parsing.ParseFormat.parseConsequence` and related
169    methods like `parseCondition`, `parseEffect`, and `parseChallenge`
170    although these currently only have a few examples of the relevant
171    formats). Simple one-effect consequences can be things like:
172
173        `gain key*1`
174
175    which adds one 'key' token, or
176
177        `set gate:open`
178
179    which sets the 'gate' mechanism to the 'open' state, or simply
180
181        `deactivate`
182
183    which once applied prevents that transition from being taken again.
184
1855. 'retrace'
186
187### Entry Targets
188
189### Additional Entry Types
190
191Besides these core entry types, a few others are used less frequently for
192key actions: 'START', 'END', 'return', 'action', 'wait', 'warp', 'apply',
193'mechanism', 'zone', 'tag', and 'annotate'
194
195
196## The Journaling Process
197
198
199## Debugging a Journal
200
201
202The 'DEBUG' entry
203
204## Advanced Journal Entry Types
205
206For now, refer to the `exploration.journal.JournalEntryType`
207documentation for these additional journal entry types, and for the full
208list of all available journal entry types.
209
210### Revising Structure
211
212'unify', 'obviate', 'extinguish', 'complicate'
213
214### Reverting Game State
215
216'revert'
217
218### Unknown Requirements
219
220'fulfills'
221
222### Custom Entry Types
223
224'alias' and 'custom'
225
226### Relative Mode
227
228'relative'
229"""