Skip to content

Instantly share code, notes, and snippets.

/marpa_error_codes.txt Secret

Created December 7, 2014 22:05
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save anonymous/7e10fe6cc37a42ab3eb5 to your computer and use it in GitHub Desktop.
Save anonymous/7e10fe6cc37a42ab3eb5 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
marpa_error_codes.txt
Libmarpa 7.3.0
failure return values, for your bindings-writing pleasure
marpa_check_version
always succeeds, technically
marpa_version
−2
marpa_c_init
Always succeeds.
marpa_c_error
Always succeeds.
marpa_g_new
NULL, and the error code is set in configuration.
marpa_g_force_valued
a negative integer.
Marpa_Grammar marpa_g_ref
NULL
Marpa_Symbol_ID marpa_g_start_symbol
−2;
11.4 Symbols
marpa_g_start_symbol_set
no such symbol, -1.
−2.
marpa_g_highest_symbol_id
−2.
marpa_g_symbol_is_accessible
no such symbol, -1
−2.
marpa_g_symbol_is_completion_event
marpa_g_symbol_is_completion_event_set
no such symbol, -1
−2.
marpa_g_symbol_is_nulled_event
marpa_g_symbol_is_nulled_event_set
no such symbol, -1.
−2.
marpa_g_symbol_is_nullable
no such symbol, -1
−2.
marpa_g_symbol_is_nulling
no such symbol, -1
−2.
marpa_g_symbol_is_productive
no such symbol, -1
−2.
marpa_g_symbol_is_prediction_event
marpa_g_symbol_is_prediction_event_set
no such symbol, -1.
−2.
marpa_g_symbol_is_start
no such symbol, -1
−2.
marpa_g_symbol_is_terminal
marpa_g_symbol_is_terminal_set
no such symbol, -1
−2.
marpa_g_symbol_new
−2.
11.5 Rules
marpa_g_highest_rule_id
−2.
marpa_g_rule_is_accessible
no such rule, -1
−2.
marpa_g_rule_is_nullable
no such rule, -1
−2.
marpa_g_rule_is_nulling
no such rule, -1
−2.
marpa_g_rule_is_loop
no such rule, -1
−2.
marpa_g_rule_is_productive
no such rule, -1.
−2.
marpa_g_rule_length
−2.
marpa_g_rule_lhs
no such rule, -1.
−2.
marpa_g_rule_new
−2.
marpa_g_rule_rhs
no such rule, -1
−2.
11.6 Sequences
marpa_g_rule_is_proper_separation
no such rule, -1
−2.
marpa_g_sequence_min
not the rule ID of sequence rule, −1.
−2.
marpa_g_sequence_new
−2.
marpa_g_sequence_separator
no separator, −1
−2.
marpa_g_symbol_is_counted
−2.
marpa_g_rule_rank
marpa_g_rule_rank_set
−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.
marpa_g_rule_null_high
marpa_g_rule_null_high_set
−2.
marpa_g_precompute
marpa_g_precompute() is unusual in that it is possible to treat one of its failures as “advisory”...
−2.
marpa_g_is_precomputed
−2.
marpa_g_has_cycle
−2.
12 Recognizer methods
marpa_r_new
NULL.
marpa_r_ref
NULL.
marpa_r_unref
void
marpa_r_start_input
−2.
marpa_r_alternative
Several error codes leave the recognizer in a fully recoverable state,
marpa_r_earleme_complete
An exhausted parse may cause a failure,
12.5 Location accessors
marpa_r_current_earleme
If input has not started, −1.
Always succeeds.
marpa_r_earleme
−2.
marpa_r_earley_set_value
−2.
marpa_r_earley_set_values
−2.
marpa_r_furthest_earleme
Always succeeds.
marpa_r_latest_earley_set
Always succeeds.
marpa_r_latest_earley_set_value_set
−2.
marpa_r_latest_earley_set_values_set
−2.
12.6 Other parse status methods
marpa_r_earley_item_warning_threshold
marpa_r_earley_item_warning_threshold_set
Always succeeds.
marpa_r_expected_symbol_event_set
-2
marpa_r_is_exhausted
Always succeeds.
marpa_r_terminals_expected
−2.
marpa_r_terminal_is_expected
−2
12.7 Untested recognizer methods
marpa_r_completion_symbol_activate
−2
marpa_r_nulled_symbol_activate
−2
marpa_r_prediction_symbol_activate
−2
13 Progress reports
marpa_r_progress_report_reset
−2.
marpa_r_progress_report_start
−2.
marpa_r_progress_report_finish
−2
marpa_r_progress_item
−1 as a termination indicator
−2.
14 Bocage methods
marpa_b_new
If there is no parse ending at Earley set earley_set_ID, marpa_b_new fails and the error code is set to MARPA_ERR_NO_PARSE.
NULL.
marpa_b_ref
NULL.
marpa_b_unref
void
14.4 Accessors
— Function: int marpa_b_ambiguity_metric (Marpa_Bocage b)
Returns an ambiguity metric. For the time being, it is vaguely defined, but it does differentiate between an ambiguous and an unambiguous bocage.
Return value on success: 1 if the bocage is not for an ambiguous parse; a number greater than 1 if the bocage is for an ambiguous parse.
Failures: On failure, −2.
— Function: int marpa_b_is_null (Marpa_Bocage b)
Return value on success: A number greater than or equal to 1 if the bocage is for a null parse; otherwise, 0.
Failures: On failure, −2.
15 Ordering methods
15.1 Overview
Before iterating the parses in the bocage, they must be ordered. To create an ordering, use the marpa_o_new() method. When an ordering is no longer in use, its memory can be freed using the marpa_o_unref() method.
An ordering is frozen once the first tree iterator is created using it. A frozen ordering cannot be changed.
As of this writing, the only methods to order parses are internal and undocumented. This is expected to change.
15.2 Creating an ordering
— Function: Marpa_Order marpa_o_new ( Marpa_Bocage b)
Creates a new ordering object, with a reference count of 1. The reference count of its parent bocage object, b, is increased by 1.
Return value: On success, the new ordering object. On failure, NULL.
15.3 Reference counting
— Function: Marpa_Order marpa_o_ref ( Marpa_Order o)
Increases the reference count by 1. Not needed by most applications.
Return value: On success, o. On failure, NULL.
— Function: void marpa_o_unref ( Marpa_Order o)
Decreases the reference count by 1, destroying o once the reference count reaches zero. Beginning with o's parent bocage, 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.
15.4 Accessors
— Function: int marpa_o_ambiguity_metric (Marpa_Order o)
Returns an ambiguity metric. For the time being, it is vaguely defined, but it does differentiate between an ambiguous and an unambiguous ordering.
Return value on success: 1 if the ordering is not for an ambiguous parse; a number greater than 1 if the ordering is for an ambiguous parse.
Failures: On failure, −2.
— Function: int marpa_o_is_null (Marpa_Order o)
Return value on success: A number greater than or equal to 1 if the ordering is for a null parse; otherwise, 0.
Failures: On failure, −2.
15.5 Non-default ordering
— Function: int marpa_o_high_rank_only_set ( Marpa_Order o, int flag)
— Function: int marpa_o_high_rank_only ( Marpa_Order o)
These methods, respectively, set and discover the “high rank only” flag of ordering o. A flag of 1 indicates that, when ranking, all choices should be discarded except those of the highest rank. A flag of 0 indicates that no choices should be discarded on the basis of their rank.
A value of 1 is the default. The value of the “high rank only” flag has no effect unless ranking has been turned on using the marpa_o_rank() method.
Return value: On success, the value of the “high rank only” flag after the call. On failure, −2.
— Function: int marpa_o_rank ( Marpa_Order o )
By default, the ordering of parse trees is arbitrary. This method causes the ordering to be ranked according to the ranks of symbols and rules, the “null ranks high” flags of the rules, and the “high rank only” flag of the ordering. Once this method returns, the ordering is frozen.
Return value: On success, a non-negative value. On failure, −2.
16 Tree methods
16.1 Overview
Once the bocage has an ordering, the parses trees can be iterated. Marpa's parse tree iterators iterate the parse trees contained in a bocage object. In Libmarpa, “parse tree iterators” are usually just called trees.
To create a tree, use the marpa_t_new() method. A newly created tree iterator is positioned before the first parse tree. When a tree iterator is no longer in use, its memory can be freed using the marpa_t_unref() method.
To position a newly created tree iterator at the first parse tree, use the marpa_t_next() method. Once the tree iterator is positioned at a parse tree, the same marpa_t_next() method is used to position it to the next parse tree.
16.2 Creating a new tree iterator
— Function: Marpa_Tree marpa_t_new (Marpa_Order o)
Creates a new tree iterator, with a reference count of 1. The reference count of its parent ordering object, o, is increased by 1.
When initialized, a tree iterator is positioned before the first parse tree. To position the tree iterator to the first parse, the application must call marpa_t_next().
Return value: On success, a newly created tree. On failure, NULL.
16.3 Reference counting
— Function: Marpa_Tree marpa_t_ref (Marpa_Tree t)
Increases the reference count by 1. Not needed by most applications.
Return value: On success, t. On failure, NULL.
— Function: void marpa_t_unref (Marpa_Tree t)
Decreases the reference count by 1, destroying t once the reference count reaches zero. Beginning with t's parent ordering, 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.
16.4 Iterating through the trees
— Function: int marpa_t_next ( Marpa_Tree t)
Positions t at the next parse tree in the iteration. Tree iterators are initialized to the position before the first parse tree, so this method must be called before creating a valuator from a tree.
If a tree iterator is positioned after the last parse, the tree is said to be “exhausted”. A tree iterator for a bocage with no parse trees is considered to be “exhausted” when initialized. If the tree iterator is exhausted, marpa_t_next() returns −1 as a termination indicator, and sets the error code to MARPA_ERR_TREE_EXHAUSTED.
Return value: On success, a non-negative value. If the tree iterator is exhausted, −1. On failure, −2.
— Function: int marpa_t_parse_count ( Marpa_Tree t)
The parse counter counts the 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.
Return value: The number of parses traversed so far. Always succeeds.
17 Value methods
17.1 Overview
The archetypal application needs a value object (or valuator) to produce the value of the parse. To create a valuator, use the marpa_v_new() method. When a valuator is no longer in use, its memory can be freed using the marpa_v_unref() method.
The application is required to maintain the stack, and the application is also required to implement most of the semantics, including the evaluation of rules. Libmarpa's valuator provides instructions to the application on how to manipulate the stack. To iterate through this series of instructions, use the marpa_v_step() method.
marpa_v_step() returns the type of step. Most step types have values associated with them. To access these values use the methods described in the section Basic step accessors. How to perform the steps is described in the sections How to use the valuator and Stepping through the valuator.
17.2 How to use the valuator
Libmarpa's valuator provides the application with “steps”, which are instructions for stack manipulation. Libmarpa itself does not maintain a stack. This leaves the upper layer in total control of the stack and the values which are placed on it.
As example may make this clearer. Suppose the evalution is at a place in the parse tree where an addition is being performed. Libmarpa does not know that the operation is an addition. It will tell the application that rule number R is to be applied to the arguments at stack locations N and N+1, and that the result is to placed in stack location N.
In this system the application keeps track of the semantics for all rules, so it looks up rule R and determines that it is an addition. The application can do this by using R as an index into an array of callbacks, or by any other method it chooses. Let's assume a callback implements the semantics for rule R. Libmarpa has told the application that two arguments are available for this operation, and that they are at locations N and N+1 in the stack. They might be the numbers 42 and 711. So the callback is called with its two arguments, and produces a return value, let's say, 753. Libmarpa has told the application that the result belongs at location N in the stack, so the application writes 753 to location N.
Since Libmarpa knows nothing about the semantics, the operation for rule R could be string concatenation instead of addition. Or, if it is addition, it could allow for its arguments to be floating point or complex numbers. Since the application maintains the stack, it is up to the application whether the stack contains integers, strings, complex numbers, or polymorphic objects which are capable of being any of these things and more.
17.3 Advantages of step-driven valuation
Step-driven valuation hides Libmarpa's grammar rewrites from the application, and is quite efficient. Libmarpa knows which rules are sequences. Libmarpa optimizes stack manipulations based on this knowledge. Long sequences are very common in practical grammars. For these, the stack manipulations suggested by Libmarpa's step-driven valuator will be significantly faster than the traditional stack evaluation algorithm.
Step-driven evalution has another advantage. To illustrate this, consider what is a very common case: The semantics are implemented in a higher-level language, using callbacks. If Libmarpa did not use step-driven valuation, it would need to provide for this case. But for generality, Libmarpa would have to deal in C callbacks. Therefore, a middle layer would have to create C language wrappers for the callbacks in the higher level language.
The implementation that results is this: The higher level language would need to wrap each callback in C. When calling Libmarpa, it would pass the wrappered callback. Libmarpa would then need to call the C language “wrappered” callback. Next, the wrapper would call the higher-level language callback. The return value, which would be data native to the higher-level language, would need to be passed to the C language wrapper, which will need to make arrangements for it to be based back to the higher-level language when appropriate.
A setup like this is not terribly efficient. And exception handling across language boundaries would be very tricky. But neither of these is the worst problem.
Callbacks are hard to debug. Wrappered callbacks are even worse. Calls made across language boundaries are harder yet to debug. In the system described above, by the time a return value is finally consumed, a language boundary will have been crossed four times.
How do programmers deal with difficulties like this? Usually, by doing the absolute minimum possible in the callbacks. A horrific debugging enviroment can become a manageable one if there is next to no code to be debugged. And this can be accomplished by doing as much as possible in pre- and post-processing.
In essence, callbacks force applications to do most of the programming via side effects. One need not be a functional programming purist to find this a very undesirable style of design to force on an application. But the ability to debug can make the difference between code that does work and code that does not. Unfairly or not, code is rarely considered well-designed when it does not work.
So, while step-driven valuation seems a roundabout approach, it is simpler and more direct than the likely alternatives. And there is something to be said for pushing semantics up to the higher levels — they can be expected to know more about it.
These advantages of step-driven valuation are strictly in the context of a low-level interface. The author is under no illusion that direct use of Libmarpa's valuator will be found satisfactory by most application programmers, even those using the C language. The author certainly avoids using step-driven valuation directly. Libmarpa's valuator is intended to be used via an upper layer, one which does know about semantics.
17.4 Maintaining the stack
This section discusses in detail the requirements for maintaining the stack. In some cases, such as implementation using a Perl array, fulfilling these requirements is trivial. Perl auto-extends its arrays, and initializes the element values, on every read or write. For the C programmer, things are not quite so easy.
In this section, we will assume a C90 or C99 standard-conformant C application. This assumption is convenient on two grounds. First, this will be the intended use for many readers. Second, standard-conformant C is a “worst case”. Any issue faced by a programmer of another environment is likely to also be one that must be solved by the C programmer.
Libmarpa often optimizes away unnecessary stack writes to stack locations. When it does so, it will not necessarily optimize away all reads to that stack location. This means that a location's first access, as suggested by the Libmarpa step instructions, may be a read. This possibility requires a special awareness from the C programmer, as discussed in the sections Sizing the stack and Initializing locations in the stack.
In the discussions in this document, stack locations are non-negative integers. The bottom of the stack is location 0. In moving from the bottom of the stack to the top, the numbers increase. Stack location Y is said to be “greater” than stack location X if stack location Y is closer to the top of stack than location X, and therefore stack locations are considered greater or lesser if the integers that represent them are greater or lesser. Another way to state that a stack location Y is greater (lesser) than stack location X is to say that a stack location Y is later (earlier) than stack location X.
17.4.1 Sizing the stack
If an implementation applies Libmarpa's step instructions literally, using a physical stack, it must make sure the stack is large enough. Specifically, the application must do the following
Ensure location 0 exists — in other words that the stack is at least length 1.
For MARPA_STEP_TOKEN steps, ensure that location marpa_v_result(v) exists.
For MARPA_STEP_NULLING_SYMBOL steps, ensure that location marpa_v_result(v) exists.
For MARPA_STEP_RULE steps, ensure that stack locations from marpa_v_arg_0(v) to marpa_v_arg_n(v) exist.
Three aspects of these requirements deserve special mention. First, note that the requirement for a MARPA_STEP_RULE is that the application size the stack to include the arguments to be read. Because stack writes may be optimized away, an application, when reading, cannot assume that the stack was sized appropriately by a prior write. The first access to a new stack location may be a read.
Second, note that there is no explicit requirement that the application size the stack to include the location for the result of the MARPA_STEP_RULE step. An application is allowed to assume that result will go into one of the locations that were read.
Third, special note should be made of the requirement that location 0 exist. By convention, the parse result resides in location 0 of the stack. Because of potential optimizations, an application cannot assume that it will receive a Libmarpa step instruction that either reads from or writes to location 0.
17.4.2 Initializing locations in the stack
Write optimizations also creates issues for implementations which require data to be initialized before reading. Every fully standard-conforming C application is such an implementation. Both C90 and C99 allow “trap values”, and therefore conforming applications must be prepared for an uninitialized location to contain one of those. Reading a trap value may cause an abend. (It is safe, in standard-conforming C, to write to a location containing a trap value.)
The requirement that locations be initialized before reading occurs in other implementations. Any implementation that has a “universe” of “safe” values, may require special precautions. The required precautions may amount to a need to initialize “uninitialized” values. A practical example might be an implementation that expects all locations to contain a pointer which it can safely indirect from. In such implementations, just as in standard-conformant C, every stack location needs to be initialized before being read.
Due to write optimizations, an application cannot rely on Libmarpa's step instructions to initialize every stack location before its first read. One way to safely deal with the initialization of stack locations, is to do all of the following:
When starting evaluation, ensure that the stack contains at least location 0.
Also, when starting evaluation, initialize every location in the stack.
Whenever the stack is extended, initialize every stack location added.
Applications which try to optimize out some of these initializations need to be aware that an application can never assume that activity in the stack is safely “beyond” an uninitialized location. Libmarpa steps often revisit earlier sections of the stack, and these revisits may include reads of previously unvisited stack locations.
17.5 Creating a new valuator
— Function: Marpa_Value marpa_v_new ( Marpa_Tree t )
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.
Return value: On success, the newly created valuator. On failure, NULL.
17.6 Reference counting
— Function: Marpa_Value marpa_v_ref (Marpa_Value v)
Increases the reference count by 1. Not needed by most applications.
Return value: On success, v. On failure, NULL.
— Function: void marpa_v_unref ( Marpa_Value v)
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.
17.7 Stepping through the valuator
— Function: Marpa_Step_Type marpa_v_step ( Marpa_Value v)
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.
Return value: On success, the type of the step to be performed. This will always be a non-negative number. On failure, −2.
17.8 Valuator steps by type
— Macro: Marpa_Step_Type MARPA_STEP_RULE
The semantics of a rule should be performed. The application can find the value of the rule's children in the stack locations from marpa_v_arg_0(v) to marpa_v_arg_n(v). The semantics for the rule whose ID is marpa_v_rule(v) should be executed on these child values, and the result placed in marpa_v_result(v). In the case of a MARPA_STEP_RULE step, the stack location of marpa_v_result(v) is guaranteed to be equal to marpa_v_arg_0(v).
— Macro: Marpa_Step_Type MARPA_STEP_TOKEN
The semantics of a non-null token should be performed. The application's value for the token whose ID is marpa_v_token(v) should be placed in stack location marpa_v_result(v). Its value according to Libmarpa will be in marpa_v_token_value(v).
— Macro: Marpa_Step_Type MARPA_STEP_NULLING_SYMBOL
The semantics for a nulling symbol should be performed. The ID of the symbol is marpa_v_symbol(v) and its value should be placed in stack location marpa_v_result(v).
— Macro: Marpa_Step_Type MARPA_STEP_INACTIVE
The valuator has gone through all of its steps and is now inactive. The value of the parse will be in stack location 0. Because of optimizations, it is possible for valuator to immediately became inactive — MARPA_STEP_INACTIVE could be both the first and last step.
— Macro: Marpa_Step_Type MARPA_STEP_INITIAL
The valuator is new and has yet to go through any steps.
— Macro: Marpa_Step_Type MARPA_STEP_INTERNAL1
— Macro: Marpa_Step_Type MARPA_STEP_INTERNAL2
— Macro: Marpa_Step_Type MARPA_STEP_TRACE
These step types are reserved for internal purposes.
17.9 Basic step accessors
The basic step accessors are so called because their information is basic to the stack manipulation. The basic step accessors are implemented as macros. They always succeed.
— Macro: int marpa_v_arg_0 (Marpa_Value v)
For a MARPA_STEP_RULE step, returns the stack location where the value of first child can be found.
— Macro: int marpa_v_arg_n (Marpa_Value v)
For a MARPA_STEP_RULE step, returns the stack location where the value of the last child can be found.
— Macro: int marpa_v_result (Marpa_Value v)
For MARPA_STEP_RULE, MARPA_STEP_TOKEN, and MARPA_STEP_NULLING_SYMBOL steps, returns the stack location where the result of the semantics should be placed.
— Macro: Marpa_Rule_ID marpa_v_rule (Marpa_Value v)
For the MARPA_STEP_RULE step, returns the ID of the rule.
— Macro: Marpa_Step_Type marpa_v_step_type (Marpa_Value v)
Returns the current step type: MARPA_STEP_TOKEN, MARPA_STEP_RULE, etc. Usually not needed since this is also the return value of marpa_v_step().
— Macro: Marpa_Symbol_ID marpa_v_symbol (Marpa_Value v)
For the MARPA_STEP_NULLING_SYMBOL step, returns the ID of the symbol. The value returned is the same as that returned by the marpa_v_token() macro.
— Macro: Marpa_Symbol_ID marpa_v_token (Marpa_Value v)
For the MARPA_STEP_TOKEN step, returns the ID of the token. The value returned is the same as that returned by the marpa_v_symbol() macro.
— Macro: int marpa_v_token_value (Marpa_Value v)
For the MARPA_STEP_TOKEN step, returns the integer which is (or which represents) the value of the token.
17.10 Other step accessors
This section contains the step accessors that are not basic to stack manipulation, but which provide other useful information about the parse. These step accessors are implemented as macros.
All of these accessors always succeed, but if called when they are irrelevant they return an unspecified value. In this context, an “unspecified value” is a value that is either −1 or the ID of a valid Earley set, but which is otherwise unpredictable.
— Macro: Marpa_Earley_Set_ID marpa_v_es_id (Marpa_Value v)
Return value: If the current step type is MARPA_STEP_RULE, the Earley Set ordinal where the rule ends. If the current step type is MARPA_STEP_TOKEN or MARPA_STEP_NULLING_SYMBOL, the Earley Set ordinal where the symbol ends. If the current step type is anything else, an unspecified value.
— Macro: Marpa_Earley_Set_ID marpa_v_rule_start_es_id (Marpa_Value v)
Return value: If the current step type is MARPA_STEP_RULE, the Earley Set ordinal where the rule begins. If the current step type is anything else, an unspecified value.
— Macro: Marpa_Earley_Set_ID marpa_v_token_start_es_id (Marpa_Value v)
Return value: If the current step type is MARPA_STEP_TOKEN or MARPA_STEP_NULLING_SYMBOL, the Earley Set ordinal where the token begins. If the current step type is anything else, an unspecified value.
18 Events
18.1 Overview
Events are generated by the marpa_g_precompute(), marpa_r_earleme_complete(), and marpa_r_start_input() methods. The methods are called event-active. Event-active methods always clear all previous events, so that after an event-active method the only events available will be those generated by that method.
Events are volatile, and it is expected that events will be queried immediately after the method that generated them. Note especially that multiple recognizers using the same base grammar overwrite each other's events.
To find out how many events were generated by the last event-active method, use the marpa_g_event_count method.
To query a specific event, use the marpa_g_event and marpa_g_event_value methods.
18.2 Methods
— Function: Marpa_Event_Type marpa_g_event (Marpa_Grammar g, Marpa_Event* event, int ix)
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.
Return value: On success, the type of event ix. If there is no ix'th event, if ix is negative, or on other failure, −2. On failure, the locations pointed to by event are not changed.
— Function: int marpa_g_event_count ( Marpa_Grammar g )
Return value: On success, the number of events. On failure, −2.
— Macro: int marpa_g_event_value (Marpa_Event* event)
This macro provides access to the “value” of the event. The semantics of the value varies according to the type of the event, and is described in the section on event codes. See Event codes.
18.3 Event codes
— Macro: int MARPA_EVENT_NONE
Applications should never see this event. Event value: Undefined. Suggested message: "No event".
— Macro: int MARPA_EVENT_COUNTED_NULLABLE
A nullable symbol is either the separator for, or the right hand side of, a sequence. Event value: The ID of the symbol. Suggested message: "This symbol is a counted nullable".
— Macro: int MARPA_EVENT_EARLEY_ITEM_THRESHOLD
This event indicates the current Earley item count exceeded a user-settable threshold. Event value: The current Earley item count. Suggested message: "Too many Earley items".
— Macro: int MARPA_EVENT_EXHAUSTED
The parse is exhausted. Event value: Undefined. Suggested message: "Recognizer is exhausted".
— Macro: int MARPA_EVENT_LOOP_RULES
One or more rules are loop rules — rules that are part of a cycle. Cycles are pathological cases of recursion, in which the same symbol string derives itself a potentially infinite number of times. Nonetheless, Marpa parses in the presence of these, and it is up to the application to treat these as fatal errors, something they almost always will wish to do. Event value: The count of loop rules. Suggested message: "Grammar contains a infinite loop".
— Macro: int MARPA_EVENT_NULLING_TERMINAL
A nulling symbol is also a terminal. Event value: The ID of the symbol. Suggested message: "This symbol is a nulling terminal".
— Macro: int MARPA_EVENT_SYMBOL_COMPLETED
The recognizer can be set to generate an event a symbol is completed using its marpa_g_symbol_is_completion_event_set() method. (A symbol is "completed" if and only if any rule with that symbol as its LHS is completed.) This event code indicates that one of those events occurred. Event value: The ID of the completed symbol. Suggested message: "Completed symbol".
— Macro: int MARPA_EVENT_SYMBOL_EXPECTED
The recognizer can be set to generate an event when a symbol is expected as a terminal, using its marpa_r_expected_symbol_event_set() method. Note that this event only triggers if the symbol is expected as a terminal. Predicted symbols which are not expected as terminals do not trigger this event. This event code indicates that one of those events occurred. Event value: The ID of the expected symbol. Suggested message: "Expecting symbol".
— Macro: int MARPA_EVENT_SYMBOL_NULLED
The recognizer can be set to generate an event when a symbol is nulled – that is, recognized as a zero-length symbol. To set an nulled symbol event, use the recognizer's marpa_r_nulled_symbol_event_set() method. This event code indicates that a nulled symbol event occurred. Event value: The ID of the nulled symbol. Suggested message: "Symbol was nulled".
— Macro: int MARPA_EVENT_SYMBOL_PREDICTED
The recognizer can be set to generate an event when a symbol is predicted. To set an predicted symbol event, use the recognizer's marpa_r_predicted_symbol_event_set() method. Unlike the MARPA_EVENT_SYMBOL_EXPECTED event, the MARPA_EVENT_SYMBOL_PREDICTED event triggers for predictions of both non-terminals and terminals. This event code indicates that a predicted symbol event occurred. Event value: The ID of the predicted symbol. Suggested message: "Symbol was predicted".
19 Error methods, macros and codes
19.1 Error methods
— Function: Marpa_Error_Code marpa_g_error ( Marpa_Grammar g, const char** p_error_string)
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.
Return value: The last error code from a Libmarpa method. Always succeeds.
— Function: Marpa_Error_Code marpa_g_error_clear ( Marpa_Grammar g )
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.
Return value: MARPA_ERR_NONE. Always succeeds.
19.2 Error Macros
— Macro: int MARPA_ERRCODE_COUNT
The number of error codes. All error codes, whether internal or external, will be integers, non-negative but strictly less than MARPA_ERRCODE_COUNT.
19.3 External error codes
This section lists the external error codes. These are the only error codes that users of the Libmarpa external interface should ever see. Internal error codes are in their own section. See Internal error codes.
— Macro: int MARPA_ERR_NONE
No error condition. The error code is initialized to this value. Methods which do not result in failure sometimes reset the error code to MARPA_ERR_NONE. Numeric value: 0. Suggested message: "No error".
— Macro: int MARPA_ERR_BAD_SEPARATOR
A separator was specified for a sequence rule, but its ID was not that of a valid symbol. Numeric value: 6. Suggested message: "Separator has invalid symbol ID".
— Macro: int MARPA_ERR_BEFORE_FIRST_TREE
A tree iterator is positioned before the first tree, and it was specified in a context where that is not allowed. A newly created tree is positioned before the first tree. To position a newly created tree iterator to the first tree use the marpa_t_next() method. Numeric value: 91. Suggested message: "Tree iterator is before first tree".
— Macro: int MARPA_ERR_COUNTED_NULLABLE
A “counted” symbol was found that is also a nullable symbol. A “counted” symbol is one that appears on the RHS of a sequence rule. If a symbol is nullable, counting its occurrences becomes difficult. Questions of definition and problems of implementation arise. At a minimum, a sequence with counted nullables would be wildly ambigious.
Sequence rules are simply an optimized shorthand for rules that can also be written in ordinary BNF. If the equivalent of a sequence of nullables is really what your application needs, nothing in Libmarpa prevents you from specifying that sequence with ordinary BNF rules.
Numeric value: 8. Suggested message: "Nullable symbol on RHS of a sequence rule".
— Macro: int MARPA_ERR_DUPLICATE_RULE
This error indicates an attempt to add a BNF rule which is a duplicate of a BNF rule already in the grammar. Two BNF rules are considered duplicates if
Both rules have the same left hand symbol, and
Both rules have the same right hand symbols in the same order.
Duplication of sequence rules, and duplication between BNF rules and sequence rules, is dealt with by requiring that the LHS of a sequence rule not be the LHS of any other rule.
Numeric value: 11. Suggested message: "Duplicate rule".
— Macro: int MARPA_ERR_DUPLICATE_TOKEN
This error indicates an attempt to add a duplicate token. A token is a duplicate if one already read at the same earleme has the same symbol ID and the same length. Numeric value: 12. Suggested message: "Duplicate token".
— Macro: int MARPA_ERR_YIM_COUNT
This error code indicates that an implementation-defined limit on the number of Earley items per Earley set was exceedeed. This limit is different from the Earley item warning threshold, an optional limit on the number of Earley items in an Earley set, which can be set by the application.
The implementation defined-limit is very large, at least 500,000,000 earlemes. An application is unlikely ever to see this error. Libmarpa's use of memory would almost certainly exceed the implementation's limits before it occurred. Numeric value: 13. Suggested message: "Maximum number of Earley items exceeded".
— Macro: int MARPA_ERR_EVENT_IX_NEGATIVE
A negative event index was specified. That is not allowed. Numeric value: 15. Suggested message: "Negative event index".
— Macro: int MARPA_ERR_EVENT_IX_OOB
An non-negative event index was specified, but there is no event at that index. Since the events are in sequence, this means it was too large. Numeric value: 16. Suggested message: "No event at that index".
— Macro: int MARPA_ERR_GRAMMAR_HAS_CYCLE
The grammar has a cycle — one or more loop rules. This is a recoverable error, although most applications will want to treat it as fatal. For more see the description of marpa_g_precompute. Numeric value: 17. Suggested message: "Grammar has cycle".
— Macro: int MARPA_ERR_HEADERS_DO_NOT_MATCH
This is an internal error, and indicates that Libmarpa was wrongly built. Libmarpa was compiled with headers which do not match the rest of the code. The solution is to find a correctly built Libmarpa. Numeric value: 98. Suggested message: "Internal error: Libmarpa was built incorrectly"
— Macro: int MARPA_ERR_I_AM_NOT_OK
The Libmarpa base grammar is in a "not ok" state. Currently, the only way this can happen is if Libmarpa memory is being overwritten. Numeric value: 29. Suggested message: "Marpa is in a not OK state".
— Macro: int MARPA_ERR_INACCESSIBLE_TOKEN
This error code indicates that the token symbol is an inaccessible symbol — one which cannot be reached from the start symbol.
Since the inaccessibility of a symbol is a property of the grammar, this error code typically indicates an application error. Nevertheless, a retry at this location, using another token ID, may succeed. At this writing, the author knows of no uses of this technique.
Numeric value: 18. Suggested message: "Token symbol is inaccessible".
— Macro: int MARPA_ERR_INVALID_BOOLEAN
A function was called that takes a boolean argument, but the value of that argument was not either 0 or 1. Numeric value: 22. Suggested message: "Argument is not boolean".
— Macro: int MARPA_ERR_INVALID_LOCATION
The location (Earley set ID) is not valid. It may be invalid for one of two reasons:
It is negative, and it is being used as the argument to a method for which that negative value does not have a special meaning.
It is after the latest Earley set.
For users of input models other than the standard one, the term “location”, as used in association with this error code, means Earley set ID or Earley set ordinal. In the standard input model, this will always be identical with Libmarpa's other idea of location, the earleme.
Numeric value: 25. Suggested message: "Location is not valid".
— Macro: int MARPA_ERR_INVALID_START_SYMBOL
A start symbol was specified, but its symbol ID is not that of a valid symbol. Numeric value: 27. Suggested message: "Specified start symbol is not valid".
— Macro: int MARPA_ERR_INVALID_ASSERTION_ID
A method was called with an invalid assertion ID. This is a assertion ID which not only does not exist, but cannot exist. Currently that means its value is less than zero. Numeric value: 96. Suggested message: "Assertion ID is malformed".
— Macro: int MARPA_ERR_INVALID_RULE_ID
A method was called with an invalid rule ID. This is a rule ID which not only does not exist, but cannot exist. Currently that means its value is less than zero. Numeric value: 26. Suggested message: "Rule ID is malformed".
— Macro: int MARPA_ERR_INVALID_SYMBOL_ID
A method was called with an invalid symbol ID. This is a symbol ID which not only does not exist, but cannot exist. Currently that means its value is less than zero. Numeric value: 28. Suggested message: "Symbol ID is malformed".
— Macro: int MARPA_ERR_MAJOR_VERSION_MISMATCH
There was a mismatch in the major version number between the requested version of libmarpa, and the actual one. Numeric value: 30. Suggested message: "Libmarpa major version number is a mismatch".
— Macro: int MARPA_ERR_MICRO_VERSION_MISMATCH
There was a mismatch in the micro version number between the requested version of libmarpa, and the actual one. Numeric value: 31. Suggested message: "Libmarpa micro version number is a mismatch".
— Macro: int MARPA_ERR_MINOR_VERSION_MISMATCH
There was a mismatch in the minor version number between the requested version of libmarpa, and the actual one. Numeric value: 32. Suggested message: "Libmarpa minor version number is a mismatch".
— Macro: int MARPA_ERR_NO_EARLEY_SET_AT_LOCATION
A non-negative Earley set ID (also called an Earley set ordinal) was specified, but there is no corresponding Earley set. Since the Earley set ordinals are in sequence, this means that the specified ID is greater than that of the latest Earley set. Numeric value: 39. Suggested message: "Earley set ID is after latest Earley set".
— Macro: int MARPA_ERR_NOT_PRECOMPUTED
The grammar is not precomputed, and attempt was made to do something with it that is not allowed for unprecomputed grammars. For example, a recognizer cannot be created from a grammar until it is precomputed. Numeric value: 34. Suggested message: "This grammar is not precomputed".
— Macro: int MARPA_ERR_NO_PARSE
The application attempted to create a bocage from a recognizer without a parse. Applications will often want to treat this as a soft error. Numeric value: 41. Suggested message: "No parse".
— Macro: int MARPA_ERR_NO_RULES
A grammar which has no rules is being used in a way that is not allowed. Usually the problem is that the user is trying to precompute the grammar. Numeric value: 42. Suggested message: "This grammar does not have any rules".
— Macro: int MARPA_ERR_NO_START_SYMBOL
The grammar has no start symbol, and an attempt was made to perform an operation which requires one. Usually the problem is that the user is trying to precompute the grammar. Numeric value: 43. Suggested message: "This grammar has no start symbol".
— Macro: int MARPA_ERR_NO_SUCH_ASSERTION_ID
A method was called with an assertion ID which is well-formed, but the assertion does not exist. Numeric value: 97. Suggested message: "No assertion with this ID exists".
— Macro: int MARPA_ERR_NO_SUCH_RULE_ID
A method was called with a rule ID which is well-formed, but the rule does not exist. Numeric value: 89. Suggested message: "No rule with this ID exists".
— Macro: int MARPA_ERR_NO_SUCH_SYMBOL_ID
A method was called with a symbol ID which is well-formed, but the symbol does not exist. Numeric value: 90. Suggested message: "No symbol with this ID exists".
— Macro: int MARPA_ERR_NO_TOKEN_EXPECTED_HERE
This error code indicates that no tokens at all were expected at this earleme location. This can only happen in alternative input models.
Typically, this indicates an application programming error. Retrying input at this location will always fail. But if the application is able to leave this earleme empty, a retry at a later location, using this or another token, may succeed. At this writing, the author knows of no uses of this technique.
Numeric value: 44. Suggested message: "No token is expected at this earleme location".
— Macro: int MARPA_ERR_NULLING_TERMINAL
Marpa does not allow a symbol to be both nulling and a terminal. Numeric value: 49. Suggested message: "A symbol is both terminal and nulling".
— Macro: int MARPA_ERR_ORDER_FROZEN
The Marpa order object has been frozen. If a Marpa order object is frozen, it cannot be changed.
Multiple tree iterators can share a Marpa order object, but that order object is frozen after the first tree iterator is created from it. Applications can order an bocage in many ways, but they must do so by creating multiple order objects.
Numeric value: 50. Suggested message: "The ordering is frozen".
— Macro: int MARPA_ERR_PARSE_EXHAUSTED
The parse is exhausted. Numeric value: 53. Suggested message: "The parse is exhausted".
— Macro: int MARPA_ERR_PARSE_TOO_LONG
The parse is too long. The limit on the length of a parse is implementation dependent, but it is very large, at least 500,000,000 earlemes.
This error code is unlikely in the standard input model. Almost certainly memory would be exceeded before it could occur. If an application sees this error, it almost certainly using one of the non-standard input models.
Most often this messsage will occur because of a request to add a single extremely long token, perhaps as a result of an application error. But it is also possible this error condition will occur after the input of a large number of long tokens.
Numeric value: 54. Suggested message: "This input would make the parse too long".
— Macro: int MARPA_ERR_POINTER_ARG_NULL
In a method which takes pointers as arguments, one of the pointer arguments is NULL, in a case where that is not allowed. One such method is marpa_r_progress_item(). Numeric value: 56. Suggested message: "An argument is null when it should not be".
— Macro: int MARPA_ERR_PRECOMPUTED
An attempt was made to use a precomputed grammar in a way that is not allowed. Often this is an attempt to change the grammar. Nearly every change to a grammar after precomputation invalidates the precomputation, and is therefore not allowed. Numeric value: 57. Suggested message: "This grammar is precomputed".
— Macro: int MARPA_ERR_PROGRESS_REPORT_NOT_STARTED
No recognizer progress report is currently active, and an action has been attempted which is inconsistent with that. One such action would be a marpa_r_progress_item() call. Numeric value: 59. Suggested message: "No progress report has been started".
— Macro: int MARPA_ERR_PROGRESS_REPORT_EXHAUSTED
The progress report is “exhausted” — all its items have been iterated through. Numeric value: 58. Suggested message: "The progress report is exhausted".
— Macro: int MARPA_ERR_RANK_TOO_LOW
A symbol or rule rank was specified which was less than an implementation-defined minimum. Implementations will always allow at least those ranks in the range between −134,217,727 and 134,217,727. Numeric value: 85. Suggested message: "Rule or symbol rank too low".
— Macro: int MARPA_ERR_RANK_TOO_HIGH
A symbol or rule rank was specified which was greater than an implementation-defined maximum. Implementations will always allow at least those ranks in the range between −134,217,727 and 134,217,727. Numeric value: 86. Suggested message: "Rule or symbol rank too high".
— Macro: int MARPA_ERR_RECCE_IS_INCONSISTENT
The recognizer is “inconsistent”, usually because the user has rejected one or more rules or terminals, and has not yet called the marpa_r_consistent() method. Numeric value: 95. Suggested message: "The recognizer is inconsistent.
— Macro: int MARPA_ERR_RECCE_NOT_ACCEPTING_INPUT
The recognizer is not accepting input, and the application has attempted something that is inconsistent with that fact. Numeric value: 60. Suggested message: "The recognizer is not accepting input".
— Macro: int MARPA_ERR_RECCE_NOT_STARTED
The recognizer has not been started. and the application has attempted something that is inconsistent with that fact. Numeric value: 61. Suggested message: "The recognizer has not been started".
— Macro: int MARPA_ERR_RECCE_STARTED
The recognizer has been started. and the application has attempted something that is inconsistent with that fact. Numeric value: 62. Suggested message: "The recognizer has been started".
— Macro: int MARPA_ERR_RHS_IX_NEGATIVE
The index of a RHS symbol was specified, and it was negative. That is not allowed. Numeric value: 63. Suggested message: "RHS index cannot be negative".
— Macro: int MARPA_ERR_RHS_IX_OOB
A non-negative index of RHS symbol was specified, but there is no symbol at that index. Since the indexes are in sequence, this means the index was greater than or equal to the rule length. Numeric value: 64. Suggested message: "RHS index must be less than rule length".
— Macro: int MARPA_ERR_RHS_TOO_LONG
An attempt was made to add a rule with too many right hand side symbols. The limit on the RHS symbol count is implementation dependent, but it is very large, at least 500,000,000 symbols. This is far beyond what is required in any current practical grammar. An application with rules of this length is almost certain to run into memory and other limits. Numeric value: 65. Suggested message: "The RHS is too long".
— Macro: int MARPA_ERR_SEQUENCE_LHS_NOT_UNIQUE
The LHS of a sequence rule cannot be the LHS of any other rule, whether a sequence rule or a BNF rule. An attempt was made to violate this restriction. Numeric value: 66. Suggested message: "LHS of sequence rule would not be unique".
— Macro: int MARPA_ERR_START_NOT_LHS
The start symbol is not on the LHS on any rule. That means it could never match any possible input, not even the null string. Presumably, an error in writing the grammar. Numeric value: 73. Suggested message: "Start symbol not on LHS of any rule".
— Macro: int MARPA_ERR_SYMBOL_IS_NOT_COMPLETION_EVENT
An attempt was made to use a symbol in a way that requires it to be set up for completion events, but the symbol was not set set up for completion events. The archtypal case is an attempt to activate completion events for the symbol in the recognizer. The archtypal case is an attempt to activate a completion event in the recognizer for a symbol that is not set up as a completion event. Numeric value: 92. Suggested message: "Symbol is not set up for completion events".
— Macro: int MARPA_ERR_SYMBOL_IS_NOT_NULLED_EVENT
An attempt was made to use a symbol in a way that requires it to be set up for nulled events, but the symbol was not set set up for nulled events. The archtypal case is an attempt to activate a nulled events in the recognizer for a symbol that is not set up as a nulled event. Numeric value: 93. Suggested message: "Symbol is not set up for nulled events".
— Macro: int MARPA_ERR_SYMBOL_IS_NOT_PREDICTION_EVENT
An attempt was made to use a symbol in a way that requires it to be set up for predictino events, but the symbol was not set set up for predictino events. The archtypal case is an attempt to activate a prediction event in the recognizer for a symbol that is not set up as a prediction event. Numeric value: 94. Suggested message: "Symbol is not set up for prediction events".
— Macro: int MARPA_ERR_SYMBOL_VALUED_CONFLICT
Unvalued symbols are a deprecated Marpa feature, which may be avoided with the marpa_g_force_valued method. An unvalued symbol may take on any value, and therefore a symbol which is unvalued at some points cannot safely to be used to contain a value at others. This error indicates that such an unsafe use is being attempted. Numeric value: 74. Suggested message: "Symbol is treated both as valued and unvalued".
— Macro: int MARPA_ERR_TERMINAL_IS_LOCKED
An attempt was made to change the terminal status of a symbol to a different value after it was locked. Numeric value: 75. Suggested message: "The terminal status of the symbol is locked".
— Macro: int MARPA_ERR_TOKEN_IS_NOT_TERMINAL
A token was specified whose symbol ID is not a terminal. Numeric value: 76. Suggested message: "Token symbol must be a terminal".
— Macro: int MARPA_ERR_TOKEN_LENGTH_LE_ZERO
A token length was specified which is less than or equal to zero. Zero-length tokens are not allowed in Libmarpa. Numeric value: 77. Suggested message: "Token length must greater than zero".
— Macro: int MARPA_ERR_TOKEN_TOO_LONG
The token length is too long. The limit on the length of a token is implementation dependent, but it is at least 500,000,000 earlemes. An application using a token that long is almost certain to run into some other limit. Numeric value: 78. Suggested message: "Token is too long".
— Macro: int MARPA_ERR_TREE_EXHAUSTED
A Libmarpa parse tree iterator is “exhausted”, that is, it has no more parses. Numeric value: 79. Suggested message: "Tree iterator is exhausted".
— Macro: int MARPA_ERR_TREE_PAUSED
A Libmarpa tree is “paused” and an operation was attempted which is inconsistent with that fact. Typically, this operation will be a call of the marpa_t_next() method. Numeric value: 80. Suggested message: "Tree iterator is paused".
— Macro: int MARPA_ERR_UNEXPECTED_TOKEN_ID
An attempt was made to read a token where a token with that symbol ID is not expected. This message can also occur when an attempt is made to read a token at a location where no token is expected. Numeric value: 81. Suggested message: "Unexpected token".
— Macro: int MARPA_ERR_UNPRODUCTIVE_START
The start symbol is unproductive. That means it could never match any possible input, not even the null string. Presumably, an error in writing the grammar. Numeric value: 82. Suggested message: "Unproductive start symbol".
— Macro: int MARPA_ERR_VALUATOR_INACTIVE
The valuator is inactive in a context where that should not be the case. Numeric value: 83. Suggested message: "Valuator inactive".
— Macro: int MARPA_ERR_VALUED_IS_LOCKED
Unvalued symbols are a deprecated Marpa feature, which may be avoided with the marpa_g_force_valued method. This error code indicates that the valued status of a symbol is locked, and an attempt was made to change it to a status different from the current one. Numeric value: 84. Suggested message: "The valued status of the symbol is locked".
— Macro: int MARPA_ERR_SYMBOL_IS_NULLING
An attempt was made to do something with a nulling symbol that is not allowed. For example, the ID of a nulling symbol cannot be an argument to marpa_r_expected_symbol_event_set — because it is not possible to create an “expected symbol” event for a nulling symbol. Numeric value: 87. Suggested message: "Symbol is nulling".
— Macro: int MARPA_ERR_SYMBOL_IS_UNUSED
An attempt was made to do something with a nulling symbol that is not allowed. An “unused” symbol is a inaccessible or unproductive symbol. For example, the ID of a unused symbol cannot be an argument to marpa_r_expected_symbol_event_set — because it is not possible to create an “expected symbol” event for a nulling symbol. Numeric value: 88. Suggested message: "Symbol is not used".
19.4 Internal error codes
An internal error code may be one of two things: First, it can be an error code which arises from an internal Libmarpa programming issue (in other words, something happening in the code that was not supposed to be able to happen.) Second, it can be an error code which only occurs when a method from Libmarpa's internal interface is used. Both kinds of internal error message share one common trait — users of the Libmarpa's external interface should never see them.
Internal error messages require someone with knowledge of the Libmarpa internals to follow up on them. They usually do not have descriptions or suggested messages.
— Macro: int MARPA_ERR_AHFA_IX_NEGATIVE
Numeric value: 1.
— Macro: int MARPA_ERR_AHFA_IX_OOB
Numeric value: 2.
— Macro: int MARPA_ERR_ANDID_NEGATIVE
Numeric value: 3.
— Macro: int MARPA_ERR_ANDID_NOT_IN_OR
Numeric value: 4.
— Macro: int MARPA_ERR_ANDIX_NEGATIVE
Numeric value: 5.
— Macro: int MARPA_ERR_BOCAGE_ITERATION_EXHAUSTED
Numeric value: 7.
— Macro: int MARPA_ERR_DEVELOPMENT
"Development" errors were used heavily during Libmarpa's development, when it was not yet clear how precisely to classify every error condition. Unless they are using a developer's version, users of the external interface should never see development errors.
Development errors have an error string associated with them. The error string is a short 7-bit ASCII error string which describes the error. Numeric value: 9. Suggested message: "Development error, see string".
— Macro: int MARPA_ERR_DUPLICATE_AND_NODE
Numeric value: 10.
— Macro: int MARPA_ERR_YIM_ID_INVALID
Numeric value: 14.
— Macro: int MARPA_ERR_INTERNAL
A “catchall” internal error. Numeric value: 19.
— Macro: int MARPA_ERR_INVALID_AHFA_ID
The AHFA ID was invalid. There are no AHFAs any more, so this message should not occur. Numeric value: 20.
— Macro: int MARPA_ERR_INVALID_AIMID
The AHM ID was invalid. The term “AIMID” is a legacy of earlier implementations and must be kept for backward compatibility. Numeric value: 21.
— Macro: int MARPA_ERR_INVALID_IRLID
Numeric value: 23.
— Macro: int MARPA_ERR_INVALID_NSYID
Numeric value: 24.
— Macro: int MARPA_ERR_NOOKID_NEGATIVE
Numeric value: 33.
— Macro: int MARPA_ERR_NOT_TRACING_COMPLETION_LINKS
Numeric value: 35.
— Macro: int MARPA_ERR_NOT_TRACING_LEO_LINKS
Numeric value: 36.
— Macro: int MARPA_ERR_NOT_TRACING_TOKEN_LINKS
Numeric value: 37.
— Macro: int MARPA_ERR_NO_AND_NODES
Numeric value: 38.
— Macro: int MARPA_ERR_NO_OR_NODES
Numeric value: 40.
— Macro: int MARPA_ERR_NO_TRACE_YS
Numeric value: 46.
— Macro: int MARPA_ERR_NO_TRACE_PIM
Numeric value: 47.
— Macro: int MARPA_ERR_NO_TRACE_YIM
Numeric value: 45.
— Macro: int MARPA_ERR_NO_TRACE_SRCL
Numeric value: 48.
— Macro: int MARPA_ERR_ORID_NEGATIVE
Numeric value: 51.
— Macro: int MARPA_ERR_OR_ALREADY_ORDERED
Numeric value: 52.
— Macro: int MARPA_ERR_PIM_IS_NOT_LIM
Numeric value: 55.
— Macro: int MARPA_ERR_SOURCE_TYPE_IS_NONE
Numeric value: 70.
— Macro: int MARPA_ERR_SOURCE_TYPE_IS_TOKEN
Numeric value: 71.
— Macro: int MARPA_ERR_SOURCE_TYPE_IS_COMPLETION
Numeric value: 68.
— Macro: int MARPA_ERR_SOURCE_TYPE_IS_LEO
Numeric value: 69.
— Macro: int MARPA_ERR_SOURCE_TYPE_IS_AMBIGUOUS
Numeric value: 67.
— Macro: int MARPA_ERR_SOURCE_TYPE_IS_UNKNOWN
Numeric value: 72.
20 Design notes
Design apologetics are throughout this document, dispersed among sections where it is hoped that they motivate the description or discussion. The notes in this section did not find a home elsewhere.
20.1 Why so many time objects?
Marpa is an aggressively multi-pass algorithm. Marpa achieves its efficiency, not in spite of making multiple passes over the data, but because of it. Marpa regularly substitutes two fast O(n) passes for a single O(n log n) pass. Marpa's proliferation of time objects is in keeping with its multi-pass approach.
Bocage objects come at no cost, even for unambiguous parses, because the same pass which creates the bocage also deals with other issues which are of major significance for unambiguous parses. It is the post-processing of the bocage pass that enables Marpa to do both left- and right-recursion in linear time.
Of the various objects, the best case for elimination is of the ordering object. In many cases, the ordering is trivial. Either the parse is unambiguous, or the application does not care about the order in which parses are returned. But while it would be easy to add an option to bypass creation of an ordering object, there is little to be gained from it. When the ordering is trivial, its overhead is very small — essentially a handful of subroutine calls. Many orderings accomplish nothing, but these cost next to nothing.
Tree objects come at minimal cost to unambiguous grammars, because the same pass that allows iteration through multiple parse trees does the tree traversal. This eliminates much of the work that otherwise would need to be done in the valuation time object. In the current implement, the valuation time object needs only to step through a sequence already determined in the tree iterator.
20.2 Numbered objects
As the name suggests, the choice was made to implement numbered objects as integers, and not as pointers. In standard-conformant C, integers can be safely checked for validity, while pointers cannot.
There are efficiency tradeoffs between pointers and integers but they are complicated, and they go both ways. Pointers can be faster, but integers can be used as indexes into more than one data structure. Which is actually faster depends on the design. Integers allow for a more flexible design, so that once the choice is settled on, careful programming can make them a win, possibly a very big one.
The approach taken in Libmarpa was to settle, from the outset, on integers as the implementation for numbered objects, and to optimize on that basis. The author concedes that it is possible that others redoing Libmarpa from scratch might find that pointers are faster. But the author is confident that they will also discover, on modern architectures, that the lack of safe validity checking is far too high a price to pay for the difference in speed.
20.3 LHS terminals
Marpa's idea in losing the sharp division between terminals and non-terminals is that the distinction, while helpful for proving theorems, is not essential in practice. LHS symbols in the input might be useful for “short circuiting” the rules in which they occur. This may prove helpful in debugging, or have other applications.
However, it also can be useful, for checking input validity as well as for efficiency, to follow tradition and distinguish non-terminals from terminals. For this reason, the traditional behavior is the default in Libmarpa.
21 Work in Progress
21.1 Untested methods
The methods of this section are not in the external interface, because they have not been adequately tested. Their fate is uncertain. Users should regard these methods as unsupported.
21.1.1 Ranking methods
— Function: Marpa_Rank marpa_g_default_rank ( Marpa_Grammar g)
— Function: Marpa_Rank marpa_g_default_rank_set ( Marpa_Grammar g, Marpa_Rank 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.
Return value: On success, 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.
— Function: Marpa_Rank marpa_g_symbol_rank ( Marpa_Grammar g, Marpa_Symbol_ID sym_id)
— Function: Marpa_Rank marpa_g_symbol_rank_set ( Marpa_Grammar g, Marpa_Symbol_ID sym_id, Marpa_Rank 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.
Return value: On success, 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.
21.1.2 Zero-width assertion methods
— Function: Marpa_Assertion_ID marpa_g_zwa_new ( Marpa_Grammar g, int default_value)
— Function: int marpa_g_zwa_place ( Marpa_Grammar g, Marpa_Assertion_ID zwaid, Marpa_Rule_ID xrl_id, int rhs_ix)
— Function: int marpa_r_zwa_default ( Marpa_Recognizer r, Marpa_Assertion_ID zwaid)
On success, returns previous default value of the assertion.
— Function: int marpa_r_zwa_default_set ( Marpa_Recognizer r, Marpa_Assertion_ID zwaid, int default_value)
Changes default value to default_value. On success, returns previous default value of the assertion.
— Function: Marpa_Assertion_ID marpa_g_highest_zwa_id ( Marpa_Grammar g )
21.1.3 Methods for revising parses
Marpa allows an application to “change its mind” about a parse, rejected rule previously recognized or predicted, and terminals previously scanned. The methods in this section provide that capability.
— Function: Marpa_Earleme marpa_r_clean ( Marpa_Recognizer r)
22 Deprecated techniques and methods
22.1 Valued and unvalued symbols
22.1.1 What unvalued symbols were
Libmarpa symbols can have values, which is the traditional way of doing semantics. Libmarpa also allows symbols to be unvalued. An unvalued symbol is one whose value is unpredictable from instance to instance. If a symbol is unvalued, we sometimes say that it has “whatever” semantics.
Situations where the semantics can tolerate unvalued symbols are surprisingly frequent. For example, the top-level of many languages is a series of major units, all of whose semantics are typically accomplished via side effects. The compiler is typically indifferent to the actual value produced by these major units, and tracking them is a waste of time. Similarly, the value of the separators in a list is typically ignored.
Rules are unvalued if and only if their LHS symbols are unvalued. When rules and symbols are unvalued, Libmarpa optimizes their evaluation.
It is in principle unsafe to check the value of a symbol if it can be unvalued. For this reason, once a symbol has been treated as valued, Libmarpa marks it as valued. Similarly, once a symbol has been treated as unvalued, Libmarpa marks it as unvalued. Once marked, a symbol's valued status is locked and cannot be changed later.
The valued status of terminals is marked the first time they are read. The valued status of LHS symbols must be explicitly marked by the application when initializing the valuator — this is Libmarpa's equivalent of registering a callback.
LHS terminals are disabled by default. If allowed, the user should be aware that the valued status of a LHS terminal will be locked in the recognizer if it is used as a terminal, and the symbol's use as a rule LHS in the valuator must be consistent with the recognizer's marking.
Marpa reports an error when a symbol's use conflicts with its locked valued status. Doing so usually saves the programmer some tricky debugging further down the road.
22.1.2 Grammar methods dealing with unvalued symbols
— Function: int marpa_g_symbol_is_valued ( Marpa_Grammar g, Marpa_Symbol_ID symbol_id)
— Function: int marpa_g_symbol_is_valued_set ( Marpa_Grammar g, Marpa_Symbol_ID symbol_id, int value)
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.
Return value: On success, 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.
22.1.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 ( Marpa_Value v, Marpa_Symbol_ID sym_id )
— Function: int marpa_v_symbol_is_valued_set ( Marpa_Value v, Marpa_Symbol_ID sym_id, int value )
These methods, respectively, discover and set to value, the valued status for symbol sym_id. 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 failure, −2.
— Function: int marpa_v_rule_is_valued ( Marpa_Value v, Marpa_Rule_ID rule_id )
— Function: int marpa_v_rule_is_valued_set ( Marpa_Value v, Marpa_Rule_ID rule_id, int value )
These methods respectively, discover and set to value, the valued status for the LHS symbol of rule rule_id. 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.
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 failure, −2.
— Function: int marpa_v_valued_force ( Marpa_Value v)
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.
Return value: On success, a non-negative number. On failure, returns −2, and sets the error code to an appropriate value, which will never be MARPA_ERR_NONE.
Appendix A GNU Free Documentation License
Version 1.3, 3 November 2008
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
http://fsf.org/
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
PREAMBLE
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
The “publisher” means any person or entity that distributes copies of the Document to the public.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
VERBATIM COPYING
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
MODIFICATIONS
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
State on the Title page the name of the publisher of the Modified Version, as the publisher.
Preserve all the copyright notices of the Document.
Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
Include an unaltered copy of this License.
Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
COMBINING DOCUMENTS
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”
COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
TRANSLATION
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
TERMINATION
You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.
FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Document.
RELICENSING
“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.
“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.
“Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.
An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.
ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this:
with the Invariant Sections being list their titles, with
the Front-Cover Texts being list, and with the Back-Cover Texts
being list.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
-------------
This manual (12 November 2014) is for Libmarpa 7.3.0.
Copyright © 2014 Jeffrey Kegler.
http://irclog.perlgeek.de/marpa/2014-12-07#i_9772028
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment