32.2.3 Registering semantics in the valuator

By default, Libmarpa’s valuator objects assume that non-terminal symbols have no semantics. The archetypal application will need to register symbols that contain semantics. The primary method for doing this is marpa_v_symbol_is_valued(). Applications will typically register semantics by rule, and these applications will find the marpa_v_rule_is_valued() method more convenient.

Function: int marpa_v_symbol_is_valued_set ( Marpa_Value v, Marpa_Symbol_ID sym_id, int status )

Function: int marpa_v_symbol_is_valued ( Marpa_Value v, Marpa_Symbol_ID sym_id )

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).

Return value: On success, the valued status after the call. If value is not either 0 or 1, or on other hard failure, -2.

Function: int marpa_v_rule_is_valued_set ( Marpa_Value v, Marpa_Rule_ID rule_id, int status )

Function: int marpa_v_rule_is_valued ( Marpa_Value v, Marpa_Rule_ID rule_id )

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 it to a status different from the current one will fail with 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.

Return value: On success, 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 hard failure, -2.

Function: int marpa_v_valued_force ( Marpa_Value v)

This methods locks the valued status of all symbols to 1, so that all symbols will always be valued. Hard fails if this is not possible, for example because one of the grammar’s symbols already is locked at a valued status of 0.

Return value: On success, a non-negative integer. On hard failure, returns -2, and sets the error code to an appropriate value, which will never be MARPA_ERR_NONE.