NAME

marpaWrapper - alternate interface to libmarpa

DESCRIPTION

marpaWrapper is a thin interface on top of libmarpa. Alike the original, there are four explicit namespaces: the grammar, the recognizer, the value and the forest tree.

SYNOPSIS

#include <marpaWrapper.h>

GRAMMAR METHODS

marpaWrapperGrammar_newp

typedef struct marpaWrapperGrammarOption {
  genericLogger_t *genericLoggerp;             /* Default: NULL.                                      */
  short            warningIsErrorb;            /* Default: 0. Have precedence over warningIsIgnoredb  */
  short            warningIsIgnoredb;          /* Default: 0.                                         */
  short            autorankb;                  /* Default: 0.                                         */
} marpaWrapperGrammarOption_t;

marpaWrapperGrammar_t *marpaWrapperGrammar_newp(marpaWrapperGrammarOption_t *marpaWrapperGrammarOptionp)

Instanciate a grammar wrapper, and takes an eventual pointer to a marpaWrapperGrammarOption_t structure describing grammar options. This structure contains the following members:

genericLoggerp: An eventual generic logger. If NULL, the grammar will never log.
warningIsErrorb: A flag saying that any grammar warning should be treated as an error. Any true value enable this flag. Only 0 can disable it. It has precedence over the next member:
warningIsIgnoredb: A flag saying that any grammar warning should be ignored. Any true value enable this flag. Only 0 can disable it.
warningIsIgnoredb: A flag saying that rules are automatically ranked. Then when a rule is created, its eventual initial rank is ignored, and set automatically: rules sharing the same LHS have a decreasing rank as they are created.
autorankb: Automatic assign rule ranks. In such a cause the eventual rank number on a rule is always ignored. Rules are autoranked by their order of in the grammar. The latest the rule, the lower its rank.

NULL is returned in case of failure.

marpaWrapperGrammar_clonep

typedef short (*marpaWrapperGrammar_grammarOptionSetter_t)(void *userDatavp, marpaWrapperGrammarOption_t *marpaWrapperGrammarOptionp);
typedef short (*marpaWrapperGrammar_symbolOptionSetter_t)(void *userDatavp, int symboli, marpaWrapperGrammarSymbolOption_t *marpaWrapperGrammarSymbolOptionp);
typedef short (*marpaWrapperGrammar_ruleOptionSetter_t)(void *userDatavp, int rulei, marpaWrapperGrammarRuleOption_t *marpaWrapperGrammarRuleOptionp);

typedef struct marpaWrapperGrammarCloneOption {
  void                                      *userDatavp;           /* Default: NULL. User context */
  marpaWrapperGrammar_grammarOptionSetter_t  grammarOptionSetterp; /* Default: NULL. Overwrite grammar option */
  marpaWrapperGrammar_symbolOptionSetter_t   symbolOptionSetterp;  /* Default: NULL. Overwrite event symbol option */
  marpaWrapperGrammar_ruleOptionSetter_t     ruleOptionSetterp;    /* Default: NULL. Overwrite event rule option */
} marpaWrapperGrammarCloneOption_t;

marpaWrapperGrammar_t *marpaWrapperGrammar_clonep(marpaWrapperGrammar_t *marpaWrapperGrammarOriginp, marpaWrapperGrammarCloneOption_t *marpaWrapperGrammarCloneOptionp);

Clone a yet existing marpaWrapperGrammarOriginp grammar. This clone is guaranteed to have the same symbol and rule ids as the original. The marpaWrapperGrammarCloneOptionp can be NULL, otherwise it is used to specify callback routines to modify symbol and rule options, leaving responsibility to the caller to have something that can be created.

marpaWrapperGrammarCloneOptionp content is:

userDatavp: User context that will be used as-us within the callbacks.
grammarOptionSetterp: Grammar option callback setter. If it is NULL, grammar is clone with the same options as the original, otherwise marpaWrapperGrammarOptionp is an input/output variable pointer containing the options of the grammar.
symbolOptionSetterp: Symbol option callback setter. If it is NULL, symbols are cloned as the original, otherwise marpaWrapperGrammarSymbolOptionp is an input/output variable pointer containing the options of the symbol symboli.
ruleOptionSetterp: Rule option callback setter. As for symbols, if it is NULL, rules are also cloned as the original, otherwise marpaWrapperGrammarRuleOptionp is an input/output variable pointer containing the options of the rule rulei.

marpaWrapperGrammar_newSymboli

typedef enum marpaWrapperGrammarEventType {
  MARPAWRAPPERGRAMMAR_EVENTTYPE_NONE       = 0x00,
  MARPAWRAPPERGRAMMAR_EVENTTYPE_COMPLETION = 0x01,
  MARPAWRAPPERGRAMMAR_EVENTTYPE_NULLED     = 0x02,
  MARPAWRAPPERGRAMMAR_EVENTTYPE_PREDICTION = 0x04,
} marpaWrapperGrammarEventType_t;

typedef struct marpaWrapperGrammarSymbolOption {
  short  terminalb;             /* Default: 0. Eventually force symbol to be terminal         */
  short  startb;                /* Default: 0. Eventually force symbol to be the start symbol */
  int    eventSeti;             /* Default: MARPAWRAPPERGRAMMAR_EVENTTYPE_NONE.               */
} marpaWrapperGrammarSymbolOption_t;

