### ----------------------------------------------------
### -- Marpa
### -- Licenses: Artistic-2.0
### -- Authors: 
### -- File: README.md
### ----------------------------------------------------
### -- Chunk 3 of 3
 number of parse trees traversed so far. The count includes the current iteration of the tree, so that a value of 0 indicates that the tree iterator is at its initialized position, before the first parse tree. Success value: The number of parses traversed so far. Failure value: Always succeeds.

### sub marpa_v_new

```raku
sub marpa_v_new(
    Marpa::Marpa-Tree $t
) returns Marpa::Marpa-Value
```

Creates a new valuator. The parent object of the new valuator will be the tree iterator t, and the reference count of the new valuator will be 1. The reference count of t is increased by 1. The parent tree iterator is “paused”, so that the tree iterator cannot move on to a new parse tree until the valuator is destroyed. Many valuators of the same parse tree can exist at once. A tree iterator is “unpaused” when all of the valuators of that tree iterator are destroyed. Success value: The newly created valuator. Failure value: NULL.

### sub marpa_v_ref

```raku
sub marpa_v_ref(
    Marpa::Marpa-Value $v
) returns Marpa::Marpa-Value
```

Increases the reference count by 1. Not needed by most applications. Success value: v. Failure value: NULL.

### sub marpa_v_unref

```raku
sub marpa_v_unref(
    Marpa::Marpa-Value $v
) returns Mu
```

Decreases the reference count by 1, destroying v once the reference count reaches zero. Beginning with v's parent tree, 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_v_step

```raku
sub marpa_v_step(
    Marpa::Marpa-Value $v
) returns Marpa::Marpa-Step-Type
```

This method “steps through” the valuator. The return value is a Marpa-Step_Type, an integer which indicates the type of step. How the application is expected to act on each step is described below. See Valuator steps by type. When the iteration through the steps is finished, marpa_v_step returns MARPA-STEP-INACTIVE. Success value: The type of the step to be performed. This will always be a non-negative number. Failure value: −2.

### sub marpa_g_event

```raku
sub marpa_g_event(
    Marpa::g $g,
    NativeCall::Types::Pointer[Marpa::Marpa-Event] $event,
    Int $ix
) returns Marpa-Event-Code
```

On success, the type of the ix'th event is returned and the data for the ix'th event is placed in the location pointed to by event. Event indexes are in sequence. Valid events will be in the range from 0 to n, where n is one less than the event count. The event count can be queried using the marpa_g_event_count() method. Success value: The type of event ix. If there is no ix'th event, if ix is negative, or on other failure, −2. Failure value: −2. The locations pointed to by event are not changed.

### sub marpa_g_event_count

```raku
sub marpa_g_event_count(
    Marpa::g $g
) returns Int
```

Success value: The number of events. Failure value: −2.

### sub marpa_g_error

```raku
sub marpa_g_error(
    Marpa::g $g,
    NativeCall::Types::Pointer[Str] $p_error_string
) returns Marpa-Error-Code
```

When a method fails, this method allows the application to read the error code. p_error_string is reserved for use by the internals. Applications should set it to NULL. Success value: The last error code from a Libmarpa method. Failure value: Always succeeds.

### sub marpa_g_error_clear

```raku
sub marpa_g_error_clear(
    Marpa::g $g
) returns Marpa-Error-Code
```

Sets the error code to MARPA-ERR-NONE. Not often used, but now and then it can be useful to force the error code to a known state. Success value: MARPA-ERR-NONE. Failure value: Always succeeds.

### sub marpa_g_default_rank_set

```raku
sub marpa_g_default_rank_set(
    Marpa::g $g,
    Marpa::Marpa-Rank $rank
) returns Marpa::Marpa-Rank
```

These methods, respectively, set and query the default rank of the grammar. When a grammar is created, the default rank is 0. When rules and symbols are created, their rank is the default rank of the grammar. Changing the grammar's default rank does not affect those rules and symbols already created, only those that will be created. This means that the grammar's default rank can be used to, in effect, assign ranks to groups of rules and symbols. Applications may find this behavior useful. 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_symbol_rank_set

