marpa_util - Marpa/Tcl - marpa::util
Welcome to Marpa/Tcl, a Tcl binding to the "libmarpa" parsing engine.
Please read the document Marpa/Tcl - Introduction to Marpa/Tcl, if you have not done so already. It provides an overview of the whole system.
This document describes a mainly internal package of Marpa/Tcl.
The package commands provide access to information about unicode characters useful to parsers, and parser generators, i.e. case folding classes, named character classes, etc.
This command sets the key of dictionary variable tmp to value. The variable resides in the caller's scope.
The result of the command is the empty string.
This command sets the key of dictionary variable spec to the contents of dictionary variable tmp. After the assignment tmp is unset. Both variables reside in the caller's scope.
The result of the command is the empty string.
This command sets the key of dictionary variable spec to the empty string. The variable resides in the caller's scope.
The result of the command is the empty string.
This command sets the key of the dictionary variable named by dstvarname to the contents of the dictionary variable named by srcvarname. After the assignment the source variable is unset. Both variables reside in the caller's scope.
The result of the command is the empty string.
The commands of this section are for use within the message of debug commands. Both enable the execution of side effects specific to the active narrative tracing tag.
This command runs the script in the context of the caller of the debug command whose message it is part of. This enables the activation of side effect specific to and in support of the active tag associated with that debug command.
The result of the command is the empty string.
This is command is like marpa::D, except that it returns label as its result, leaving a trace of itself in the debug output.
The commands of this section are for use within TclOO class definition scripts and methods, to simplify the generation of customized errors.
This command has to be run in TclOO class definition scripts. It arranges for the creation of a method E in that class which simplifies the raising of custom errors.
The label is used as the tag for narrative tracing of E's invokations. The following words, if specified, are used to extend the base error of MARPA with class-specific information.
The result of the command is the empty string. The new method E has the following signature and behaviour:
This method raises a Tcl error with error message msg, and an error code consisting of the word MARPA, followed by the words specified with marpa::E] when creating the method, and then the words given to itself.
This is command is like marpa::E, except that the created method E is configured to place the prefix in front of the messages it is invoked with.
The result of the command is the empty string.
This command raises a Tcl error with error message msg, and an error code consisting of the word MARPA followed by the words it was given.
This command imports the command cmd into the namespace of the caller's scope, for easy access. By default the tail of the qualified command name is used as the name the command will be accessible though. Specify a non-empty dst if a different name is wanted. By default cmd is resolved to its fully qualified name in the caller's caller. Specify the up level if a different scope has to be used.
The result of the command is the empty string.
This command resolves the command stored in the named variable cmdvarname to its fully-qualified name and returns that as its result. The named variable resides in the caller's scope. By default the command is resolved to its fully qualified name in the caller's caller. Specify the up level if a different scope has to be used.
The command in this section are the management of assets attached to the end of Tcl script files, after a separating Ctrl-Z character, i.e. unicode codepoint 26, "\x1a".
The standard use of these commands is to invoke them with the result of [info script] to extract any assets attached to the script file the currently running procedure came from.
This command assumes that the file pointed to by path contains one or more assets attached to it, separated by "\x1a" from the main file and each each other. It reads these assets and then returns a list containing them, in their order of attachment.
Invoking this command for the same path multiple times will read the assets only once into memory, on the first call. All further calls are served from an internal cache.
This command is like marpa::asset*, except that it assumes that only a single asset is attached to the referenced file and returns that asset directly, without wrapping it into a list.
Invoking this command on a file which has multiple assets attached means that the returned result will contain the "\x1A" characters separating these assets from each other.
Location atoms are triples (3-element lists) containing a start location, end location, and string. The start and end specify a range, with the two ends included in it.
The null location is represented by the triple whose elements are all the empty string.
This command takes one or more location atoms and returns a new location atom which merges together. If only a single atom is specified then that atom is returned unchanged.
The merging is performed by taking the first atom and repeatedly merging the other atoms to it, via marpa::location::merge2.
This command takes two atoms and returns their merge. The rules of merging are
If any of the argument atoms is the null location the other is returned unchanged.
An error is thrown if the end-location of a is not exactly adjacent to the start location of b.
The result contains the start location of a, the end location of b and the string concatening the strings of
This command reformats the location for human readability and returns the result. The only change is quoting the string element as a C string, i.e. wrapping into single-quotes and characters special to C are backslash-escaped, either named, or as octals.
This command returns a location where both start and end are position, and the string is string.
This command returns the null location.
This command tests if the argument represents the null location and returns true if so, and false otherwise.
This command returns the null location while ignore all of its arguments.
This command takes list values, removes the elements referenced by the indices in the list mask, and returns the filtered result.
Note that the command assumes that mask contains the indices in decreasing order Invoking the command with mask unsorted or sorfted in increasing order will yield undefined results.
This command returns x as its result. It ignores y. In respect it is like a K-combinator.
The side effects y may have in caller's scope are of course executed before K executes. Like, for example, unsetting the variable providing x, thus decrementing the reference count of x.
This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such at the Marpa/Tcl Tracker. Please report any ideas for enhancements you may have for either package and/or documentation as well.
aycock, character classes, context free grammar, document processing, earley, horspool, joop leo, lexing, libmarpa, nigel horspool, parsing, regex, table parsing
Copyright © 2015-present Andreas Kupries
Copyright © 2018-present Documentation, Andreas Kupries