marpaWrapperGrammar_newSymboli(marpaWrapperGrammar_t *marpaWrapperGrammarp,
                               marpaWrapperGrammarSymbolOption_t *marpaWrapperGrammarSymbolOptionp);

Creates a new symbol. Takes an eventual pointer to a marpaWrapperGrammarSymbolOption_t structure describing symbol options. Such structure contain:

terminalb

If this is a true value, it forces the grammar to treat this symbol as a terminal.

startb

If this is a true value, it forces the grammar to treat this symbol as the start symbol. Default is to take the very first symbol created as the starting point.

eventSeti

A bitwise mask of the following constant values:

MARPAWRAPPERGRAMMAR_EVENTTYPE_COMPLETION: This symbol can generate a completed event.
MARPAWRAPPERGRAMMAR_EVENTTYPE_NULLED: This symbol can generate a nulling event.
MARPAWRAPPERGRAMMAR_EVENTTYPE_PREDICTION: This symbol can generate a predicted event.

A false value is equivalent to MARPAWRAPPERGRAMMAR_EVENTTYPE_NONE, i.e. no event set on this symbol at creation time.

A positive integer is returned on success, -1 on failure. End-user can profit from the fact that the returned number always start at 0 for the very first symbol, and increases by one at every new symbol.

The macro MARPAWRAPPERGRAMMAR_NEWSYMBOL(marpaWrapperGrammarp) exist for convenience, and is stricly equivalent to the call marpaWrapperGrammar_newSymboli(marpaWrapperGrammarp, NULL).

marpaWrapperGrammar_symbolPropertyb

typedef enum marpaWrapperSymbolProperty {
  MARPAWRAPPER_SYMBOL_IS_ACCESSIBLE = 0x01,
  MARPAWRAPPER_SYMBOL_IS_NULLABLE   = 0x02,
  MARPAWRAPPER_SYMBOL_IS_NULLING    = 0x04,
  MARPAWRAPPER_SYMBOL_IS_PRODUCTIVE = 0x08,
  MARPAWRAPPER_SYMBOL_IS_START      = 0x10,
  MARPAWRAPPER_SYMBOL_IS_TERMINAL   = 0x20
} marpaWrapperSymbolProperty_t;

short marpaWrapperGrammar_symbolPropertyb(marpaWrapperGrammar_t *marpaWrapperGrammarp, int symboli, int *marpaWrapperSymbolPropertyBitSetp);

Inspect properties of symbol symboli, putting a bitset result in the value pointed by marpaWrapperSymbolPropertyBitSetp, which can be NULL. Bitset can have the following bits (quoted directly from marpa documentation):

MARPAWRAPPER_SYMBOL_IS_ACCESSIBLE: A symbol is accessible if it can be reached from the start symbol.
MARPAWRAPPER_SYMBOL_IS_NULLABLE: 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.
MARPAWRAPPER_SYMBOL_IS_NULLING: A symbol is nulling if it always produces the empty string.
MARPAWRAPPER_SYMBOL_IS_PRODUCTIVE: A symbol is productive if it can produce a string of terminals. All nullable symbols are considered productive.
MARPAWRAPPER_SYMBOL_IS_START: Symbol symboli is the start symbol.
MARPAWRAPPER_SYMBOL_IS_TERMINAL: Symbol symboli has been created explicitely as a terminal.

Returns 0 on failure, 1 on success.

marpaWrapperGrammar_newSymbolExti

int marpaWrapperGrammar_newSymbolExti(marpaWrapperGrammar_t *marpaWrapperGrammarp,
                                      short terminalb,
                                      short startb,
                                      int eventSeti);

Alternate way to create a symbol, where all the options are explicitely given as parameters. terminalb, startb and eventSeti have the same meaning as in the marpaWrapperGrammarSymbolOption_t structure.

marpaWrapperGrammar_newRulei

typedef struct marpaWrapperGrammarRuleOption {
  int    ranki;          /* Default: 0. Rank                                        */
  short  nullRanksHighb; /* Default: 0. Null variant pattern                        */
  short  sequenceb;      /* Default: 0. Sequence ?                                  */
  int    separatorSymboli; /* Default: -1. Eventual separator symbol                */
  short  properb;        /* Default: 0. Proper flag                                 */
  int    minimumi;       /* Default: 0. Mininimum - must be 0 or 1                  */
} marpaWrapperGrammarRuleOption_t;

int marpaWrapperGrammar_newRulei(marpaWrapperGrammar_t *marpaWrapperGrammarp,
                                 marpaWrapperGrammarRuleOption_t *marpaWrapperGrammarRuleOptionp,
                                 int lhsSymboli,
                                 size_t rhsSymboll, int *rhsSymbolip);

Creates a new rule, with LHS symbol lhsSymboli, and rhsSymboll symbols, stored in the array rhsSymbolip. The pointer to an eventual marpaWrapperGrammarRuleOption_t structure give the following options:

ranki: Rule priority.
nullRanksHighb: Null variants pattern. If 0, nulled symbols rank low, else nulled symbols rank high.
sequenceb: If a true value, identifies this rule as being a sequence. Then there must be one RHS symbol, and the following next members take effect:
separatorSymboli: If positive or zero, this is the symbol Id of a separator.
properb: When it is a true value, says that the separation is proper, i.e. trailing separator is not allowed.
minimumi: When it is 0 or '*', says the sequence repeats at least zero time. If 1 or '+', says it repeat at least one time.

