marpaWrapper - alternate interface to libmarpa
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.
#include <marpaWrapper.h>
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:
marpaWrapperGrammarOption_t
An eventual generic logger. If NULL, the grammar will never log.
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:
A flag saying that any grammar warning should be ignored. Any true value enable this flag. Only 0 can disable it.
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.
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.
NULL
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.
marpaWrapperGrammarOriginp
marpaWrapperGrammarCloneOptionp
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.
marpaWrapperGrammarOptionp
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.
marpaWrapperGrammarSymbolOptionp
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.
marpaWrapperGrammarRuleOptionp
rulei
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:
marpaWrapperGrammarSymbolOption_t
If this is a true value, it forces the grammar to treat this symbol as a terminal.
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.
A bitwise mask of the following constant values:
This symbol can generate a completed event.
This symbol can generate a nulling event.
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_NEWSYMBOL(marpaWrapperGrammarp)
marpaWrapperGrammar_newSymboli(marpaWrapperGrammarp, NULL)
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):
marpaWrapperSymbolPropertyBitSetp
A symbol is accessible if it can be reached from the start symbol.
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.
A symbol is nulling if it always produces the empty string.
A symbol is productive if it can produce a string of terminals. All nullable symbols are considered productive.
Symbol symboli is the start symbol.
Symbol symboli has been created explicitely as a terminal.
Returns 0 on failure, 1 on success.
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.
terminalb
startb
eventSeti
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:
lhsSymboli
rhsSymboll
rhsSymbolip
marpaWrapperGrammarRuleOption_t
Rule priority.
Null variants pattern. If 0, nulled symbols rank low, else nulled symbols rank high.
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:
If positive or zero, this is the symbol Id of a separator.
When it is a true value, says that the separation is proper, i.e. trailing separator is not allowed.
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.
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):
marpaWrapperRulePropertyBitSetp
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.
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.
A rule is nulling if it always produces the empty string.
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.
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.
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_NEWRULE(marpaWrapperGrammarp, lhsSymboli, ...)
marpaWrapperGrammar_newRuleExti(marpaWrapperGrammarp, 0, 0, lhsSymboli, ...)
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_NEWSEQUENCE(marpaWrapperGrammarp, lhsSymboli, rhsSymboli, minimumi)
marpaWrapperGrammar_newSequenceExti(marpaWrapperGrammarp, 0, 0, lhsSymboli, rhsSymboli, minimumi, -1, 0)
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.
eventlp
eventpp
forceReloadb
short marpaWrapperGrammar_precomputeb(marpaWrapperGrammar_t *marpaWrapperGrammarp);
Compute the grammar. Return 0 on failure, 1 on success. Eventual events are automatically fetched.
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.
starti
void marpaWrapperGrammar_freev(marpaWrapperGrammar_t *marpaWrapperGrammarp);
Destructor of the grammar wrapper pointed by marpaWrapperGrammarp.
marpaWrapperGrammarp
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.
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:
marpaWrapperRecognizerOption_t
An eventual generic logger. If NULL, the recognizer will never log.
If this is a true value, disable Earley item warning threshold.
Generate an MARPAWRAPPERGRAMMAR_EVENT_EXHAUSTED event when parse tree is exhausted. When not set, no exhaustion event is ever generated.
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.
valuei
lengthi
1
Returns 1 on success, 0 on failure.
short marpaWrapperRecognizer_completeb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp);
Ends an alternative serie. Returns 1 on success, 0 on failure.
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.
marpaWrapperRecognizer_alternativeb
marpaWrapperRecognizer_completeb
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.
earleySetIdip
marpaWrapperValue_value_startb()
marpaWrapperValue_value_lengthb()
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:
onoffb
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.
*nSymbollp
*symbolArraypp
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.
exhaustedbp
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:
endi
*nProgresslp
*progresspp
0
-1
marpaWrapperRecognizerProgress_t
Current earley position set
Original earley position set
Rule identifier, as returned by marpaWrapperGrammar_newRulei, marpaWrapperGrammar_newRuleExti or marpaWrapperGrammar_newSequenceExti
marpaWrapperGrammar_newRulei
marpaWrapperGrammar_newRuleExti
marpaWrapperGrammar_newSequenceExti
Position inside rulei, where a value -1 means rule completion.
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.
logleveli
symbolDescriptionCallbackp
?
Every call to the generic logger will have this format: [%c%d@%d..%d] %s where first %c character is:
[%c%d@%d..%d] %s
%c
Rule is finished
Rule is being recognized
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.
%d
%d..%d
earleySetOrigIdi
earleySetIdi
.
marpaWrapperGrammar_t *marpaWrapperRecognizer_grammarp(marpaWrapperRecognizer_t *marpaWrapperRecognizerp);
Returns the grammar associated to marpaWrapperRecognizerp, NULL if failure.
marpaWrapperRecognizerp
short marpaWrapperRecognizer_contextSetb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp, marpaWrapperRecognizerContext_t context);
Associates a context to current Earleme Set Id.
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.
contextp
i
short marpaWrapperRecognizer_currentEarlemeb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp, int *ip);
When ip is not NULL, fills it with the current earleme.
ip
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.
short marpaWrapperRecognizer_furthestEarlemeb(marpaWrapperRecognizer_t *marpaWrapperRecognizerp, int *ip);
When ip is not NULL, fills it with the furthest earleme.
void marpaWrapperRecognizer_freev(marpaWrapperRecognizer_t *marpaWrapperRecognizerp);
Destructor of the recognizer wrapper pointed by marpaWrapperRecognizerp.
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:
marpaWrapperValueOption_t
Only rules with highest rank will be considered.
Different parse tree values are returned ordered by rank.
Allows a parse to be ambiguous.
Allows a parse to be undefined.
Limit the number of parse trees traversals. A value lower or equal to zero mean this is unlimited.
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.
resulti
The ruleCallbackp callback also has:
ruleCallbackp
Rule identifier
low indice in the output generic stack, used as input for this rule
high indice in the output generic stack, used as input for this rule
The symbolCallbackp callback has:
symbolCallbackp
Symbol identifier
indice in the input generic stack
The nullingCallbackp callback has:
nullingCallbackp
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.
argi
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.
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.
startip
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.
marpaWrapperValuep
Returns a true value value, a false value on failure.
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.
lengthip
void marpaWrapperValue_freev(marpaWrapperValue_t *marpaWrapperValuep);
Destructor of the value wrapper pointed by marpaWrapperValuep.
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.
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:
marpaWrapperAsfOption_t
An eventual generic logger. If NULL, the forest tree will never log.
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.
traverserCallbackp
*valueip
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.
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.
short marpaWrapperAsf_traverse_symbolIdb(marpaWrapperAsfTraverser_t *traverserp, int *symbolIdip);
If it returns a true value, then current ASF token Id is filled in *symbolIdip.
*symbolIdip
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.
*ruleIdip
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.
*nextbp
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).
rhIxi
*lengthip
marpaWrapperRecognizer_t *marpaWrapperAsf_recognizerp(marpaWrapperAsf_t *marpaWrapperAsfp);
Convenient method that returns the recognizer wrapper, NULL if failure.
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 .
genericLoggerpp
marpaWrapperAsfValue_t *marpaWrapperAsfValue_newp(marpaWrapperRecognizer_t *marpaWrapperRecognizerp, marpaWrapperAsfOption_t *marpaWrapperAsfOptionp);
Instanciate a new valuator using the ASF. Returns NULL on failure.
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:
marpaWrapperValue_t
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.
arg0i
argni
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.
marpaWrapperValue_valueb
valueSymbolCallbackp
valueNullingCallbackp
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.
short marpaWrapperAsfValue_value_startb(marpaWrapperAsfValue_t *marpaWrapperAsfValuep, int *startip);
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.
marpaWrapperAsfValuep
short marpaWrapperAsfValue_value_lengthb(marpaWrapperAsfValue_t *marpaWrapperAsfValuep, int *lengthip);
void marpaWrapperAsfValue_freev(marpaWrapperAsfValue_t *marpaWrapperAsfValuep);
Destructor of the ASF value instance pointed by marpaWrapperAsfValuep.
void marpaWrapperAsf_freev(marpaWrapperAsf_t *marpaWrapperAsfp)
Destructor of the ASF instance pointed by marpaWrapperAsfp.
marpaWrapperAsfp
They are both exclusive. I.e. once you enter the value method, you cannot call for a forest tree, vice and versa.
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.
libmarpa, genericLogger, genericStack
To install MarpaX::ESLIF, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MarpaX::ESLIF
CPAN shell
perl -MCPAN -e shell install MarpaX::ESLIF
For more information on module installation, please visit the detailed CPAN module installation guide.