For the purposes of this module, a notation will be any way in which one can encode, as a text string, a non-environment Logic Concept. (For the definition of Logic Concepts, or LCs, refer to the documentation in another repository.) For example, putdown notation, as defined in that repository, is an example of a "notation," according to this definition.
A parsing function will be a function that inspects a text string and does the following two things:
- If the text string does not correctly express one or more Logic Concepts in the expected notation, return an error object as described below.
- Otherwise, return a JavaScript array containing the Logic Concept instance(s) described by the input. You must return an array in any case, even if there is exactly one Logic Concept in it.
An error object must have a message field, containing a string describing
the problem in a human-readable way. It may optionally also have a
position field, an integer between 0 and the length of the input
(inclusive) indicating where the problem occurred. Indexes into the input
range from 0 to one less than its length, and so an error position equal to
the input length can be used to express that something was missing at the end
of the input, such as a close grouper.
A representation function will be a function that accepts as input the same notation you would pass to the corresponding parsing function, but instead of producing a Logic Concept instance, it produces a text string containing the HTML representation of the meaning. For instance, the representation for putdown notation could be just the code in fixed-width font, but the representation for $\LaTeX$ could be the typeset version in HTML.
This module installs multiple parsing and representation functions, including ones for putdown, smackdown, $\LaTeX$, and WYSIWYG math editing. It also provides functions clients can use to install additional parsing and representation functions, or query the set of currently installed ones.
Source
Methods
addParser(name, func)
Install a new parsing function into this module. Provide the name of the notation, together with a function whose behavior works as documented at the top of this module. If you call this function more than once with the same name, you will overwrite any function you installed in the past for the same name with the new function.
Parameters
-
name
stringthe name of the notation
-
func
functionthe parsing function, with signature and behavior as documented at the top of this module
Source
addRepresentation(name, func)
Install a new representation function into this module. Provide the name of the notation, together with a function whose behavior works as documented at the top of this module. If you call this function more than once with the same name, you will overwrite any function you installed in the past for the same name with the new function.
Parameters
-
name
stringthe name of the notation
-
func
functionthe representation function, with signature and behavior as documented at the top of this module
See
Source
markNameAsMath(name)
Mark any of the names you've installed using addParser() as one that should be edited in the UI using a math editor, as opposed to a plain text input. The default is that all notations are written in plain text, but if you mark one with this function as requiring a math editor, then all dialogs that let the user write in that notation will present a math editor instead of a plain text box.
Parameters
-
name
stringthe name of the notation
Source
names() → {Array.<string>}
This function returns a list of all the installed parsing functions, which is just a list of their names, each one a string.
Returns
-
Array.<string>the names of all installed parsing functions
Source
parse(input, notationName) → {LogicConcept|Object}
Apply the parser for a given notation to some text input. Return either a Logic Concept (if the input was understandable as an expression in the given notation, according to the rules at the top of this module), or an error object otherwise (also structured according to that same documentation).
Parameters
-
input
stringthe input to be parsed
-
notationName
stringthe name of the notation function to use for parsing
Returns
-
LogicConceptObjecteither a LogicConcept instance, upon success, or an error object, upon failure, as described above
Source
putdownHTML(LC) → {string}
Create an HTML representation of the putdown notation for any LC or array of LCs. This will be used as a debugging tool for any power user who wants to see the code for any atom in their document. This is the more technical version of syntaxTreeHTML().
Parameters
-
LC
LogicConcept|Array.<LogicConcept>the LogicConcept to be represented, or an array of LogicConcepts to be represented
See
Returns
-
stringthe HTML representation of the LogicConcept(s)
Source
represent(code, notationName) → {string}
Apply the representation function for a given notation to some text input. Return the output of that representation function, if one for that notation is installed, or throw an error if none is installed.
Parameters
-
code
stringthe code to be represented in HTML
-
notationName
stringthe name of the notation in which the code is expressed
Returns
-
stringthe HTML representation of the code
Source
syntaxTreeHTML(LC) → {string}
Create a universally understandable HTML representation for any LC or array of LCs. This will be used as a debugging tool for any power user who wants to see a syntax-tree-like representation of any atom in their document. This is the more user-friendly version of putdownHTML().
Parameters
-
LC
LogicConcept|Array.<LogicConcept>the LogicConcept to be represented, or an array of LogicConcepts to be represented
See
Returns
-
stringthe HTML representation of the LogicConcept(s)
Source
usesMathEditor(name) → {boolean}
Check whether the given notation has been marked as a mathematical one, using the markNameAsMath() function.
Parameters
-
name
stringthe name of the notation to check
See
Returns
-
booleanwhether the given name uses a WYSIWYG math editor when the user is typing in content using that notation