A positive integer is returned on success, -1 on failure. End-user can profit from the fact that the returned number always start at 0 for the very first rule, and increases by one at every new rule.

marpaWrapperGrammar_rulePropertyb

typedef enum marpaWrapperRuleProperty {
  MARPAWRAPPER_RULE_IS_ACCESSIBLE = 0x01,
  MARPAWRAPPER_RULE_IS_NULLABLE   = 0x02,
  MARPAWRAPPER_RULE_IS_NULLING    = 0x04,
  MARPAWRAPPER_RULE_IS_LOOP       = 0x08,
  MARPAWRAPPER_RULE_IS_PRODUCTIVE = 0x10
} marpaWrapperRuleProperty_t;

short marpaWrapperGrammar_rulePropertyb(marpaWrapperGrammar_t *marpaWrapperGrammarp, int rulei, int *marpaWrapperRulePropertyBitSetp);

Inspect properties of rule rulei, putting a bitset result in the value pointed by marpaWrapperRulePropertyBitSetp, which can be NULL. Bitset can have the following bits (quoted directly from marpa documentation):

MARPAWRAPPER_RULE_IS_ACCESSIBLE

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.

MARPAWRAPPER_RULE_IS_NULLABLE

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.

MARPAWRAPPER_RULE_IS_NULLING

A rule is nulling if it always produces the empty string.

MARPAWRAPPER_RULE_IS_LOOP

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.

MARPAWRAPPER_RULE_IS_PRODUCTIVE

A rule is productive if it can produce a string of terminals. A 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.

Returns 0 on failure, 1 on success.

marpaWrapperGrammar_newRuleExti

int marpaWrapperGrammar_newRuleExti(marpaWrapperGrammar_t *marpaWrapperGrammarp,
                                    int ranki,
                                    short nullRanksHighb,
                                    int lhsSymboli, ...);

Alternate way to create a rule that is not sequence. The variadic parameter ... must end with -1 to identify the end of the RHS list.

The macro MARPAWRAPPERGRAMMAR_NEWRULE(marpaWrapperGrammarp, lhsSymboli, ...) exist for convenience, and is strictly equivalent to marpaWrapperGrammar_newRuleExti(marpaWrapperGrammarp, 0, 0, lhsSymboli, ...).

marpaWrapperGrammar_newSequenceExti

int marpaWrapperGrammar_newSequenceExti(marpaWrapperGrammar_t *marpaWrapperGrammarp,
                                        int ranki,
                                        short nullRanksHighb,
                                        int lhsSymboli,
                                        int rhsSymboli,
                                        int minimumi,
                                        int separatorSymboli,
                                        short properb);

Alternate way to create a sequence.

The macro MARPAWRAPPERGRAMMAR_NEWSEQUENCE(marpaWrapperGrammarp, lhsSymboli, rhsSymboli, minimumi), exist for convenience, and is equivalent to calling marpaWrapperGrammar_newSequenceExti(marpaWrapperGrammarp, 0, 0, lhsSymboli, rhsSymboli, minimumi, -1, 0).

marpaWrapperGrammar_eventb

typedef struct marpaWrapperGrammarEvent {
  enum {
    MARPAWRAPPERGRAMMAR_EVENT_COMPLETED,
    MARPAWRAPPERGRAMMAR_EVENT_NULLED,
    MARPAWRAPPERGRAMMAR_EVENT_EXPECTED,
    MARPAWRAPPERGRAMMAR_EVENT_EXHAUSTED
  } eventType;
  int symboli; /* -1 in case of exhaustion, symbolId otherwise */
} marpaWrapperGrammarEvent_t;

short marpaWrapperGrammar_eventb(marpaWrapperGrammar_t *marpaWrapperGrammarp, size_t *eventlp, marpaWrapperGrammarEvent_t **eventpp, short forceReloadb);

Return the list of events. Number of events is stored in eventlp, and eventpp is the list itself. This list of owned by the grammar and must not be freed by the caller. Events are always pre-fetched whenever necessary, that is the forceReloadb parameter should be 0 in all situations. Nevertheless, a true value for forceReloadb is allowed.

Returns 0 on failure, 1 on success.

marpaWrapperGrammar_precomputeb

short marpaWrapperGrammar_precomputeb(marpaWrapperGrammar_t *marpaWrapperGrammarp);

Compute the grammar. Return 0 on failure, 1 on success. Eventual events are automatically fetched.

marpaWrapperGrammar_precompute_startb

short marpaWrapperGrammar_precomputeb(marpaWrapperGrammar_t *marpaWrapperGrammarp, int starti);

Compute the grammar by fixing beforehand the start symbol to starti, regardless if a symbol was marked previously as being the start symbol or not. Return 0 on failure, 1 on success. Eventual events are automatically fetched.

marpaWrapperGrammar_freev

void marpaWrapperGrammar_freev(marpaWrapperGrammar_t *marpaWrapperGrammarp);

Destructor of the grammar wrapper pointed by marpaWrapperGrammarp.

RECOGNIZER METHODS