```raku
sub marpa_g_symbol_rank_set(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $sym_id,
    Marpa::Marpa-Rank $rank
) returns Marpa::Marpa-Rank
```

These methods, respectively, set and query the rank of a symbol sym_id. When sym_id is created, its rank initialized to the default rank of the grammar. 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_zwa_new

```raku
sub marpa_g_zwa_new(
    Marpa::g $g,
    Int $default_value
) returns Marpa::Marpa-Assertion-ID
```

On success, returns previous default value of the assertion.

### sub marpa_r_zwa_default_set

```raku
sub marpa_r_zwa_default_set(
    Marpa::Marpa-Recognizer $r,
    Marpa::Marpa-Assertion-ID $zwaid,
    Int $default_value
) returns Int
```

Changes default value to default_value. On success, returns previous default value of the assertion.

### sub marpa_g_symbol_is_valued_set

```raku
sub marpa_g_symbol_is_valued_set(
    Marpa::g $g,
    Marpa::Marpa-Symbol-ID $symbol_id,
    Int $value
) returns Int
```

These methods, respectively, set and query the “valued status” of a symbol. Once set to a value with the marpa_g_symbol_is_valued_set() method, the valued status of a symbol is “locked” at that value. It cannot thereafter be changed. Subsequent calls to marpa_g_symbol_is_valued_set() for the same sym_id will fail, leaving sym_id's valued status unchanged, unless value is the same as the locked-in value. Success value: 1 if the symbol symbol_id is valued after the call, 0 if not. If the valued status is locked and value is different from the current status, −2. If value is not 0 or 1; or on other failure, −2. Failure value: −2.

### sub marpa_v_symbol_is_valued_set

```raku
sub marpa_v_symbol_is_valued_set(
    Marpa::Marpa-Value $v,
    Marpa::Marpa-Symbol-ID $sym_id,
    Int $status
) returns Int
```

These methods, respectively, set and query the valued status of symbol sym_id. marpa_v_symbol_is_valued_set() will set the valued status to the value of its status argument. A valued status of 1 indicates that the symbol is valued. A valued status of 0 indicates that the symbol is unvalued. If the valued status is locked, an attempt to change to a status different from the current one will fail (error code MARPA-ERR-VALUED-IS-LOCKED). Success value: The valued status after the call. If value is not either 0 or 1, or on other failure, −2. Failure value: −2.

### sub marpa_v_rule_is_valued_set

```raku
sub marpa_v_rule_is_valued_set(
    Marpa::Marpa-Value $v,
    Marpa::Marpa-Rule-ID $rule_id,
    Int $status
) returns Int
```

These methods, respectively, set and query the valued status for the LHS symbol of rule rule_id. marpa_v_rule_is_valued_set() sets the valued status to the value of its status argument. A valued status of 1 indicates that the symbol is valued. A valued status of 0 indicates that the symbol is unvalued. If the valued status is locked, an attempt to change to a status different from the current one will fail (error code MARPA-ERR-VALUED-IS-LOCKED). Rules have no valued status of their own. The valued status of a rule is always that of its LHS symbol. These methods are conveniences — they save the application the trouble of looking up the rule's LHS. Success value: The valued status of the rule rule_id's LHS symbol after the call. If value is not either 0 or 1, or on other failure, −2. Failure value: −2.

### sub marpa_v_valued_force

```raku
sub marpa_v_valued_force(
    Marpa::Marpa-Value $v
) returns Int
```

This methods locks the valued status of all symbols to 1, indicated that the symbol is valued. If this is not possible, for example because one of the grammar's symbols already is locked at a valued status of 0, failure is returned. Success value: A non-negative number. Failure value: −2, and sets the error code to an appropriate value, which will never be MARPA-ERR-NONE.



