txt: ## dist_zef-raku-community-modules-Marpa.md
  ## Chunk 1 of 3
  [![Actions Status](https://github.com/raku-community-modules/Marpa/workflows/test/badge.svg)](https://github.com/raku-community-modules/Marpa/actions)
  
  # NAME
  
  Marpa - Raku interface to the libmarpa C library.
  
  # SYNOPSIS
  
  ```
  use Marpa;
  
  ```
  
  # DESCRIPTION
  
  Marpa is a Raku interface to the libmarpa C library.
  
  Marpa requires libmarpa to be present. I'd recommend installing from packages, or just look on the libmarpa website for install instructions.
  
  # AUTHOR
  
  Jeffrey Goff, aka DrForr
  
  Source can be located at: <https://github.com/raku-community-modules/Marpa> . Comments and Pull Requests are welcome.
  
  # COPYRIGHT AND LICENSE
  
  Copyright 2015 - 2018 Jeffrey Goff
  
  Copyright 2019 - 2022 Raku Community
  
  This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
  
  ### sub marpa\_check\_version
  
  ```
  sub marpa_check_version(
      Int $required_major,
      Int $required_minor,
      Int $required_micro
  ) returns Marpa-Error-Code
  
  ```
  
  Checks that the Marpa library in use is compatible with the given version. Generally you will pass in the constants MARPA-MAJOR-VERSION, MARPA-MINOR-VERSION, MARPA-MICRO-VERSION as the three arguments to this function; that produces a check that the library in use is compatible with the version of Libmarpa the application or module was compiled against. Compatibility is defined by two things: first the version of the running library is newer than the version required\_major.required\_minor.required\_micro. Second the running library must be binary compatible with the version required\_major.required\_minor.required\_micro (same major version.) Success value: MARPA-ERR-NONE if the Marpa library is compatible with the requested version. Failure value: If the library is not compatible, one of the following is returned, indicating the nature of the mismatch: MARPA-ERR-MAJOR-VERSION-MISMATCH, MARPA-ERR-MINOR-VERSION-MISMATCH MARPA-ERR-MICRO-VERSION-MISMATCH
  
  ### sub marpa\_version
  
  ```
  sub marpa_version(
      NativeCall::Types::Pointer[Int] $version
  ) returns Marpa-Error-Code
  
  ```
  
  Returns the version number in version, which must have room for three int's. Success value: A non-negative number. Failure value: −2.
  
  ### sub marpa\_c\_init
  
  ```
  sub marpa_c_init(
      NativeCall::Types::Pointer[Marpa::Marpa-Config] $config
  ) returns Int
  
  ```
  
  Initialize the config information to “safe” default values. Unspecified behavior will result if an initialized configuration is used to create a grammar. Success value: A non-negative value. Failure value: Always succeeds.
  
  ### sub marpa\_c\_error
  
  ```
  sub marpa_c_error(
      NativeCall::Types::Pointer[Marpa::Marpa-Config] $config,
      NativeCall::Types::Pointer[Str] $p_error_string
  ) returns Marpa-Error-Code
  
  ```
  
  Error codes are usually kept in the base grammar, which leaves marpa\_g\_new() no place to put its error code on failure. Objects of the Marpa-Config class provide such a place. p\_error\_string is reserved for use by the internals. Applications should set it to NULL. Success value: The error code in config. Failure value: Always succeeds.
  
  ### sub marpa\_g\_new
  
  ```
  sub marpa_g_new(
      NativeCall::Types::Pointer[Marpa::Marpa-Config] $configuration
  ) returns Marpa::g
  
  ```
  
  Creates a new grammar time object. The returned grammar object is not yet precomputed, and will have no symbols and rules. Its reference count will be 1. Unless the application calls marpa\_c\_error, Libmarpa will not reference the location pointed to by the configuration argument after marpa\_g\_new returns. The configuration argument may be NULL, but if it is, there will be no way to determine the error code on failure. Success value: the grammar object. Failure value: NULL, and the error code is set in configuration.
  
  ### sub marpa\_g\_force\_valued
  
  ```
  sub marpa_g_force_valued(
      Marpa::g $g
  ) returns Int
  
  ```
  
  It is recommended that this call be made immediately after the grammar constructor. It turns off a deprecated feature. The marpa\_g\_force\_valued forces all the symbols in a grammar to be “valued”. The opposite of a valued symbol is one about whose value you do not care. This distinction has been made in the past in hope of gaining efficiencies at evaluation time. Current thinking is that the gains do not repay the extra complexity. Success value: a non-negative integer. Failure value: a negative integer.
  
  ### sub marpa\_g\_ref
  
  ```
  sub marpa_g_ref(
      Marpa::Marpa-Grammar $g
  ) returns Marpa::g
  
  ```
  
  Increases the reference count by 1. Not needed by most applications. Success value: the grammar object it was called with. Failure value: NULL.
  
  ### sub marpa\_g\_unref
  
  ```
  sub marpa_g_unref(
      Marpa::g $g
  ) returns Mu
  
  ```
  
  Decreases the reference count by 1, destroying g once the reference count reaches zero.
  
  ### sub marpa\_g\_start\_symbol
  
  ```
  sub marpa_g_start_symbol(
      Marpa::g $g
  ) returns Marpa::Marpa-Symbol-ID
  
  ```
  
  Returns current value of the start symbol of grammar g. The value is that specified in the marpa\_g\_start\_symbol\_set() call, if there has been one. Success value: The new start symbol. Failure value: -1 if there is no start symbol, otherwise -2.
  
  ### sub marpa\_g\_start\_symbol\_set
  
  ```
  sub marpa_g_start_symbol_set(
      Marpa::g $g,
      Marpa::Marpa-Symbol-ID $sym_id
  ) returns Marpa::Marpa-Symbol-ID
  
  ```
  
  Sets the start symbol of grammar g to symbol id. Success value: The ID of the new start symbol. Failure value: -1 if sym\_id is well-formed but there is no such symbol, otherwise -2.
  
  ### sub marpa\_g\_highest\_symbol\_id
  
  ```
  sub marpa_g_highest_symbol_id(
      Marpa::g $g
  ) returns Int
  
  ```
  
  Success value: the numerically largest symbol ID of $g. Failure value: -2.
  
  ### sub marpa\_g\_symbol\_is\_accessible
  
  ```
  sub marpa_g_symbol_is_accessible(
      Marpa::g $g,
      Marpa::Marpa-Symbol-ID $sym_id
  ) returns Int
  
  ```
  
  A symbol is accessible if it can be reached from the start symbol. Success value: 1 if symbol sym\_id is accessible, 0 if not. If sym\_id is well-formed, but there is no such symbol, −1. If the grammar is not precomputed, or on other failure, −2. Failure value: -2.
  
  ### sub marpa\_g\_symbol\_is\_nullable
  
  ```
  sub marpa_g_symbol_is_nullable(
      Marpa::g $g,
      Marpa::Marpa-Symbol-ID $sym_id
  ) returns Int
  
  ```
  
  A symbol is nullable if it sometimes produces the empty string. A nulling symbol is always a nullable symbol, but not all nullable symbols are nulling symbols. Success value: 1 if symbol sym\_id is nullable, 0 if not. If sym\_id is well-formed, but there is no such symbol, −1. If the grammar is not precomputed, or on other failure, −2. Failure value: -2.
  
  ### sub marpa\_g\_symbol\_is\_nulling
  
  ```
  sub marpa_g_symbol_is_nulling(
      Marpa::g $g,
      Marpa::Marpa-Symbol-ID $sym_id
  ) returns Int
  
  ```
  
  A symbol is nulling if it always produces the empty string. Success value: 1 if symbol sym\_id is nulling, 0 if not. If sym\_id is well-formed, but there is no such symbol, −1. If the grammar is not precomputed, or on other failure, −2. Failure value: -2.
  
  ### sub marpa\_g\_symbol\_is\_productive
  
  ```
  sub marpa_g_symbol_is_productive(
      Marpa::g $g,
      Marpa::Marpa-Symbol-ID $sym_id
  ) returns Int
  
  ```
  
  A symbol is productive if it can produce a string of terminals. All nullable symbols are considered productive. Success value: 1 if symbol sym\_id is productive, 0 if not. If sym\_id is well-formed, but there is no such symbol, −1. If the grammar is not precomputed, or on other failure, −2. Failure value: -2.
  
  ### sub marpa\_g\_symbol\_is\_start
  
  ```
  sub marpa_g_symbol_is_start(
      Marpa::g $g,
      Marpa::Marpa-Symbol-ID $sym_id
  ) returns Int
  
  ```
  
  This return value of this call indicates whether sym\_id is the start symbol. Success value: 1 if sym\_id is the start symbol. 0 if sym\_id is not the start symbol, either because the start symbol is different from sym\_id, or because the start symbol has not been set yet. Failure value: -1 if sym\_id is well-formed, but there is no such symbol. -2 on other failure.
  
  ### sub marpa\_g\_symbol\_is\_terminal\_set
  
  ```
  sub marpa_g_symbol_is_terminal_set(
      Marpa::g $g,
      Marpa::Marpa-Symbol-ID $sym_id,
      Int $value
  ) returns Int
  
  ```
  
  These methods, respectively, set and query the “terminal status” of a symbol. To be used as an input symbol in the marpa\_r\_alternative() method, a symbol must be a terminal. This function flags symbol sym\_id as a terminal if value is 1, or flags it as a non-terminal if value is 0. Once set to a value with the marpa\_g\_symbol\_is\_terminal\_set() method, the terminal status of a symbol is “locked” at that value. A subsequent call to marpa\_g\_symbol\_is\_terminal\_set() that attempts to change the terminal status of sym\_id to a value different from its current one will fail. The error code will be MARPA-ERR-TERMINAL-IS-LOCKED. By default, a symbol is a terminal if and only if it does not appear on the LHS of any rule. An attempt to flag a nulling symbol as a terminal will cause a failure, but this is not necessarily detected before precomputation. Success returns: When successful, these methods return 1 if symbol sym\_id is a terminal symbol after the call, 0 otherwise. Failure returns: If sym\_id is well-formed, but there is no such symbol, −1. On all other failures, −2. Other failures include when value is not 0 or 1; when the terminal status is locked and value is different from its current value; and, in the case of marpa\_g\_symbol\_is\_terminal\_set(), when the grammar g is precomputed.
  
  ### sub marpa\_g\_symbol\_new
  
  ```
  sub marpa_g_symbol_new(
      Marpa::g $g
  ) returns Marpa::Marpa-Symbol-ID
  
  ```
  
  Creates a new symbol. The symbol ID will be a non-negative integer. Success value: The ID of a new symbol. Failure value: −2.
  
  ### sub marpa\_g\_highest\_rule\_id
  
  ```
  sub marpa_g_highest_rule_id(
      Marpa::g $g
  ) returns Int
  
  ```
  
  Success value: The ID of the numerically largest rule ID of $g. Failure value: −2.
  
  ### sub marpa\_g\_rule\_is\_accessible
  
  ```
  sub marpa_g_rule_is_accessible(
      Marpa::g $g,
      Marpa::Marpa-Rule-ID $rule_id
  ) returns Int
  
  ```
  
  A rule is accessible if it can be reached from the start symbol. A rule is accessible if and only if its LHS symbol is accessible. The start rule is always an accessible rule. Success value: 1 if rule rule\_id is accessible, 0 if not. If rule\_id is well-formed, but there is no such rule, −1. If the grammar is not precomputed, or on other failure, −2. Failure value: −2.
  
  ### sub marpa\_g\_rule\_is\_nullable
  
  ```
  sub marpa_g_rule_is_nullable(
      Marpa::g $g,
      Marpa::Marpa-Rule-ID $ruleid
  ) returns Int
  
  ```
  
  A rule is nullable if it sometimes produces the empty string. A nulling rule is always a nullable rule, but not all nullable rules are nulling rules. Success value: 1 if rule ruleid is nullable, 0 if not. If rule\_id is well-formed, but there is no such rule, −1. If the grammar is not precomputed, or on other failure, −2. Failure value: −2.
  
  ### sub marpa\_g\_rule\_is\_nulling
  
  ```
  sub marpa_g_rule_is_nulling(
      Marpa::g $g,
      Marpa::Marpa-Rule-ID $ruleid
  ) returns Int
  
  ```
  
  A rule is nulling if it always produces the empty string. Success value: 1 if rule ruleid is nulling, 0 if not. If rule\_id is well-formed, but there is no such rule, −1. If the grammar is not precomputed, or on other failure, −2. Failure value: −2.
  
  ### sub marpa\_g\_rule\_is\_loop
  
  ```
  sub marpa_g_rule_is_loop(
      Marpa::g $g,
      Marpa::Marpa-Rule-ID $rule_id
  ) returns Int
  
  ```
  
  A rule is a loop rule if it non-trivially produces the string of length one which consists only of its LHS symbol. Such a derivation takes the parse back to where it started, hence the term “loop”. “Non-trivially” means the zero-step derivation does not count — the derivation must have at least one step. The presence of a loop rule makes a grammar infinitely ambiguous, and applications will typically want to treat them as fatal errors. But nothing forces an application to do this, and Marpa will successfully parse and evaluate grammars with loop rules. Success value: 1 if rule rule\_id is a loop rule, 0 if not. If rule\_id is well-formed, but there is no such rule, −1. If the grammar is not precomputed, or on other failure, −2. Failure value: −2.
  
  ### sub marpa\_g\_rule\_is\_productive
  
  ```
  sub marpa_g_rule_is_productive(
      Marpa::g $g,
      Marpa::Marpa-Rule-ID $rule_id
  ) returns Int
  
  ```
  
  A rule is productive if it can produce a string of terminals. An rule is productive if and only if all the symbols on its RHS are productive. The empty string counts as a string of terminals, so that a nullable rule is always a productive rule. For that same reason, an empty rule is considered productive. Success value: 1 if rule rule\_id is productive, 0 if not. If rule\_id is well-formed, but there is no such rule, −1. If the grammar is not precomputed, or on other failure, −2. Failure value: −2.
  
  ### sub marpa\_g\_rule\_length
  
  ```
  sub marpa_g_rule_length(
      Marpa::g $g,
      Marpa::Marpa-Rule-ID $rule_id
  ) returns Int
  
  ```
  
  The length of a rule is the number of symbols on its RHS. Success value: The length of rule $rule\_id. Failure value: −2.
  
  ### sub marpa\_g\_rule\_lhs
  
  ```
  sub marpa_g_rule_lhs(
      Marpa::g $g,
      Marpa::Marpa-Rule-ID $rule_id
  ) returns Marpa::Marpa-Symbol-ID
  
  ```
  
  Success value: The LHS symbol of rule rule\_id. If rule\_id is well-formed, but there is no such rule, −1. Failure value: −2.
  
  ### sub marpa\_g\_rule\_new
  
  ```
  sub marpa_g_rule_new(
      Marpa::g $g,
      Marpa::Marpa-Symbol-ID $lhs_id,
      NativeCall::Types::Pointer[Marpa::Marpa-Symbol-ID] $rhs_ids,
      Int $length
  ) returns Marpa::Marpa-Rule-ID
  
  ```
  
  Creates a new external BNF rule in grammar g. The ID of the new rule will be a non-negative integer, which will be unique to that rule. In addition to BNF rules, Marpa also allows sequence rules, which are created by another method: marpa\_g\_sequence\_new(). Sequence rules and BNF rules are numbered in the same series, so that a BNF rule will never have the same rule ID as a sequence rule, and vice versa. The LHS symbol is lhs\_id, and there are length symbols on the RHS. The RHS symbols are in an array pointed to by rhs\_ids. Possible failures, with their error codes, include: MARPA-ERR-SEQUENCE-LHS-NOT-UNIQUE: The LHS symbol is the same as that of a sequence rule. MARPA-ERR-DUPLICATE-RULE: The new rule would duplicate another BNF rule. Another BNF rule is considered the duplicate of the new one, if its LHS symbol is the same as symbol lhs\_id, if its length is the same as length, and if its RHS symbols match one for one those in the array of symbols rhs\_ids. Success value: the ID of new external rule. Failure value: −2.
  
  ### sub marpa\_g\_rule\_rhs
  
  ```
  sub marpa_g_rule_rhs(
      Marpa::g $g,
      Marpa::Marpa-Rule-ID $rule_id,
      int $ix
  ) returns Marpa::Marpa-Symbol-ID
  
  ```
  
  Returns the ID of the symbol in position ix in the RHS of rule rule\_id. The RHS position, ix, is zero-based. Success value: The ID of the symbol in position ix on the rules RHS. If rule\_id is well-formed, but there is no such rule, −1. If ix is greater than or equal to the length of the rule, or on other failure, −2. Failure value: −2.
  
  ### sub marpa\_g\_rule\_is\_proper\_separation
  
  ```
  sub marpa_g_rule_is_proper_separation(
      Marpa::g $g,
      Marpa::Marpa-Rule-ID $rule_id
  ) returns Int
  
  ```
  
  Success returns: marpa\_g\_rule\_is\_proper\_separation() succeeds if and only if rule\_id is valid. If rule rule\_id is a sequence rule where the proper separation flag is set, returns 1. On other success, including the case where rule rule\_id is not a sequence rule, returns 0. Failure returns: If rule\_id is well-formed, but there is no such rule, returns −1. On other failure, −2.
  
  ### sub marpa\_g\_sequence\_min
  
  ```
  sub marpa_g_sequence_min(
      Marpa::g $g,
      Marpa::Marpa-Rule-ID $rule_id
  ) returns Int
  
  ```
  
  Returns the mininum length of a sequence rule. This accessor can be also be used to test whether or not a rule is a sequence rule. −1 is returned if and only if the rule is valid but not a sequence rule. Success value: If rule rule\_id is a sequence rule, its minimum length. If rule rule\_id is valid, but is not the rule ID of sequence rule, −1. If rule\_id is well-formed, but there is no such rule, or on other failure, −2. Failure value: −2.
  
  ### sub marpa\_g\_sequence\_new
  
  ```
  sub marpa_g_sequence_new(
      Marpa::g $g,
      Marpa::Marpa-Symbol-ID $lhs_id,
      Marpa::Marpa-Symbol-ID $rhs_id,
      Marpa::Marpa-Symbol-ID $separator_id,
      Int $min,
      Int $flags
  ) returns Marpa::Marpa-Rule-ID
  
  ```
  
  Adds a new sequence rule to grammar g. The ID of the new sequence rule will be a non-negative integer, which is unique to that rule. Sequence rules and BNF rules are numbered in the same series, so that a BNF rule will never have the same rule ID as a sequence rule, and vice versa. The sequence is lhs\_id, and the item to be repeated in the sequence is rhs\_id. The sequence must be repeated at least min times, where min is 0 or 1. If separator\_id is non-negative, it is a separator symbol. If flags & MARPA-PROPER-SEPARATION is non-zero, separation is “proper”, that is, a trailing separator is not allowed. The term proper is based on the idea that properly-speaking, separators should actually separate items. Some higher-level Marpa interfaces offer the ability to discard separators in the semantics, and in fact will do this by default. At the Libmarpa level, sequences always “keep separators”. It is up to the programmer to arrange to discard separators, if that is what is desired. The sequence RHS, or item, is restricted to a single symbol, and that symbol cannot be nullable. If separator\_id is a symbol, it also cannot be a nullable symbol. Nullables on the RHS of sequences are restricted because they lead to highly ambiguous grammars. Grammars of this kind are allowed by Libmarpa, but they must be expressed using BNF rules, not sequence rules. This is for two reasons: First, sequence optimizations would not work in the presence of nullables. Second, since it is not completely clear what an application intends when it asks for a sequence of identical items, some of which are nullable, the user's intent can be more clearly expressed directly in BNF. The LHS symbol cannot be the LHS of any other rule, whether a BNF rule or a sequence rule. On an attempt to create an sequence rule with a duplicate LHS, marpa\_g\_sequence\_new() fails, setting the error code to MARPA-ERR-SEQUENCE-LHS-NOT-UNIQUE. Sequence rules do not add to the classes of grammar parsed by Libmarpa — a sequence can always be written as BNF rules. When a rule is created with the marpa\_g\_sequence\_new() method, Libmarpa will understand that it is a sequence, and will optimize accordingly. The speedup is often considerable. Success value: The ID of the external rule. Failure value: −2.
  
  ### sub marpa\_g\_sequence\_separator
  
  ```
  sub marpa_g_sequence_separator(
      Marpa::g $g,
      Marpa::Marpa-Rule-ID $rule_id
  ) returns Int
  
  ```
  
  Success value: If rule rule\_id is a sequence rule, its separator. If rule rule\_id is a sequence rule, but there is no separator, −1. If rule\_id is not a sequence rule, does not exist or is not well-formed; or on other failure, −2. Failure value: −2.
  
  ### sub marpa\_g\_symbol\_is\_counted
  
  ```
  sub marpa_g_symbol_is_counted(
      Marpa::g $g,
      Marpa::Marpa-Symbol-ID $sym_id
  ) returns Int
  
  ```
  
  A symbol is counted if it appears on the RHS of a sequence rule, or if it is used as the separator symbol of a sequence rule. Success return: Returns 1 if symbol sym\_id is counted, 0 if not. Failure return: If sym\_id is well-formed, but there is no such symbol, −1. If sym\_id is not well-formed, and on other failure, −2.
  
  ### sub marpa\_g\_rule\_rank\_set
  
  ```
  sub marpa_g_rule_rank_set(
      Marpa::g $g,
      Marpa::Marpa-Rule-ID $rule_id,
      Marpa::Marpa-Rank $rank
  ) returns Marpa::Marpa-Rank
  
  ```
  
  These methods, respectively, set and query the rank of a rule rule\_id. When rule\_id is created, its rank initialized to the default rank of the grammar. Initially, the default rank of the grammar is 0. Methods to reset the grammar's default rank are currently in the experimental stage. Success value: Returns the rank after the call, and sets the error code to MARPA-ERR-NONE. On failure, returns −2, and sets the error code to an appropriate value, which will never be MARPA-ERR-NONE. Note that when the rank is −2, the error code is the only way to distinguish success from failure. The error code can be determined by using the marpa\_g\_error() call. Failure value: −2.
  
  ### sub marpa\_g\_rule\_null\_high\_set
  
  ```
  sub marpa_g_rule_null_high_set(
      Marpa::g $g,
      Marpa::Marpa-Rule-ID $rule_id,
      Int $flag
  ) returns Int
  
  ```
  
  These methods, respectively, set and query the “null ranks high” setting of the rule rule\_id. The “null ranks high” setting is either 0 or 1. When rule\_id is created, its “null ranks high” setting is initialized to 0. The “null ranks high” setting affects the ranking of rules with properly nullable symbols on their right hand side. If a rule has properly nullable symbols on its RHS, each instance in which it appears in a parse will have a pattern of nulled and non-nulled symbols. Such a pattern is called a “null variant”. If the “null ranks high” setting is 0 (the default), nulled symbols rank low. If the “null ranks high” setting is 1, nulled symbols rank high. Ranking of a null variants is done from left-to-right. The marpa\_g\_rule\_null\_high\_set() method will return failure after the grammar has been precomputed. If there is no other cause of failure, the marpa\_g\_rule\_null\_high() method succeeds on both precomputed and unprecomputed grammars. Success value: The value of the “null ranks high” flag after the call. Failure value: If rule\_id is well-formed, but there is no such rule, −1. On all other failures, −2.
  
  ### sub marpa\_g\_completion\_symbol\_activate
  
  ```
  sub marpa_g_completion_symbol_activate(
      Marpa::g $g,
      Marpa::Marpa-Symbol-ID $sym_id,
      Int $reactivate
  ) returns Int
  
  ```
  
  Allows the user to deactivate and reactivate symbol completion events in the grammar. When a recognizer is created, the activation status of each of its events is initialized to the activation status of that event in the base grammar. If reactivate is zero, the event is deactivated in the grammar. If reactivate is one, the event is activated in the grammar. 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. The activation status of a completion event in the grammar can only be changed if the symbol is marked as a completion event symbol in the grammar, and before the grammar is precomputed. However, if a symbol is marked as a completion event symbol in the recognizer, the completion event can be deactivated and reactivated in the recognizer. Success cases: On success, the method returns the value of reactivate. The method succeeds trivially if the symbol is already set as indicated by reactivate. Failure cases: 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\_g\_nulled\_symbol\_activate
  
  ```
  sub marpa_g_nulled_symbol_activate(
      Marpa::g $g,
      Marpa::Marpa-Symbol-ID $sym_id,
      Int $reactivate
  ) returns Int
  
  ```
  
  Allows the user to deactivate and reactivate symbol nulled events in the grammar. When a recognizer is created, the activation status of each of its events is initialized to the activation status of that event in the base grammar. If reactivate is zero, the event is deactivated in the grammar. If reactivate is one, the event is activated in the grammar. 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. The activation status of a nulled event in the grammar can only be changed if the symbol is marked as a nulled event symbol in the grammar, and before the grammar is precomputed. However, if a symbol is marked as a nulled event symbol in the recognizer, the nulled event can be deactivated and reactivated in the recognizer. Success value: On success, 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 nulled event for sym\_id cannot be set as indicated by reactivate, the method fails. On failure, −2 is returned.
  
  ### sub marpa\_g\_prediction\_symbol\_activate
  
  ```
  sub marpa_g_prediction_symbol_activate(
      Marpa::g $g,
      Marpa::Marpa-Symbol-ID $sym_id,
      Int $reactivate
  ) returns Int
  
  ```
  
  Allows the user to deactivate and reactivate symbol prediction events in the grammar. When a recognizer is created, the activation status of each of its events is initialized to the activation status of that event in the base grammar. If reactivate is zero, the event is deactivated in the grammar. If reactivate is one, the event is activated in the grammar. 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. The activation status of a prediction event in the grammar can only be changed if the symbol is marked as a prediction event symbol in the grammar, and before the grammar is precomputed. However, if a symbol is marked as a prediction event symbol in the recognizer, the prediction event can be deactivated and reactivated in the recognizer. Success cases: On success, the method returns the value of reactivate. The method succeeds trivially if the symbol is already set as indicated by reactivate. Failure cases: If the active status of the prediction event for sym\_id cannot be set as indicated by reactivate, the method fails. On failure, −2 is returned.
  
  ### sub marpa\_g\_symbol\_is\_completion\_event
  
  ```
  sub marpa_g_symbol_is_completion_event(
      Marpa::g $g,
      Marpa::Marpa-Symbol-ID $sym_id
  ) returns Int
  
  ```
  
  Libmarpa can be set up to generate an MARPA-EVENT-SYMBOL-COMPLETED event whenever the symbol is completed. A symbol is said to be completed when a non-nulling rule with that symbol on its LHS is completed. For completion events to occur, the symbol must be marked as a completion event symbol. The marpa\_g\_symbol\_is\_completion\_event\_set() function marks symbol sym\_id as a completion event symbol if value is 1, and unmarks it it as a completion event symbol if value is 0. The marpa\_g\_symbol\_is\_completion\_event() method returns the current value of the completion event marking for symbol sym\_id. Marking a completion event sets its activation status to on. Unmarking a completion event sets its activation status to off. The completion event marking cannot be changed once the grammar is precomputed. If a completion event is marked, its activation status can be changed using the marpa\_g\_completion\_symbol\_activate() method. Note that, if a symbol is marked as a completion event symbol in the recognizer, its completion event can be deactivated and reactivated in the recognizer. Nulled rules and symbols will never cause completion events. Nullable symbols may be marked as completion event symbols, but this will have an effect only when the symbol is not nulled. Nulling symbols may be marked as completion event symbols, but no completion events will ever be generated for a nulling symbol. Note that this implies at no completion event will ever be generated at earleme 0, the start of parsing. Success value: On success, 1 if symbol sym\_id is a completion event symbol after the call, 0 otherwise. Failure value: 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\_symbol\_is\_nulled\_event
  
  ```
  sub marpa_g_symbol_is_nulled_event(
      Marpa::g $g,
      Marpa::Marpa-Symbol-ID $sym_id
  ) returns Int
  
  ```
  
  Libmarpa can set up to generate an MARPA-EVENT-SYMBOL-NULLED event whenever the symbol is nulled. A symbol is said to be nulled when a zero length instance of that symbol is recognized. For nulled events to occur, the symbol must be marked as a nulled event symbol. The marpa\_g\_symbol\_is\_nulled\_event\_set() function marks symbol sym\_id as a nulled event symbol if value is 1, and unmarks it it as a nulled event symbol if value is 0. The marpa\_g\_symbol\_is\_nulled\_event() method returns the current value of the nulled event marking for symbol sym\_id. Marking a nulled event sets its activation status to on. Unmarking a nulled event sets its activation status to off. The nulled event marking cannot be changed once the grammar is precomputed. If a nulled event is marked, its activation status can be changed using the marpa\_g\_nulled\_symbol\_activate() method. Note that, if a symbol is marked as a nulled event symbol in the recognizer, its nulled event can be deactivated and reactivated in the recognizer. As a reminder, a symbol instance is a symbol at a specific location in the input, and with a specific length. Also, whenever a nulled symbol instance is recognized at a location, it is acceptable at that location, and vice versa. When a symbol instance is recognized at a location, it will generate a nulled event or a prediction event, but never both. A symbol instance of zero length, when recognized at a location, generates a nulled event at that location, and does not generate a completion event. A symbol instance of non-zero length, when acceptable at a location, generates a completion event at that location, and does not generate a nulled event. When a symbol instance is acceptable at a location, it will generate a nulled event or a prediction event, but never both. A symbol instance of zero length, when acceptable at a location, generates a nulled event at that location, and does not generate a prediction event. A symbol instance of non-zero length, when acceptable at a location, generates a prediction event at that location, and does not generate a nulled event. While it is not possible for a symbol instance to generate both a nulled event and a completion event at a location, it is quite possible that a symbol might generate both kinds of event at that location. This is because multiple instances of the same symbol may be recognized at a given location, and these instances will have different lengths. If one instance is recognized at a given location as zero length and a second, non-zero-length, instance is recognized at the same location, the first will generate only nulled events, while the second will generate only completion events. For similar reasons, while a symbol instance will never generate both a null event and a prediction event at a location, multiple instances of the same symbol may do so. Zero length derivations can be ambiguous. When a zero length symbol is recognized, all of its zero-length derivations are also considered to be recognized. Success: On success, 1 if symbol sym\_id is a nulled 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\_symbol\_is\_prediction\_event
  
  ```
  sub marpa_g_symbol_is_prediction_event(
      Marpa::g $g,
      Marpa::Marpa-Symbol-ID $sym_id
  ) returns Int
  
  ```
  
  Libmarpa can be set up to generate a MARPA-EVENT-SYMBOL-PREDICTED event when a non-nulled symbol is predicted. A non-nulled symbol is said to be predicted when a instance of it is acceptable at the current earleme according to the grammar. Nulled symbols do not generate predictions. For predicted events to occur, the symbol must be marked as a predicted event symbol. The marpa\_g\_symbol\_is\_predicted\_event\_set() function marks symbol sym\_id as a predicted event symbol if value is 1, and unmarks it it as a predicted event symbol if value is 0. The marpa\_g