There is one notion to know about in the recognizer: it has an internal position, that is called below an Earley Set Id: initially 0, every completion of alternatives advances that position. This notion exposes some internals of the wrapped libmarpa, that is an Earley Parser.

marpaWrapperRecognizer_newp

typedef struct marpaWrapperRecognizerOption {
  genericLogger_t *genericLoggerp;             /* Default: NULL. */
  short            disableThresholdb;          /* Default: 0.    */
  short            exhaustionEventb;           /* Default: 0.                                         */
} marpaWrapperRecognizerOption_t;

 marpaWrapperRecognizer_t *marpaWrapperRecognizer_newp(marpaWrapperGrammar_t *marpaWrapperGrammarp,
                                                       marpaWrapperRecognizerOption_t *marpaWrapperRecognizerOptionp);

Instanciate a recognizer wrapper, using a grammar pointer that must be precomputed, and takes an eventual pointer to a marpaWrapperRecognizerOption_t structure describing recognizer options. This structure contains the following members:

genericLoggerp: An eventual generic logger. If NULL, the recognizer will never log.
disableThresholdb: If this is a true value, disable Earley item warning threshold.
exhaustionEventb: Generate an MARPAWRAPPERGRAMMAR_EVENT_EXHAUSTED event when parse tree is exhausted. When not set, no exhaustion event is ever generated.

NULL is returned in case of failure.

marpaWrapperRecognizer_alternativeb

short marpaWrapperRecognizer_alternativeb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp,
                                          int symboli,
                                          int valuei,
                                          int lengthi);

Pushes symbol number symboli as an alternative, with a value valuei that must be a positive integer (up to the end-user to associate this to something else - typically using valuei as an index in an array of user-only-knows other values), and a length lengthi that must also be a positive integer. Please note that lengthi, here, is not the length in the input stream, but becayse Marpa has support to overlapping tokens, i.e. this is the length within the grammar - almost any application will want to use the value 1.

Returns 1 on success, 0 on failure.

marpaWrapperRecognizer_completeb

short marpaWrapperRecognizer_completeb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp);

Ends an alternative serie. Returns 1 on success, 0 on failure.

marpaWrapperRecognizer_readb

short marpaWrapperRecognizer_readb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp,
                                   int symboli,
                                   int valuei,
                                   int lengthi);

Convenient method that is combining calls to marpaWrapperRecognizer_alternativeb and marpaWrapperRecognizer_completeb on a single symbol, useful when the end-user knows there is only one alternative.

Returns 1 on success, 0 on failure.

marpaWrapperRecognizer_latestb

short marpaWrapperRecognizer_latestb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp, int *earleySetIdip);

Put the latest Earleme Set Id in the value pointed by earleySetIdip, if it is not NULL. The user is foreseen to keep track of any associated data, and use the methods marpaWrapperValue_value_startb() and marpaWrapperValue_value_lengthb() to process some Earleme Set Id related information during valuation.

Returns 1 on success, 0 on failure.

marpaWrapperRecognizer_readb

short marpaWrapperRecognizer_readb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp,
                                   int symboli,
                                   int valuei,
                                   int lengthi);

Returns 1 on success, 0 on failure.

marpaWrapperRecognizer_event_onoffb

short marpaWrapperRecognizer_event_onoffb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp,
                                          int symboli,
                                          marpaWrapperGrammarEventType_t eventSeti,
                                          int onoffb);

Sets on or off an event on symbol number symboli, using a bit-wise eventSeti, and a flag onoffb. Any true value for onoffb is interpreted as event being set, a false value (i.e. 0) meaning the event is unset. The parameter eventSeti has the same meaning as when creating a symbol, i.e. it is a logical OR between:

A bitwise mask of the following constant values:

MARPAWRAPPERGRAMMAR_EVENTTYPE_COMPLETION: This symbol can generate a completed event.
MARPAWRAPPERGRAMMAR_EVENTTYPE_NULLED: This symbol can generate a nulling event.
MARPAWRAPPERGRAMMAR_EVENTTYPE_PREDICTION: This symbol can generate a predicted event.

Returns 1 on success, 0 on failure.

marpaWrapperRecognizer_expectedb

short marpaWrapperRecognizer_expectedb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp,
                                       size_t *nSymbollp,
                                       int **symbolArraypp);

Gets the list of expected symbols, the number of them being stored in *nSymbollp and their identifier in the *symbolArraypp array. End-user must not free the array, it is owned by the recognizer wrapper.

Returns 1 on success, 0 on failure.

marpaWrapperRecognizer_exhaustedb

short marpaWrapperRecognizer_exhaustedb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp, short *exhaustedbp);

Gets the exhaustion status of the recognizer into the value pointed by exhaustedbp if it not NULL. A true value means the recognizer is exhausted, a false value means it is not.

Returns 1 on success, 0 on failure.

marpaWrapperRecognizer_progressb

typedef struct marpaWrapperRecognizerProgress {
  int earleySetIdi;
  int earleySetOrigIdi;
  int rulei;
  int positioni;
} marpaWrapperRecognizerProgress_t;

short marpaWrapperRecognizer_progressb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp,
                                       int starti,
                                       int endi,
                                       size_t *nProgresslp,
                                       marpaWrapperRecognizerProgress_t **progresspp);

