txt: ## dist_zef-raku-community-modules-Marpa.md
  ## Chunk 2 of 3
  \_symbol\_is\_predicted\_event() method returns the current value of the predicted event marking for symbol sym\_id. Marking a prediction event sets its activation status to on. Unmarking a prediction event sets its activation status to off. The prediction event marking cannot be changed once the grammar is precomputed. If a prediction event is marked, its activation status can be changed using the marpa\_g\_prediction\_symbol\_activate() method. Note that, if a symbol is marked as a prediction event symbol in the recognizer, its prediction event can be deactivated and reactivated in the recognizer. Success: On success, 1 if symbol sym\_id is a predicted event symbol after the call, 0 otherwise. Failures: If sym\_id is well-formed, but there is no such symbol, −1. If the grammar g is precomputed; or on other failure, −2.
  
  ### sub marpa\_g\_precompute
  
  ```
  sub marpa_g_precompute(
      Marpa::g $g
  ) returns Int
  
  ```
  
  Precomputation is necessary for a recognizer to be generated from a grammar. On success, marpa\_g\_precompute returns a non-negative number to indicate that it precomputed the grammar without issues. On failure, marpa\_g\_precompute returns −2. Precomputation may return one or more events, which may be queried using the marpa\_g\_event() method. At this point events only occur when failure is reported, and events always report issues. But application writers should expect future versions to have events which are reported on success, as well as events which do not represent issues. A MARPA-EVENT-LOOP-RULES event occurs when there are infinite loop rules (cycles) in the grammar. The presence of one or more of these will cause failure to be reported, but will not prevent the grammar from being precomputed. Each MARPA-EVENT-COUNTED-NULLABLE event is a symbol which is a nullable on the right hand side of a sequence rule — a “counted” symbol. The presence of one or more of these will cause failure to be reported, and will prevent the grammar from being precomputed. So that the programmer can fix several at once, these failures are delayed until events are created for all of the counted nullables. Each MARPA-EVENT-NULLING-TERMINAL event is a nulling symbol which is also flagged as a terminal. Since terminals cannot be of zero length, this is a logical impossibility. The presence of one or more of these will cause failure to be reported, and will prevent the grammar from being precomputed. So that the programmer can fix several at once, the failure is delayed until events are created for all of the counted nullables. Precomputation involves freezing and then thoroughly checking the grammar. Among the reasons for precomputation to fail are the following: MARPA-ERR-NO-RULES: The grammar has no rules. MARPA-ERR-NO-START-SYMBOL: No start symbol was specified. MARPA-ERR-INVALID-START-SYMBOL: A start symbol ID was specified, but it is not the ID of a valid symbol. MARPA-ERR-START-NOT-LHS: The start symbol is not on the LHS of any rule. MARPA-ERR-UNPRODUCTIVE-START: The start symbol is not productive. MARPA-ERR-COUNTED-NULLABLE: A symbol on the RHS of a sequence rule is nullable. Libmarpa does not allow this. MARPA-ERR-NULLING-TERMINAL: A terminal is also a nulling symbol. Libmarpa does not allow this. More details of these can be found under the description of the appropriate code. See External error codes. marpa\_g\_precompute() is unusual in that it is possible to treat one of its failures as “advisory”, and to proceed with parsing. If marpa\_g\_precompute() fails with an error code of MARPA-ERR-GRAMMAR-HAS-CYCLE, parsing can proceed, just as it typically would for success. The grammar will have been precomputed, as calling the marpa\_g\_is\_precomputed() method will confirm. Most applications, however, will want to simply treat failure with MARPA-ERR-GRAMMAR-HAS-CYCLE, as simply another failure, and fix the cycles before parsing. Cycles make a grammar infinitely ambiguous, and are considered useless in current practice. Cycles make processing the grammar less efficient, sometimes considerably so. Detection of cycles is returned as failure because that is by far the convenient thing to do for the vast majority of applications. Success value: A non-negative number. Failure value: −2.
  
  ### sub marpa\_g\_is\_precomputed
  
  ```
  sub marpa_g_is_precomputed(
      Marpa::g $g
  ) returns Int
  
  ```
  
  Success value: 1 if grammar g is already precomputed, 0 otherwise. Failure value: −2.
  
  ### sub marpa\_g\_has\_cycle
  
  ```
  sub marpa_g_has_cycle(
      Marpa::g $g
  ) returns Int
  
  ```
  
  This function allows the application to determine if grammar g has a cycle. As mentioned, most applications will want to treat these as fatal errors. To determine which rules are in the cycle, marpa\_g\_rule\_is\_loop() can be used. Success value: 1 if the grammar has a cycle, 0 otherwise. Failure value: −2.
  
  ### sub marpa\_r\_new
  
  ```
  sub marpa_r_new(
      Marpa::g $g
  ) returns Marpa::Marpa-Recognizer
  
  ```
  
  Creates a new recognizer. The reference count of the recognizer will be 1. The reference count of g, the base grammar, will be incremented by one. Success value: The newly created recognizer. If g is not precomputed, or on other failure, NULL. Failure value: NULL.
  
  ### sub marpa\_r\_ref
  
  ```
  sub marpa_r_ref(
      Marpa::Marpa-Recognizer $r
  ) returns Marpa::Marpa-Recognizer
  
  ```
  
  Increases the reference count by 1. Not needed by most applications. Success value: The recognizer object, $r. Failure value: NULL.
  
  ### sub marpa\_r\_unref
  
  ```
  sub marpa_r_unref(
      Marpa::Marpa-Recognizer $r
  ) returns Mu
  
  ```
  
  Decreases the reference count by 1, destroying r once the reference count reaches zero. When r is destroyed, the reference count of its base grammar is decreased by one. If this takes the reference count of the base grammar to zero, it too is destroyed.
  
  ### sub marpa\_r\_start\_input
  
  ```
  sub marpa_r_start_input(
      Marpa::Marpa-Recognizer $r
  ) returns Int
  
  ```
  
  Makes r ready to accept input. The first Earley set, the one at earleme 0, will be completed during this call. Because the call to marpa\_r\_start\_input() completes an Earley set, it may generate events. For details about the events that may be generated during Earley set completion, see the description of the marpa\_r\_earleme\_complete() method. Success value: A non-negative value. Failure value: −2.
  
  ### sub marpa\_r\_alternative
  
  ```
  sub marpa_r_alternative(
      Marpa::Marpa-Recognizer $r,
      Marpa::Marpa-Symbol-ID $token_id,
      Int $value,
      Int $length
  ) returns Int
  
  ```
  
  Reads a token into r. The token will start at the current earleme. Libmarpa allows tokens to be ambiguous, to be of variable length and to overlap. token\_id is the symbol ID of the token, which must be a terminal. length is the length of the token. value is an integer that represents the value of the token. In applications where the token's actual value is not an integer, it is expected that the application will use this value as a “virtual” value, perhaps finding the actual value by using value to index an array. value is not used inside Libmarpa — it is simply stored to be returned by the valuator as a convenience for the application. Some applications may prefer to track token values on their own, perhaps based on the earleme location and token\_id, instead of using Libmarpa's token values. A value of 0 is reserved for a now-deprecated feature. Do not use it. For more details on that feature, see the section Valued and unvalued symbols. When marpa\_r\_alternative() is successful, the value of the furthest earleme is set to the greater of its value before the call, and current+length, where current is the value of the current earleme. The values of the current and latest earlemes are unchanged by calls to marpa\_r\_alternative(). Several error codes leave the recognizer in a fully recoverable state, allowing the application to retry the marpa\_r\_alternative() method. Retry is efficient, and quite useable as a parsing technique. The error code of primary interest from this point of view is MARPA-ERR-UNEXPECTED-TOKEN-ID, which indicates that the token was not accepted because of its token ID. Retry after this condition is used in several applications, and is called “the Ruby Slippers technique”. The error codes MARPA-ERR-DUPLICATE-TOKEN, MARPA-ERR-NO-TOKEN-EXPECTED-HERE and MARPA-ERR-INACCESSIBLE-TOKEN also leave the recognizer in a fully recoverable state, and may also be useable for the Ruby Slippers or similar techniques. At this writing, the author knows of no applications which attempt to recover from these errors. Success value: MARPA-ERR-NONE. Failure value: Some other error code.
  
  ### sub marpa\_r\_earleme\_complete
  
  ```
  sub marpa_r_earleme_complete(
      Marpa::Marpa-Recognizer $r
  ) returns Int
  
  ```
  
  This method does the final processing for the current earleme. It then advances the current earleme by one. Note that marpa\_r\_earleme\_complete() may be called even when no tokens have been read at the current earleme — in the character-per-earleme input model, for example, tokens can span many characters and, if the input is unambiguous over that span, there will be no other tokens that start inside it. As mentioned, marpa\_r\_earleme\_complete() always advances the current earleme, incrementing its value by 1. This means that value of the current earleme after the call will be the one plus the value of the earleme processed by the call to marpa\_r\_earleme\_complete(). If any token was accepted at the earleme being processed, marpa\_r\_earleme\_complete() creates a new Earley set which will be the latest Earley set and, after the call, the latest earleme will be equal to the new current earleme. If no token was accepted at the earleme being processed, no Earley set is created, and the value of the latest earleme remains unchanged. The value of the furthest earleme is never changed by a call to marpa\_r\_earleme\_complete(). During this method, one or more events may occur. On success, this function returns the number of events generated, but it is important to note that events may be created whether earleme completion fails or succeeds. When this method fails, the application must call marpa\_g\_event() if it wants to determine if any events occurred. Since the reason for failure to complete an earleme is often detailed in the events, applications that fail will often be at least as interested in the events as those that succeed. The MARPA-EVENT-EARLEY-ITEM-THRESHOLD event indicates that an application-settable threshold on the number of Earley items has been reached or exceeded. What this means depends on the application, but when the default threshold is exceeded, it means that it is very likely that the time and space resources consumed by the parse will prove excessive. A parse is “exhausted” when it can accept no more input. This can happen both on success and on failure. Note that the failure due to parse exhaustion only means failure at the current earleme. There may be successful parses at earlier earlemes. If a parse is exhausted, but successful, an event with the event code MARPA-EVENT-EXHAUSTED occurs. Because the parse is exhausted, no input will be accepted at later earlemes. It is quite common for a parse to become exhausted when it succeeds. Many practical grammars are designed so that a successful parse cannot be extended. An exhausted parse may cause a failure, in which case marpa\_r\_earleme\_complete() returns an error whose error code is MARPA-ERR-PARSE-EXHAUSTED. For a parse to fail at an earleme due to exhaustion, it must be the case that no alternatives were accepted at that earleme. In fact, in the standard input model, a failure due to parse exhaustion occurs if and only if no alternatives were accepted at the current earleme. The circumstances under which failure due to parse exhaustion occurs are slightly more complicated when variable length tokens are in use. Informally, a parse will never fail due to exhaustion as long as it is possible that a token ending at some future earleme will continue the parse. More precisely, a call to marpa\_r\_earleme\_complete() fails due to parse exhaustion if and only if, first, no alternatives were added at the current earleme and, second, that call left the current earleme equal to the furthest earleme. Success value: The number of events generated. Failure value: −2.
  
  ### sub marpa\_r\_current\_earleme
  
  ```
  sub marpa_r_current_earleme(
      Marpa::Marpa-Recognizer $r
  ) returns Marpa::Marpa-Earleme
  
  ```
  
  Success value: If input has started, the current earleme. If input has not started, −1. Failure value: Always succeeds.
  
  ### sub marpa\_r\_earleme
  
  ```
  sub marpa_r_earleme(
      Marpa::Marpa-Recognizer $r,
      Marpa::Marpa-Earley-Set-ID $set_id
  ) returns Marpa::Marpa-Earleme
  
  ```
  
  In the default, token-stream model, Earley set ID and earleme are always equal, but this is not the case in other input models. (The ID of an Earley set ID is also called its ordinal.) If there is no Earley set whose ID is set\_id, marpa\_r\_earleme() fails. If set\_id was negative, the error code is set to MARPA-ERR-INVALID-LOCATION. If set\_id is greater than the ordinal of the latest Earley set, the error code is set to MARPA-ERR-NO-EARLEY-SET-AT-LOCATION. At this writing, there is no method for the inverse operation (conversion of an earleme to an Earley set ID). One consideration in writing such a method is that not all earlemes correspond to Earley sets. Applications that want to map earlemes to Earley sets will have no trouble if they are using the standard input model — the Earley set ID is always exactly equal to the earleme in that model. For other applications that want an earleme-to-ID mapping, the most general method is create an ID-to-earleme array using the marpa\_r\_earleme() method and invert it. Success value: The earleme corresponding to Earley set set\_id. Failure value: −2.
  
  ### sub marpa\_r\_earley\_set\_value
  
  ```
  sub marpa_r_earley_set_value(
      Marpa::Marpa-Recognizer $r,
      Marpa::Marpa-Earley-Set-ID $earley_set
  ) returns Int
  
  ```
  
  Returns the integer value of earley\_set. For more details, see the description of marpa\_r\_earley\_set\_values(). Success value: The value of earley\_set. Failure value: −2.
  
  ### sub marpa\_r\_earley\_set\_values
  
  ```
  sub marpa_r_earley_set_values(
      Marpa::Marpa-Recognizer $r,
      Marpa::Marpa-Earley-Set-ID $earley_set,
      NativeCall::Types::Pointer[Int] $p_value,
      NativeCall::Types::Pointer[NativeCall::Types::Pointer[NativeCall::Types::void]] $p_pvalue
  ) returns Int
  
  ```
  
  If p\_value is non-zero, sets the location pointed to by p\_value to the integer value of the Earley set. Similarly, if p\_pvalue is non-zero, sets the location pointed to by p\_pvalue to the pointer value of the Earley set. The “value” and “pointer” of an Earley set are an arbitrary integer and an arbitrary pointer that the application can use for its own purposes. In character-per-earleme input models, for example, the integer can be the codepoint of the current character. In a traditional token-per-earleme input model, they could be used to indicate the string value of the token – the pointer could point to the start of the string, and the integer could indicate its length. The Earley set value and pointer can be set using the marpa\_r\_latest\_earley\_set\_values\_set() method. The Earley set integer value defaults to −1, and the pointer value defaults to NULL. Success value: returns a non-negative integer. Failure value: −2.
  
  ### sub marpa\_r\_furthest\_earleme
  
  ```
  sub marpa_r_furthest_earleme(
      Marpa::Marpa-Recognizer $r
  ) returns UInt
  
  ```
  
  Success value: The furthest earleme. Failure value: Always succeeds.
  
  ### sub marpa\_r\_latest\_earley\_set
  
  ```
  sub marpa_r_latest_earley_set(
      Marpa::Marpa-Recognizer $r
  ) returns Marpa::Marpa-Earley-Set-ID
  
  ```
  
  This method returns the Earley set ID (ordinal) of the latest Earley set. Applications that want the value of the latest earleme can convert this value using the marpa\_r\_earleme() method. Success value: the ID of the latest Earley set. Failure value: Always succeeds.
  
  ### sub marpa\_r\_latest\_earley\_set\_value\_set
  
  ```
  sub marpa_r_latest_earley_set_value_set(
      Marpa::Marpa-Recognizer $r,
      Int $value
  ) returns Int
  
  ```
  
  Sets the integer value of the latest Earley set. For more details, see the description of marpa\_r\_latest\_earley\_set\_values\_set(). Success value: The new value of earley\_set. Failure value: −2.
  
  ### sub marpa\_r\_latest\_earley\_set\_values\_set
  
  ```
  sub marpa_r_latest_earley_set_values_set(
      Marpa::Marpa-Recognizer $r,
      Int $value,
      NativeCall::Types::Pointer[NativeCall::Types::void] $pvalue
  ) returns Int
  
  ```
  
  Sets the integer and pointer value of the latest Earley set. For more about the “integer value” and “pointer value” of an Earley set, see the description of the marpa\_r\_earley\_set\_values() method. Success value: Returns a non-negative integer. Failure value: −2.
  
  ### sub marpa\_r\_completion\_symbol\_activate
  
  ```
  sub marpa_r_completion_symbol_activate(
      Marpa::Marpa-Recognizer $r,
      Marpa::Marpa-Symbol-ID $sym_id,
      Int $reactivate
  ) returns Int
  
  ```
  
  Allows the user to deactivate and reactivate symbol completion events in the recognizer. If reactivate is zero, the event is deactivated. If reactivate is one, the event is activated. Symbol completion events are active by default if the symbol was set up for completion events in the grammar. If a symbol was not set up for completion events in the grammar, symbol completion events are inactive by default and any attempt to change that is a fatal error. Success value: The method returns the value of reactivate. The method succeeds trivially if the symbol is already set as indicated by reactivate. Failure value: If the active status of the completion event for sym\_id cannot be set as indicated by reactivate, the method fails. On failure, −2 is returned.
  
  ### sub marpa\_r\_earley\_item\_warning\_threshold\_set
  
  ```
  sub marpa_r_earley_item_warning_threshold_set(
      Marpa::Marpa-Recognizer $r,
      Int $threshold
  ) returns Int
  
  ```
  
  These methods, respectively, set and query the Earley item warning threshold. The Earley item warning threshold is a number that is compared with the count of Earley items in each Earley set. When it is matched or exceeded, a MARPA-EVENT-EARLEY-ITEM-THRESHOLD event is created. If threshold is zero or less, an unlimited number of Earley items will be allowed without warning. This will rarely be what the user wants. By default, Libmarpa calculates a value based on the grammar. The formula Libmarpa uses is the result of some experience, and most applications will be happy with it. Success value: The value that the Earley item warning threshold has after the method call is finished. Failure value: Always succeeds.
  
  ### sub marpa\_r\_expected\_symbol\_event\_set
  
  ```
  sub marpa_r_expected_symbol_event_set(
      Marpa::Marpa-Recognizer $r,
      Marpa::Marpa-Symbol-ID $symbol_id,
      Int $value
  ) returns Int
  
  ```
  
  Sets the “expected symbol event bit” for symbol\_id to value. A recognizer event is created whenever symbol symbol\_id is expected at the current earleme. if and only if the expected symbol event bit for symbol\_id is 1. The “expected symbol event bit” must be 1 or 0. In this context, “expected” means “expected as a terminal”. Even if a symbol is predicted at the current earleme, if it is not acceptable as a terminal, it does not trigger an “expected symbol event”. By default, the “expected symbol event bit” is 0. It is an error to attempt to set the “expected symbol event bit” to 1 for a nulling symbol, an inaccessible symbol, or an unproductive symbol. Success value: The value of the event bit after the method call is finished. Failure value: -2 if symbol\_id is not the ID of a valid symbol; if it is the ID of an nulling, inaccessible for unproductive symbol; or on other failure.
  
  ### sub marpa\_r\_is\_exhausted
  
  ```
  sub marpa_r_is_exhausted(
      Marpa::Marpa-Recognizer $r
  ) returns Int
  
  ```
  
  A parser is “exhausted” if it cannot accept any more input. Both successful and failed parses can be exhausted. In many grammars, the parse is always exhausted as soon as it succeeds. Good parses may also exist at earlemes prior to the current one. Success value: 1 if the parser is exhausted, 0 otherwise. Failure value: Always succeeds.
  
  ### sub marpa\_r\_nulled\_symbol\_activate
  
  ```
  sub marpa_r_nulled_symbol_activate(
      Marpa::Marpa-Recognizer $r,
      Marpa::Marpa-Symbol-ID $sym_id,
      Int $boolean
  ) returns Int
  
  ```
  
  Allows the user to deactivate and reactivate symbol nulled events in the recognizer. If boolean is zero, the event is deactivated. If boolean is one, the event is activated. Symbol nulled events are active by default if the symbol was set up for nulled events in the grammar. If a symbol was not set up for nulled events in the grammar, symbol nulled events are inactive by default and any attempt to change that is a fatal error. Success cases: On success, the method returns the value of boolean. The method succeeds trivially if the symbol is already set as indicated by boolean. Failure cases: If the active status of the nulled event for sym\_id cannot be set as indicated by boolean, the method fails. On failure, −2 is returned.
  
  ### sub marpa\_r\_prediction\_symbol\_activate
  
  ```
  sub marpa_r_prediction_symbol_activate(
      Marpa::Marpa-Recognizer $r,
      Marpa::Marpa-Symbol-ID $sym_id,
      Int $boolean
  ) returns Int
  
  ```
  
  Allows the user to deactivate and reactivate symbol prediction events in the recognizer. If boolean is zero, the event is deactivated. If boolean is one, the event is activated. Symbol prediction events are active by default if the symbol was set up for prediction events in the grammar. If a symbol was not set up for prediction events in the grammar, symbol prediction events are inactive by default and any attempt to change that is a fatal error. Success value: The method returns the value of boolean. The method succeeds trivially if the symbol is already set as indicated by boolean. Failure value: If the active status of the prediction event for sym\_id cannot be set as indicated by boolean, the method fails. On failure, −2 is returned.
  
  ### sub marpa\_r\_terminals\_expected
  
  ```
  sub marpa_r_terminals_expected(
      Marpa::Marpa-Recognizer $r,
      NativeCall::Types::Pointer[Marpa::Marpa-Symbol-ID] $buffer
  ) returns Int
  
  ```
  
  Returns a list of the ID's of the symbols that are acceptable as tokens at the current earleme. buffer is expected to be large enough to hold the result. This is guaranteed to be the case if the buffer is large enough to hold a number of Marpa-Symbol-ID's that is greater than or equal to the number of symbols in the grammar. Success value: The number of Marpa-Symbol-ID's in buffer. Failure value: −2.
  
  ### sub marpa\_r\_terminal\_is\_expected
  
  ```
  sub marpa_r_terminal_is_expected(
      Marpa::Marpa-Recognizer $r,
      Marpa::Marpa-Symbol-ID $symbol_id
  ) returns Int
  
  ```
  
  Success value: If symbol\_id is the ID of a valid terminal symbol that is expected at the current earleme, a number greater than zero. If symbol\_id is the ID of a valid terminal symbol that is not expected at the current earleme, or if symbol\_id is the ID of a valid symbol that is not a terminal, zero. Failure value: −2. It is a failure if symbol\_id is not the ID of a valid symbol.
  
  ### sub marpa\_r\_progress\_report\_reset
  
  ```
  sub marpa_r_progress_report_reset(
      Marpa::Marpa-Recognizer $r
  ) returns Int
  
  ```
  
  Resets the progress report. Assumes a report of the progress has already been initialized at some Earley set for recognizer r, with marpa\_r\_progress\_report\_start(). The reset progress report will be positioned before its first item. Success value: A non-negative value. Failure value: −2.
  
  ### sub marpa\_r\_progress\_report\_start
  
  ```
  sub marpa_r_progress_report_start(
      Marpa::Marpa-Recognizer $r,
      Marpa::Marpa-Earley-Set-ID $set_id
  ) returns Int
  
  ```
  
  Initializes a report of the progress at Earley set set\_id for recognizer r. If a progress report already exists, it is destroyed and its memory is freed. Initially, the progress report is positioned before its first item. If no Earley set with ID set\_id exists, marpa\_r\_progress\_report\_start() fails. The error code is MARPA-ERR-INVALID-LOCATION if set\_id is negative. The error code is MARPA-ERR-NO-EARLEY-SET-AT-LOCATION if set\_id is greater than the ID of the latest Earley set. Success value: the number of report items available. If the recognizer has not been started; if set\_id does not exist; or on other failure, −2. Failure value: −2.
  
  ### sub marpa\_r\_progress\_report\_finish
  
  ```
  sub marpa_r_progress_report_finish(
      Marpa::Marpa-Recognizer $r
  ) returns Int
  
  ```
  
  Destroys the report of the progress at Earley set set\_id for recognizer r, freeing the memory and other resources. It is often not necessary to call this method. Any previously existing progress report is destroyed automatically whenever a new progress report is started, and when the recognizer is destroyed. Success value: A non-negative value. Failure value: −2 if no progress report has been started, or on other failure.
  
  ### sub marpa\_r\_progress\_item
  
  ```
  sub marpa_r_progress_item(
      Marpa::Marpa-Recognizer $r,
      NativeCall::Types::Pointer[Int] $position,
      NativeCall::Types::Pointer[Marpa::Marpa-Earley-Set-ID] $origin
  ) returns Marpa::Marpa-Rule-ID
  
  ```
  
  This method allows access to the data for the next item of a progress report. If there are no more progress report items, it returns −1 as a termination indicator and sets the error code to MARPA-ERR-PROGRESS-REPORT-EXHAUSTED. Either the termination indicator, or the item count returned by marpa\_r\_progress\_report\_start(), can be used to determine when the last item has been seen. On success, the dot position is returned in the location pointed to by the position argument, and the origin is returned in the location pointed to by the origin argument. On failure, the locations pointed to by the position and origin arguments are unchanged. Success value: The rule ID of the next progress report item. If there are no more progress report items, −1. If either the position or the origin argument is NULL, or on other failure, −2. Failure value: −2.
  
  ### sub marpa\_b\_new
  
  ```
  sub marpa_b_new(
      Marpa::Marpa-Recognizer $r,
      Marpa::Marpa-Earley-Set-ID $earley_set_ID
  ) returns Marpa::Marpa-Bocage
  
  ```
  
  Creates a new bocage object, with a reference count of 1. The reference count of its parent recognizer object, r, is increased by 1. If earley\_set\_ID is −1, the Earley set at the current earleme is used, if there is one. If earley\_set\_ID is −1 and there is no Earley set at the current earleme; or if earley\_set\_ID is −1 and there is no parse ending at Earley set earley\_set\_ID, marpa\_b\_new() fails and the error code is set to MARPA-ERR-NO-PARSE. Success value: The new bocage object. Failure value: NULL.
  
  ### sub marpa\_b\_ref
  
  ```
  sub marpa_b_ref(
      Marpa::Marpa-Bocage $b
  ) returns Marpa::Marpa-Bocage
  
  ```
  
  Increases the reference count by 1. Not needed by most applications. Success value: $b. Failure value: NULL.
  
  ### sub marpa\_b\_unref
  
  ```
  sub marpa_b_unref(
      Marpa::Marpa-Bocage $b
  ) returns Mu
  
  ```
  
  Decreases the reference count by 1, destroying b once the reference count reaches zero. When b is destroyed, the reference count of its parent recognizer is decreased by 1. If this takes the reference count of the parent recognizer to zero, it too is destroyed. If the parent recognizer is destroyed, the reference count of its base grammar is decreased by 1. If this takes the reference count of the base grammar to zero, it too is destroyed.
  
  ### sub marpa\_b\_ambiguity\_metric
  
  ```
  sub marpa_b_ambiguity_metric(
      Marpa::Marpa-Bocage $b
  ) returns Int
  
  ```
  
  Returns an ambiguity metric. The metric is 1 is the parse is unambiguous. If the metric is 2 or greater, the parse is ambiguous. It was originally intended to have values greater than 2 be an cheaply computed estimate of the degree of ambiguity, but a satisfactory scheme for this has yet to be implemented. Success value: 1 if the bocage is not for an ambiguous parse; 2 or greater if the bocage is for an ambiguous parse. Failure value: −2.
  
  ### sub marpa\_b\_is\_null
  
  ```
  sub marpa_b_is_null(
      Marpa::Marpa-Bocage $b
  ) returns Int
  
  ```
  
  Success value: A number greater than or equal to 1 if the bocage is for a null parse; otherwise, 0. Failure value: −2.
  
  ### sub marpa\_o\_new
  
  ```
  sub marpa_o_new(
      Marpa::Marpa-Bocage $b
  ) returns Marpa::Marpa-Order
  
  ```
  
  Creates a new ordering object, with a reference count of 1. The reference count of its parent bocage object, b, is increased by 1. Success value: the new ordering object. Failure value: NULL.
  
  ### sub marpa\_o\_ref
  
  ```
  sub marpa_o_ref(
      Marpa::Marpa-Order $o
  ) returns Marpa::Marpa-Order
  
  ```
  
  Increases the reference count by 1. Not needed by most applications. Success value: o. Failure value: NULL.
  
  ### sub marpa\_o\_unref
  
  ```
  sub marpa_o_unref(
      Marpa::Marpa-Order $o
  ) returns Mu
  
  ```
  
  Decreases the reference count by 1, destroying o once the reference count reaches zero. Beginning with o's parent bocage, Libmarpa then proceeds up the chain of parent objects. Every time a child is destroyed, the reference count of its parent is decreased by 1. Every time the reference count of an object is decreased by 1, if that reference count is now zero, that object is destroyed. Libmarpa follows this chain of decrements and destructions as required, all the way back to the base grammar, if necessary.
  
  ### sub marpa\_o\_ambiguity\_metric
  
  ```
  sub marpa_o_ambiguity_metric(
      Marpa::Marpa-Order $o
  ) returns Int
  
  ```
  
  Returns an ambiguity metric. The metric is 1 is the parse is unambiguous. If the metric is 2 or greater, the parse is ambiguous. It was originally intended to have values greater than 2 be an cheaply computed estimate of the degree of ambiguity, but a satisfactory scheme for this has yet to be implemented. If the ordering is not already frozen, it will be frozen on return from marpa\_o\_ambiguity\_metric(). marpa\_o\_ambiguity\_metric() is considered an “accessor”, because it is assumed that the ordering is frozen when marpa\_o\_ambiguity\_metric() is called. Success value: 1 if the ordering is not for an ambiguous parse; 2 or greater if the ordering is for an ambiguous parse. Failure value: −2.
  
  ### sub marpa\_o\_is\_null
  
  ```
  sub marpa_o_is_null(
      Marpa::Marpa-Order $o
  ) returns Int
  
  ```
  
  Success value: A number greater than or equal to 1 if the ordering is for a null parse; otherwise, 0. Failure value: −2.
  
  ### sub marpa\_o\_high\_rank\_only\_set
  
  ```
  sub marpa_o_high_rank_only_set(
      Marpa::Marpa-Order $o,
      Int $flag
  ) returns Int
  
  ```
  
  These methods, respectively, set and query the “high rank only” flag of ordering o. A flag of 1 indicates that, when ranking, all choices should be discarded except those of the highest rank. A flag of 0 indicates that no choices should be discarded on the basis of their rank. A value of 1 is the default. The value of the “high rank only” flag has no effect unless ranking has been turned on using the marpa\_o\_rank() method. Success value: the value of the “high rank only” flag after the call. Failure value: −2.
  
  ### sub marpa\_o\_rank
  
  ```
  sub marpa_o_rank(
      Marpa::Marpa-Order $o
  ) returns Int
  
  ```
  
  By default, the ordering of parse trees is arbitrary. This method causes the ordering to be ranked according to the ranks of symbols and rules, the “null ranks high” flags of the rules, and the “high rank only” flag of the ordering. Once this method returns, the ordering is frozen. Success value: A non-negative value. Failure value: −2.
  
  ### sub marpa\_t\_new
  
  ```
  sub marpa_t_new(
      Marpa::Marpa-Order $o
  ) returns Marpa::Marpa-Tree
  
  ```
  
  Creates a new tree iterator, with a reference count of 1. The reference count of its parent ordering object, o, is increased by 1. When initialized, a tree iterator is positioned before the first parse tree. To position the tree iterator to the first parse, the application must call marpa\_t\_next(). Success value: A newly created tree. Failure value: NULL.
  
  ### sub marpa\_t\_ref
  
  ```
  sub marpa_t_ref(
      Marpa::Marpa-Tree $t
  ) returns Marpa::Marpa-Tree
  
  ```
  
  Increases the reference count by 1. Not needed by most applications. Success value: t. Failure value: NULL.
  
  ### sub marpa\_t\_unref
  
  ```
  sub marpa_t_unref(
      Marpa::Marpa