Given two recognizer position sets starti and endi, this method returns *nProgresslp progress lines, each of them being indexed in the array *progresspp. starti and endi follow the perl's splice method conventions for an offset, i.e.: if the value is negative, start that far from the end of all positions. A full parse progress report is consequencly obtained by specifying 0 for starti, and -1 for endi. Every progress line is a marpaWrapperRecognizerProgress_t structure that contain:

earleySetIdi: Current earley position set
earleySetOrigIdi: Original earley position set
rulei: Rule identifier, as returned by marpaWrapperGrammar_newRulei, marpaWrapperGrammar_newRuleExti or marpaWrapperGrammar_newSequenceExti
positioni: Position inside rulei, where a value -1 means rule completion.

Returns 1 on success, 0 on failure.

marpaWrapperRecognizer_progressLogb

typedef struct marpaWrapperRecognizerContext {
  int   valuei;
  void *valuep;
} marpaWrapperRecognizerContext_t;

typedef char *(*marpaWrapperRecognizerSymbolDescriptionCallback_t)(void *userDatavp, int symboli);
typedef void  (*marpaWrapperRecognizerContextFreeCallback_t)(void *userDatavp, marpaWrapperRecognizerContext_t *contextp);

marpaWrapperRecognizer_progressLogb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp,
                                    int starti, int endi,
                                    genericLoggerLevel_t logleveli,
                                    void *userDatavp,
                                    marpaWrapperRecognizerSymbolDescriptionCallback_t symbolDescriptionCallbackp);

Convenient method that is using the eventual generic logger specified at object instance phase: if the generic logger is set, then this method will call it with the logging level logleveli, using a symbol description returned by callback symbolDescriptionCallbackp. userDatavp is an opaque pointer, typically used to propagate a userspace context, the callback will be used for every symbol identifier symboli. If no callback, or if the callback returns NULL, the hardcoded symbol description ? is used.

Every call to the generic logger will have this format: [%c%d@%d..%d] %s where first %c character is:

'F': Rule is finished
'R': Rule is being recognized
'P': Rule is being predicted

The second item %d is the current rule identifier. Then %d..%d is the earleme identifier corresponding to earleySetOrigIdi followed by the earleme identifier corresponding to earleySetIdi. The rest is the rule description: there are as many calls to the logger as there are RHS. Position will show as the . dot character. Please note that in the usual token-stream model, the earleme identifier is the same as the earley set identifier.

Returns 1 on success, 0 on failure.

marpaWrapperRecognizer_grammarp

marpaWrapperGrammar_t *marpaWrapperRecognizer_grammarp(marpaWrapperRecognizer_t *marpaWrapperRecognizerp);

Returns the grammar associated to marpaWrapperRecognizerp, NULL if failure.

marpaWrapperRecognizer_contextSetb

short marpaWrapperRecognizer_contextSetb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp, marpaWrapperRecognizerContext_t context);

Associates a context to current Earleme Set Id.

Returns 0 on failure, 1 on success.

marpaWrapperRecognizer_contextGetb

short marpaWrapperRecognizer_contextGetb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp, int i, marpaWrapperRecognizerContext_t *contextp);

When contextp is not NULL, fills it with the context at Earleme Set Id i, where i follows the perl's splice method conventions for an offset, i.e.: if the value is negative, start that far from the end of all positions.

Returns 0 on failure, 1 on success.

marpaWrapperRecognizer_currentEarlemeb

short marpaWrapperRecognizer_currentEarlemeb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp, int *ip);

When ip is not NULL, fills it with the current earleme.

Returns 0 on failure, 1 on success.

marpaWrapperRecognizer_earlemeb

short marpaWrapperRecognizer_earlemeb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp, int i, int *ip);;

When ip is not NULL, fills it with the earleme at Earleme Set Id i, where i follows the perl's splice method conventions for an offset, i.e.: if the value is negative, start that far from the end of all positions.

Returns 0 on failure, 1 on success.

marpaWrapperRecognizer_furthestEarlemeb

short marpaWrapperRecognizer_furthestEarlemeb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp, int *ip);

When ip is not NULL, fills it with the furthest earleme.

Returns 0 on failure, 1 on success.

marpaWrapperRecognizer_freev

void marpaWrapperRecognizer_freev(marpaWrapperRecognizer_t *marpaWrapperRecognizerp);

Destructor of the recognizer wrapper pointed by marpaWrapperRecognizerp.

VALUES METHODS

marpaWrapperValue_newp

typedef struct marpaWrapperValueOption {
  genericLogger_t                   *genericLoggerp;             /* Default: NULL */
  short                              highRankOnlyb;              /* Default: 1 */
  short                              orderByRankb;               /* Default: 1 */
  short                              ambiguousb;                 /* Default: 0 */
  short                              nullb;                      /* Default: 0 */
  int                                maxParsesi;                 /* Default: 0 */
} marpaWrapperValueOption_t;

marpaWrapperValue_t *marpaWrapperValue_newp(marpaWrapperRecognizer_t *marpaWrapperRecognizerp,
                                            marpaWrapperValueOption_t *marpaWrapperValueOptionp);

Instanciate a value wrapper, and takes an eventual pointer to a marpaWrapperValueOption_t structure describing value options. This structure contains the following members:

genericLoggerp: An eventual generic logger. If NULL, the grammar will never log.
highRankOnlyb: Only rules with highest rank will be considered.
orderByRankb: Different parse tree values are returned ordered by rank.
ambiguousb: Allows a parse to be ambiguous.
nullb: Allows a parse to be undefined.
maxParsesi: Limit the number of parse trees traversals. A value lower or equal to zero mean this is unlimited.

NULL is returned in case of failure.

marpaWrapperValue_valueb

typedef short (*marpaWrapperValueRuleCallback_t)(void *userDatavp, int rulei, int arg0i, int argni, int resulti);
typedef short (*marpaWrapperValueSymbolCallback_t)(void *userDatavp, int symboli, int argi, int resulti);
typedef short (*marpaWrapperValueNullingCallback_t)(void *userDatavp, int symboli, int resulti);

short marpaWrapperValue_valueb(marpaWrapperValue_t               *marpaWrapperValuep,
                               void                              *userDatavp,
                               marpaWrapperValueRuleCallback_t    ruleCallbackp,
                               marpaWrapperValueSymbolCallback_t  symbolCallbackp,
                               marpaWrapperValueNullingCallback_t nullingCallbackp);

Get the current parse tree value. It is recommended to set the three different callbacks to valid function pointers. Every callback will be called with userDatavp as first argument, typically used to propagate user context, and with resulti as last argument, which is the destination indice in a output generic stack.

The ruleCallbackp callback also has:

rulei: Rule identifier
arg0i: low indice in the output generic stack, used as input for this rule
argni: high indice in the output generic stack, used as input for this rule

The symbolCallbackp callback has:

symboli: Symbol identifier
argi: indice in the input generic stack

The nullingCallbackp callback has:

symboli: Symbol identifier

A typical portable implemententation is using a generic stack that distinguishes between user input (i.e. the lexing phase) and parse tree values: user input has its own generic stack, and a parse tree value have its own as well. In such implemention, only the symbol callback should take data from the input generic stack (at indice argi>, and put result in the output, i.e. the parse tree value, generic stack (at indice resulti). All the other methods deal only with the output generic stack.

A typical usage is:

while (marpaWrapperValue_valueb(marpaWrapperValuep, ...) > 0) {
  /* Output is in indice 0 of output stack */
}

An example of generic stack with indice is the genericStack package, used in the test-suite of marpaWrapper.

Returns -1 on failure, 0 when there is no more parse value, and 1 on success.

marpaWrapperValue_value_startb

short marpaWrapperValue_value_startb(marpaWrapperValue_t *marpaWrapperValuep, int *startip);

Get the Start Earleme Set Id in the value pointed by startip, if it is not NULL.

This method will always fail if it is called outside of a value callback. This mean that you have to arrange to get marpaWrapperValuep via the opaque context of the callbacks.

Returns a true value value, a false value on failure.

marpaWrapperValue_value_lengthb

short marpaWrapperValue_value_lengthb(marpaWrapperValue_t *marpaWrapperValuep, int *lengthip);

Get the number of Earleme Set Ids in the value pointed by lengthip, if it is not NULL.

This method will always fail if it is called outside of a value callback. This mean that you have to arrange to get marpaWrapperValuep via the opaque context of the callbacks.

Returns a true value value, a false value on failure.

marpaWrapperValue_freev

void marpaWrapperValue_freev(marpaWrapperValue_t *marpaWrapperValuep);

Destructor of the value wrapper pointed by marpaWrapperValuep.

FOREST TREE METHODS

User will nagivate in a parse tree forest, and will be able to get all possible alternatives at a given point, eventually rejecting those unwanted. Internally, the wrapper will maintain a node within the parse tree forest, from where nagivation goes on.

marpaWrapperAsf_newp

typedef struct marpaWrapperAsfOption {
  genericLogger_t *genericLoggerp;             /* Default: NULL. */
  short            highRankOnlyb;              /* Default: 1 */
  short            orderByRankb;               /* Default: 1 */
  short            ambiguousb;                 /* Default: 0 */
  int              maxParsesi;                 /* Default: 0 */
} marpaWrapperAsfOption_t;

marpaWrapperAsf_t *marpaWrapperAsf_newp(marpaWrapperRecognizer_t *marpaWrapperRecognizerp,
                                        marpaWrapperAsfOption_t *marpaWrapperAsfOptionp);

Instanciate a forest tree wrapper, and takes an eventual pointer to a marpaWrapperAsfOption_t structure describing value options. This structure contains the following members:

genericLoggerp: An eventual generic logger. If NULL, the forest tree will never log.
highRankOnlyb: Only rules with highest rank will be considered.
orderByRankb: Different parse tree values are returned ordered by rank.
ambiguousb: Allows a parse to be ambiguous.
maxParsesi: Limit the number of parse trees traversals. A value lower or equal to zero mean this is unlimited.

NULL is returned in case of failure.

marpaWrapperAsf_traverseb

typedef short (*traverserCallback_t)(marpaWrapperAsfTraverser_t *traverserp, void *userDatavp, int *valueip);

short marpaWrapperAsf_traverseb(marpaWrapperAsf_t *marpaWrapperAsfp,
                                traverserCallback_t traverserCallbackp,
                                void *userDatavp,
                                int *valueip);

Call for a forest tree, using the traverserCallbackp callback function pointer, the later userDatavp as an opaque pointer, typically used to propagate user context. In case of failure, this method returns a false value, else it propagates the traverser callback value in the *valueip integer pointer. This value is typically an indice in an output stack, managed in the user-space. Traverser itself returns a false value in case of failure, and fills its *valueip argument otherwise.

In the forest tree mode, it is important to talk about ASF tokens and ASF rules, instead of symbols and rules: a rule with no RHS is considered a trivial node, and is identified as a token. This mean that, in a forest tree, when we talk about a rule, it is guaranteed that there is at least one RHS.

marpaWrapperAsf_traverse_rh_lengthl

int marpaWrapperAsf_traverse_rh_lengthi(marpaWrapperAsfTraverser_t *traverserp);

Returns the number of RHS symbols at the current node, -1 in case of failure. In particular, this will fail if it is called for a ASF token.

marpaWrapperAsf_traverse_symbolIdb

short marpaWrapperAsf_traverse_symbolIdb(marpaWrapperAsfTraverser_t *traverserp, int *symbolIdip);

If it returns a true value, then current ASF token Id is filled in *symbolIdip.

marpaWrapperAsf_traverse_ruleIdb

short marpaWrapperAsf_traverse_ruleIdb(marpaWrapperAsfTraverser_t *traverserp, int *ruleIdip);

If it returns a true value, then current original rule Id is filled in *ruleIdip. Please note that if current node is an ASF token, it is not an application failure to get the value -1 in *ruleIdip. Therefore, traversers will typically distinguish cases where *ruleIdip is >= 0 or not: if *ruleIdip is < 0, it is a nulling symbol (can be an LHS with no RHS), if *ruleIdip is >= 0 it is a, LHS with at least one RHS.

marpaWrapperAsf_traverse_nextb

short marpaWrapperAsf_traverse_nextb(marpaWrapperAsfTraverser_t *traverserp, short *nextbp);

If it returns a true value, then *nextbp contains a true value if there is another alternative, a false value otherwise.

marpaWrapperAsf_traverse_rh_valueb

short marpaWrapperAsf_traverse_rh_valueb(marpaWrapperAsfTraverser_t *traverserp, int rhIxi, int *valueip, int *lengthip);

If it returns a true value, then the indice in the user-space output stack of the RHS number rhIxi is set in *valueip for the current node. When current node is an ASF token, rhIxi is ignored. *lengthip is the number of RHS if current node is an ASF rule (guaranteed to be greater than zero), the length (in unit of Earley Set) in the input stream if current node is an ASF token. If *lengthip is zero, it indicates a nullable ASF token (i;e. a rule with no RHS, or a nullable symbol).

marpaWrapperAsf_recognizerp

marpaWrapperRecognizer_t *marpaWrapperAsf_recognizerp(marpaWrapperAsf_t *marpaWrapperAsfp);

Convenient method that returns the recognizer wrapper, NULL if failure.

marpaWrapperAsf_genericLoggerp

short marpaWrapperAsf_genericLoggerp(marpaWrapperAsf_t *marpaWrapperAsfp, genericLogger_t **genericLoggerpp);

Convenient method that returns the generic logger wrapper in the value pointed by genericLoggerpp. Return a true value on success, a false value on failure .

marpaWrapperAsfValue_newp

marpaWrapperAsfValue_t *marpaWrapperAsfValue_newp(marpaWrapperRecognizer_t *marpaWrapperRecognizerp, marpaWrapperAsfOption_t *marpaWrapperAsfOptionp);

Instanciate a new valuator using the ASF. Returns NULL on failure.

marpaWrapperAsfValue_valueb

typedef short (*marpaWrapperAsfOkRuleCallback_t)(void *userDatavp, genericStack_t *parentRuleiStackp, int rulei, int arg0i, int argni);
typedef short (*marpaWrapperAsfOkSymbolCallback_t)(void *userDatavp, genericStack_t *parentRuleiStackp, int symboli, int argi);
typedef short (*marpaWrapperAsfOkNullingCallback_t)(void *userDatavp, genericStack_t *parentRuleiStackp, int symboli);

marpaWrapperAsfValue_t *marpaWrapperAsfValue_valueb(marpaWrapperAsfValue_t               *marpaWrapperAsfValuep,
                                                    void                                 *userDatavp,
                                                    marpaWrapperAsfOkRuleCallback_t       okRuleCallbackp,
                                                    marpaWrapperAsfOkSymbolCallback_t     okSymbolCallbackp,
                                                    marpaWrapperAsfOkNullingCallback_t    okNullingCallbackp,
                                                    marpaWrapperValueRuleCallback_t       valueRuleCallbackp,
                                                    marpaWrapperValueSymbolCallback_t     valueSymbolCallbackp,
                                                    marpaWrapperValueNullingCallback_t    valueNullingCallbackp);

This method instanciates a valuation opaque pointer that will allow the user to use the ASF and perform valuation, as if he was using a marpaWrapperValue_t instance. The difference is that the user have the control on which rule or symbol is valid:

okRuleCallackp: Return 0 in case of failure, a positive value if success, a negative value if reject. Stack of parent rule IDs is in <parentRuleiStackp>. rulei is the rule number, arg0i and argni are the stack indices.
okSymbolCallackp: Return 0 in case of failure, a positive value if success, a negative value if reject. Stack of parent rule IDs is in <parentRuleiStackp>. symboli is the symbol number, and argi is the stack number.
okNullingCallackp: Return 0 in case of failure, a positive value if success, a negative value if reject. Stack of parent rule IDs is in <parentRuleiStackp>. symboli is the symbol number.
valueRuleCallbackp: Same semantic as for marpaWrapperValue_valueb.
valueSymbolCallbackp: Same semantic as for marpaWrapperValue_valueb.
valueNullingCallbackp: Same semantic as for marpaWrapperValue_valueb.

NULL is returned in case of failure.

marpaWrapperAsfValue_valueb

short marpaWrapperAsfValue_valueb(marpaWrapperAsfValue_t *marpaWrapperAsfValuep);

An example of how to use the ASF API. This method simulate the marpaWrapperValue_valueb() behaviour, but using the ASF, i.e. it returns -1 on failure, 0 when there is no more parse value, and 1 on success.

marpaWrapperAsfValue_value_startb

short marpaWrapperAsfValue_value_startb(marpaWrapperAsfValue_t *marpaWrapperAsfValuep, int *startip);

Get the Start Earleme Set Id in the value pointed by startip, if it is not NULL.

This method will always fail if it is called outside of an ASF callback. This mean that you have to arrange to get marpaWrapperAsfValuep via the opaque context of the callbacks.

Returns a true value value, a false value on failure.

marpaWrapperAsfValue_value_lengthb

short marpaWrapperAsfValue_value_lengthb(marpaWrapperAsfValue_t *marpaWrapperAsfValuep, int *lengthip);

Get the number of Earleme Set Ids in the value pointed by lengthip, if it is not NULL.

This method will always fail if it is called outside of an ASF callback. This mean that you have to arrange to get marpaWrapperAsfValuep via the opaque context of the callbacks.

Returns a true value value, a false value on failure.

marpaWrapperAsfValue_freev

void marpaWrapperAsfValue_freev(marpaWrapperAsfValue_t *marpaWrapperAsfValuep);

Destructor of the ASF value instance pointed by marpaWrapperAsfValuep.

marpaWrapperAsf_freev

void marpaWrapperAsf_freev(marpaWrapperAsf_t *marpaWrapperAsfp)

Destructor of the ASF instance pointed by marpaWrapperAsfp.

NOTES

Vaue and Forest Tree methods: They are both exclusive. I.e. once you enter the value method, you cannot call for a forest tree, vice and versa.
Forest Tree constraint: A technical limitation on getting the value associated to a lexeme imposes that forest tree is possible only if lengthi parameter of any call to marpaWrapperRecognizer_alternativeb is the value 1. This is the case for almost any application.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

SYNOPSIS

GRAMMAR METHODS

marpaWrapperGrammar_newp

marpaWrapperGrammar_clonep

marpaWrapperGrammar_newSymboli

marpaWrapperGrammar_symbolPropertyb

marpaWrapperGrammar_newSymbolExti

marpaWrapperGrammar_newRulei

marpaWrapperGrammar_rulePropertyb

marpaWrapperGrammar_newRuleExti

marpaWrapperGrammar_newSequenceExti

marpaWrapperGrammar_eventb

marpaWrapperGrammar_precomputeb

marpaWrapperGrammar_precompute_startb

marpaWrapperGrammar_freev

RECOGNIZER METHODS

marpaWrapperRecognizer_newp

marpaWrapperRecognizer_alternativeb

marpaWrapperRecognizer_completeb

marpaWrapperRecognizer_readb

marpaWrapperRecognizer_latestb

marpaWrapperRecognizer_readb

marpaWrapperRecognizer_event_onoffb

marpaWrapperRecognizer_expectedb

marpaWrapperRecognizer_exhaustedb

marpaWrapperRecognizer_progressb

marpaWrapperRecognizer_progressLogb

marpaWrapperRecognizer_grammarp

marpaWrapperRecognizer_contextSetb

marpaWrapperRecognizer_contextGetb

marpaWrapperRecognizer_currentEarlemeb

marpaWrapperRecognizer_earlemeb

marpaWrapperRecognizer_furthestEarlemeb

marpaWrapperRecognizer_freev

VALUES METHODS

marpaWrapperValue_newp

marpaWrapperValue_valueb

marpaWrapperValue_value_startb

marpaWrapperValue_value_lengthb

marpaWrapperValue_freev

FOREST TREE METHODS

marpaWrapperAsf_newp

marpaWrapperAsf_traverseb

marpaWrapperAsf_traverse_rh_lengthl

marpaWrapperAsf_traverse_symbolIdb

marpaWrapperAsf_traverse_ruleIdb

marpaWrapperAsf_traverse_nextb

marpaWrapperAsf_traverse_rh_valueb

marpaWrapperAsf_recognizerp

marpaWrapperAsf_genericLoggerp

marpaWrapperAsfValue_newp

marpaWrapperAsfValue_valueb

marpaWrapperAsfValue_valueb

marpaWrapperAsfValue_value_startb

marpaWrapperAsfValue_value_lengthb

marpaWrapperAsfValue_freev

marpaWrapperAsf_freev

NOTES

SEE ALSO

Module Install Instructions