/** \mainpage
*
* This is the <a href='http://lurch.sourceforge.net'>Lurch</a> source code documentation,
* containing details of all implemented features and decisions.
* See the tabs at the top left.
*
* <h3>New here? See the <a href='quickref.html'>Quick Reference</a>.</h3>
*
* This page gives a quick overview of the source code documentation,
* but other resources are available on
* <a href='http://lurch.sourceforge.net'>the main Lurch page</a>.
*
* If you're interested in testing out Lurch, see
* <a href='http://lurch.sourceforge.net'>the Lurch homepage</a>.<br>
* If you want to get the source code for deeper testing and/or
* development, try the \link installation Lurch Installation Guide\endlink.
*
* <h2>The Source Code</h2>
*
* <h3>Specification</h3>
*
* There is
* \link design a page that describes the concepts which the Lurch source code
* implements\endlink.
* It reads a bit more high-level, and may be a good place to go to familiarize yourself
* with the terminology, and get a broad view of what's going on before diving into details.
*
* <h3>External subprojects</h3>
*
* The Lurch Team gratefully acknowledges several open source projects on which we depend,
* some of which are imported into our source code using the <code>svn:externals</code>
* Subversion property,
* <a href='http://svnbook.red-bean.com/nightly/en/svn.advanced.externals.html'>documented
* here</a>. You will not find documentation
* of those projects in our source code docs, because that would take up space needlessly.
* Any file beneath
* <a href='http://lurch.svn.sourceforge.net/viewvc/lurch/Lurch/trunk/externals/'
* >trunk/externals/</a> is part of an external subproject, and you can find
* its documentation at its home page. See
* <a href='http://lurch.svn.sourceforge.net/viewvc/lurch/Lurch/trunk/externals/README.txt'
* >trunk/externals/README.txt</a> for links to their homepages.
*
* <h3>Specific C++ Classes</h3>
*
* The main class in the Lurch project is the Lurch Object class, called Lob. Its
* documentation is a good place to start for the technical details on which Lurch is built.
* If you're a script author and want to see what the Lobs you can get your hands on can
* do, see <a href='#script'>the Scripting section</a>, below.
*
* Other important C++ classes that have been fully implemented are mentioned on the
* \link design implemented design page\endlink, already linked to from above.
* Classes not yet fully implemented (e.g., LurchEnvironment, which is partially done)
* are described on the Lurch wiki's
* <a href='http://lurch.wiki.sourceforge.net/Foundational+Specification'>Foundational
* Specification page</a>.
*
* Note that Lurch Reference, Lurch Function, and Lurch Document are concepts
* whose functionality is part of the Lob class, since they are all special kinds of Lobs.
* Thus they are not embodied in any specific class, though conceptually they are distinct.
*
* <h2>Testing</h2>
*
* Unit testing is a big part of the Lurch development effort. We aim to test rigorously
* every method we write, and the files in the tests subdirectory go a long way toward that
* goal. See <a href='annotated.html'>the Classes page</a> and look for every class that
* begins with <code>test_</code>. Each such class is documented with what it tests, and
* every method tested should also link back to the class and method which tests it.
*
* We also test Lurch using Lurch javascript scripts. Such testing scripts are in the
* <a href='http://lurch.svn.sourceforge.net/viewvc/lurch/Lurch/trunk/tests/script_tests/'
* >tests/script_tests</a> subfolder of the Lurch svn trunk. The file
* <a href='http://lurch.svn.sourceforge.net/viewvc/lurch/Lurch/trunk/tests/script_tests/example.js'
* ><code>example.js</code></a> explains how to add additional test files to the collection.
*
* To invoke all tests simultaneously, run
* <a href='http://lurch.svn.sourceforge.net/viewvc/lurch/Lurch/trunk/utils/testlurch'>the
* <code>testlurch</code> shell script</a> from the command line. Not only does it run all
* C++ and Lurch script tests, but it also builds all utilities in
* <a href='http://lurch.svn.sourceforge.net/viewvc/lurch/Lurch/trunk/utils'>the
* <code>utils</code> subdirectory</a> and ensures they compile acceptably.
*
* <a name='script'><h2>Scripting</h2></a>
*
* The main documentation for script authors is our
* <a href='scripting.html'>Lurch Scripting with simple_script</a> page.
* Additional references are listed here.
* <ul>
<li><a href='http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide'>
Mozilla Developers Guide to javascript</a></li>
* <li><a href='http://en.wikipedia.org/wiki/ECMAScript_syntax'>Wikipedia article
* teaching ECMAScript syntax</a></li>
* <li><a href=' http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf'>ECMAScript language specification</a></li>
* <li>The Lob class documentation, in which all public slots are script-callable
* and all properties are script-accessible</li>
* <li>The lobscript.h file, which customizes the ECMAScript environment to Lurch's
* needs (see addLobsToScriptEngine() especially)</li>
* <li>The <a href="scripting.html"><code>simple_script</code></a> tool is documented in
* utils/simple_script/main.cpp, and is a handy command-line tool for Lurch script
* experimentation</li>
* <li>In <a href='http://lurch.svn.sourceforge.net/viewvc/lurch/Lurch/trunk/utils/simple_script/jsutils'>the
* <code>utils/simple_script/jsutils</code> directory</a> and in the
* <a href='http://lurch.svn.sourceforge.net/viewvc/lurch/Lurch/trunk/tests/script_tests/'
* ><code>tests/script_tests</code> directory</a> you can find examples of
* working scripts.</li>
* </ul>
*/
/** \page attrs Special Treatment of Attributes
*
* Lurch uses several conventions about how the OpenMath objects it deals with will be
* attributed. These conventions allow Lurch to not have its own proprietary data format,
* but to use OpenMath exclusively, and simply add attributes to objects to keep data in
* them according to the following conventions.
*
* It is therefore important for us to document these conventions, since they are just
* conventions. We can use this as a specification for how to
* build our software, and against which we can compare it for testing.
* The content dictionary for each of these attributes is <code>LurchCore</code>.
*
* <ul>
* <li>The attribute <code>ID</code> of any Lurch Object is for storing that object's
* unique (across the current document) identifier.
* Read more in the definition of Lob::getID().</li>
* <li>The attribute <code>nickname</code> is for storing a Lurch Object's optional
* nickname, an alias for its unique identifier. This alias can be used to refer to
* the object from outside the immediate document.
* Read more in the definition of Lob::getNickname().</li>
* <li>The attribute <code>language</code> is for storing the language in which a
* Lurch Function is written. Languages we intend to implement early on are
* "Python" and "ECMAScript"; the value of this attribute should be exactly equal to
* one of those two strings (case sensitive). This is a required attribute of
* Lurch Functions. Read more in the definitions of Lob::functionLanguage() and
* Lob::isFunction().</li>
* <li>The attribute <code>reference</code> is for flagging a Lurch Object as a
* Lurch Reference, and specifying which kind of reference it is, either
* "ID" or "nickname". Read more in the definitions of
* Lob::getIDReference(), Lob::isIDReference(),
* Lob::isNicknameReference(),and Lob::getNicknameReference().</li>
* <li>The attribute <code>author</code> is for specifying the author of a Lurch Document.
* It is a required attribute of Lurch Documents.
* Read more in the definitions of Lob::getAuthor() and Lob::isDocument().</li>
* <li>The attribute <code>title</code> is for specifying the title of a Lurch Document.
* It is a required attribute of Lurch Documents.
* Read more in the definitions of Lob::getTitle() and Lob::isDocument().</li>
* <li>The attribute <code>dependencies</code> is for specifying the other
* documents on which a Lurch Document depends; it is a list whose entries must
* fit the format of Lurch URNs.
* It is a required attribute of Lurch Documents, though it may be empty.
* Read more in the definitions of Lob::getDependencies() and Lob::isDocument().</li>
* <li>The attribute <code>helpURN</code> is for specifying that the Lurch document whose URN
* (as an OpenMath string) is the value of the attribute is a help document about the
* document that has the attribute with that key.
* I.e., if X.attribute( helpURN ) == Y, then Y is a help document about X.</li>
* <li>The attribute <code>topic</code>, if present in a document, will have an OpenMath string
* as its key, indicating that the document is a topic (in that it should show up on the
* list of Lurch math topics for a user to choose), and the string is its name/title.</li>
* <li>The attribute <code>topic_description</code> should only appear if <code>topic</code>
* appears. It is also a string containing a one- or two-sentence description of the
* topic that can be used in the user interface when the user is browsing topics.</li>
* <li>The attributes <code>mode</code> and <code>mode_description</code> function analogously
* to <code>topic</code> and <code>topic_description</code>, except for modes rather than
* topics.</li>
* <li>The attribute <code>CSSCode</code> is respected by the Lurch application. It is a
* string attribute whose value can contain cascading style sheets code that will apply to
* the document and any document that depends on it, when rendered as HTML.</li>
* </ul>
*/
/** \page opps Development Opportunities
*
* This page has been superceded by
* <a href='https://sourceforge.net/apps/trac/lurch/wiki/SomethingToWorkOn'>a wiki page
* listing accessible projects</a>, as well as the general
* <a href='https://sourceforge.net/apps/trac/lurch/wiki/DeveloperCenter'>Developer Center
* page on the wiki</a>.
*/
/** \page openmath Things to know about INRIA's OpenMath C++ Library
*
* I include the documentation for this library
* <a href='http://lurch.sourceforge.net/omcppdoc'>on our web space</a>, and also include
* <a href='http://lurch.sourceforge.net/omcppdoc/README.html'>the helpful README file</a>.
* However, <b>I have also modified the library slightly</b>, and details of my changes
* are described in their own section, below.
*
* Here are a few things I've learned about this library from using it.
*
* <b>Using the classes</b>
* <ol>
* <li>Although the OpenMath Standard (v2.0, Section 3.1.2) specifies Reference objects,
* this library does not seem to support them. The text OMR appears nowhere in the
* source code, and from this I conclude that <OMR> tags are not supported.</li>
* <li>No destructors in any class inheriting OmNode are public, except for OmDocument.
* This causes problems, which I seek to remedy with the deleteOmNode() function.
* See its documentation for full details.</li>
* <li>Here's a handy reference for OmNode types, when debugging.
* <table>
* <tr><th>Type</th><th># value</th>
* <th>Type</th><th># value</th></tr>
* <tr><th>OmIntegerType</th><th>1</th>
* <th>OmBigIntegerType</th><th>2</th></tr>
* <tr><th>OmFloatType</th><th>3</th>
* <th>OmByteArrayType</th><th>4</th></tr>
* <tr><th>OmVariableType</th><th>5</th>
* <th>OmStringType</th><th>6</th></tr>
* <tr><th>OmWStringType</th><th>7</th>
* <th>OmSymbolType</th><th>8</th></tr>
* <tr><th>OmPInstructionType</th><th>14</th>
* <th>OmCommentType</th><th>15</th></tr>
* <tr><th>OmApplicationType</th><th>16</th>
* <th>OmEndApplicationType</th><th>17</th></tr>
* <tr><th>OmAttributeType</th><th>18</th>
* <th>OmEndAttributeType</th><th>19</th></tr>
* <tr><th>OmAttributeParameterType</th><th>20</th>
* <th>OmEndAttributeParameterType</th><th>21</th></tr>
* <tr><th>OmErrorType</th><th>22</th>
* <th>OmEndErrorType</th><th>23</th></tr>
* <tr><th>OmObjectType</th><th>24</th>
* <th>OmEndObjectType</th><th>25</th></tr>
* <tr><th>OmBindingType</th><th>26</th>
* <th>OmEndBindingType</th><th>27</th></tr>
* <tr><th>OmBindingVariableType</th><th>28</th>
* <th>OmEndBindingVariableType</th><th>29</th></tr>
* <tr><th>OmUnknownType</th><th>0</th></tr>
* </table>
* </li>
* <li>It is natural to ask how to interpret an OmBigIntegerNode object whose digit array
* is invalid, or nonstandard. I adopt the following conventions.
* <ol>
* <li>Prefixing with zeros is okay, and they should be ignored ("003" is "3").</li>
* <li>Having whitespace is okay, and it should be ignored (" 52 " is "52").</li>
* <li>Empty strings are interpreted as zero ("000" is "0" is "").</li>
* <li>Invalid digit sequences, such as "512.8" or "100ABC" or "3 3 3", are not of
* concern to me when writing routines. I assume the digit sequences are valid,
* modulo the quirks just mentioned. If you pass in invalid parameters like
* that, the results are undefined; garbage in, garbage out.</li>
* </ol></li>
* <li>Reading OpenMath nodes from an input device (string, file, etc.) seems to always
* wrap them in a node of unknown type. That is, if you
* read from the string <code>"<OMI>42</OMI>"</code>, you will get a tree
* of the form <code>Unknown(Integer 42)</code>, as opposed to just a one-node tree.
* This is sensible, since you could ask it to read from a string like
* <code>"<OMI>42</OMI><OMI>5</OMI>"</code>, and it would
* need a wrapper node to return the two together as its children.
* Always creating one is just consistency.</li>
* </ol>
*
* <b>Items specific to Qt</b>
* <ol>
* <li>It is not obvious how to get the standard Qt types such as QIODevice and QFile to
* work with the OpenMath versions like OmInputDevice. Example code for reading and
* writing a document to/from a file is a good place to look to see how to get this
* working; check out the code for the method test_omlib::test_file_read_write().</li>
* </ol>
*
* <b>My modifications to the INRIA sources</b>
* <ol>
* <li>I modified the OmNode class in OmNode.h so that each OmNode object has a pointer to
* its owner, or null if there is none. It follows the following principles.
* <ol>
* <li>A child node's parent is its owner.
* A symbol node used as a key in an attribution is owned by the modified node.
* The associated value for that key has the same owner as the key.</li>
* <li>Newly created nodes have owner equal to NULL.</li>
* <li>Clones do not copy the owner; they have owner set to null.
* But their children (and their children, and so on) have owner set to
* make the newly cloned tree correctly connected.</li>
* <li>When a node is adopted, via OmNode::append(), OmNode::insert(),
* OmNode::appendAttribute(), etc., its owner is set to be the node into
* whose list of children/attributes it was placed. For attributes, this
* holds for both the key and value nodes.</li>
* <li>When a node is unadopted, using OmNode::extract() or
* OmNode::extractAttribute(), its owner is set to NULL.
* For attributes, this holds for both the key and value nodes.</li>
* <li>When a node is deleted using OmNode::kill() or OmNode::killAttribute(), its
* owner field is not modified, because it's about to be deleted anyway, so that
* data is irrelevant.</li>
* <li>Comments do not have owner, because they do not descend from OmNode.</li>
* </ol>
* </li>
* <li>It was only necessary to modify the OmNode class, because final nodes do not have
* children, and non-final nodes such as OmApplicationNode and OmBindingNode use the
* OmNode::append() method, which sets parenting as documented above.</li>
* <li>While modifying the OmNode class to have an owner field, I also added two fields to
* tell <i>how</i> the node was owned. An ownership type field
* (of C++ type OmNode::OwnershipType) marks the node as owned
* as a child (AsChild), as an attribute key (AsKey), as an attribute value (AsValue),
* or not owned (None, when owner is NULL). An owner index field (unsigned int)
* records the index in the owner's child array or attribute array where the node lies.
* This makes it easy to compute the address of a node in a tree, using the LobAddress
* class.</li>
* <li>I added a routine OMIOStringLength to OMdevString.c in the C library,
* because formerly the only way to access the length of the string was through
* a data member unfortunately named "private." (Not the keyword private, but a
* variable name "private"!) Of course this is okay in C, but not in C++. Since we're
* using C++, the compiler won't let you access such variables.<br>
* Thus I wrote a C
* function to do it for us. This is accessible by a method I added to
* OmOutputStringStream, <code>int getBufferLength()</code>, to go along with the
* <code>char* getBuffer() const</code>.<br>
* Unfortunately due to limitations in the implementation of the OpenMath library
* (a mix of C and C++) I could not declare this method as const; it is one of many
* things that makes me think a good, Qt-based, C++-only OpenMath library is needed.
* </li>
* <li>I modified <code>OmNode::consultAttribute()</code> so that it does not return a
* value and is <code>const</code>. It formerly returned the <code>this</code>
* pointer, so it could not be <code>const</code>, but I saw little value to that, and
* much more value to it being a <code>const</code> method.</li>
* <li>I modified OmNode.h so that Iterator and ConstIterator have no virtual functions.
* (I just removed the virtual keyword.) This cuts down on compiler warnings;
* there was no purpose for them being there in the first place.</li>
* <li>I modified OmFinalNode.h so that its unused parameters are commented out,
* again reducing compiler warnings.</li>
* <li>The INRIA OpenMath C library uses UTF7 for encoding OMSTR nodes, which is not at all
* standard. The OpenMath Standard v2.0 specifies "unicode," but not which encoding;
* UTF7 is not even a standard encoding, and was designed for email, not XML documents.
* I disabled UTF7 encoding in the following ways.
* <ol>
* <li>In the file OMutf7.c, which sets SHIFT_IN and
* SHIFT_OUT to be the characters + and - respectively,
* I changed them to the ASCII shift in and out (15 and 14, respectively).
* We'll be writing scripts with +'s and -'s in them, and won't want to be
* escaping them all the time with UTF7 encodings
* (which are hard to figure out).</li>
* <li>I edited OMencXml.c to use the WRITE macro rather than the OMputCharAsUTF7
* function in the OMSEputString() function.
* (But I did not make any changes to the OMSEputWCString() function,
* because we're not using wide strings in Lurch (yet) anyway.)</li>
* </ol>
* </li>
* <li>I modified OmOutputDevice.h, OmStringNode.h, and OMencXml.c to lift the restriction
* that OpenMath string nodes not ever be the empty string. This is not mentioned
* anywhere in the OpenMath Standard v2.0, and seems like an unreasonable restriction
* to us.</li>
* <li>I modified OMSEparseQuotedString() in OMencXml.c to check if it passes the end
* of the device/buffer. This was a serious bug that would cause XML code like the
* following to simply hang the program!
* <code><OMV name="x/></code>
* Now it returns OMmalformedInput error instead, as appropriate.
* </li>
* </ol>
*/
/** \page unittest How to develop with unit testing
*
* I'm in the process of learning what it is to do unit testing for the first time in my
* career, and I have to say that it is (as I suspected) exremely beneficial. I'm starting
* to get a streamlined development-and-testing process going, and wanted to document it.
* There are surely better procedures out there, but this simple one works for me.
* See an example of its results in classes like test_lob and test_omlib.
*
* This assumes you are familiar with the Qt Unit
* Testing framework, as documented on their web site (or in Qt Assistant).
* In addition to using Qt Unit Testing framework to test our C++ code, we also have the
* doctest utility for testing our Lurch script code as well (both libraries and packages);
* see its documentation in utils/doctest/main.cpp.
*
* <ol>
* <li>Create the interface file (.h) for the program elements you intend to test.
* They are proably routines in a class. Document them in-source, Doxygen-style,
* describing exactly what they must accomplish.</li>
* <li>Create the corresponding code (.cpp) file as stubs without implementation
* (i.e., routines like the following).
* \code
* int SomeClass::someFunction ( double b )
* {
* return 0; // just to keep compiler happy; routine not yet implemented
* }
* \endcode
* </li>
* <li>Run the <code>create_tests</code> script with parameter the class name you're
* working on (or the filename if it's not a class). Ensure the test compiles
* and runs without errors.</li>
* <li>Iterate the following steps to change all such stubs into implemented, tested
* routines.
* <ol>
* <li>Implement some subset of the stubs, following the specifications you wrote in
* the in-source comments. Choose as small a subset as possible, preferably of
* related things that do not depend on anything not yet built/tested.</li>
* <li>Change the name of the <code>test_1()</code> routine in your newly created test
* class to describe what you're testing, like <code>test_file_handling()</code>.
* Change the body of the test routine to a one-line debugging statement like this.
* <pre>
* qDebug() << "WARNING: THIS ROUTINE NOT YET COMPLETE!";
* </pre>
* (For the next test, obviously do not <i>change</i> the original test routine,
* but create a new one.)</li>
* <li>The promises made in the specification you wrote for your toutines (which you
* just did your best to implement) guides what tests need to be run. Document
* the (still unwritten) test routine by by enumerating all the promises you made
* in your specfication and explaining how to test each one.</li>
* <li>Begin implementing tests according to the documentation you just wrote, one
* after the other in the test routine, using macros like <code>QCOMPARE</code>,
* as documented in the Qt documentation.</li>
* <li>Often use the <code>run_test.sh</code> script in the same directory to build and
* run your tests. Debug both your test routine and the routine(s) it tests
* until all the tests you described have been implemented and they pass
* when run.</li>
* <li>Remove the debugging statement which claimed that the testing routine was
* incomplete; it is now complete.</li>
* </ol>
* </li>
* </ol>
*
* Commit your work to the SVN repository at every sensible stopping point.
*
* Commit work often, for several reasons. You might later
* wish you could rewind only part of a large change, or some other developer may find some
* flaw in the giant commit you just did that invalidates much of it, and makes you wish you
* had submitted smaller bits of testable code for your codevelopers to scrutinize.
*
* Do not commit work <i>too</i> often, for other reasons.
* You do not want the SVN repository filled up with miniscule changes that are consequently
* difficult to describe comprehensibly, and you do not want to commit code that is in an
* unstable or uncompilable intermediate state.
*/
/** \page docconv Conventions in the Lurch Documentation
*
* <ol>
* <li><b>Conventions regarding C++ unit testing</b>
* fall into the following three categories.
* The first file whose classes and functions were tested and documented is lob.h
* (including the class Lob and some non-member functions). Refer to
* that file and class for examples of each of the following conventions.
* <ol>
* <li>Each <code>.h</code> header file will link to the documentation for its
* testing unit class, and vice versa.</li>
*
* <li>Each routine declared in such a file (be it a member function or
* a non-member function) will link to the specific routine in the test class
* that tests its functionality.</li>
*
* <li>When a <code>.h</code> header file has had tests written for all its
* contents (classes, member functions, non-member functions), then a note will
* be placed in the documentation at the top of that file so indicating.</li>
* </ol>
*
* The purpose of this is so that
* anyone interested in finding the tests for a particular function can just look
* in the documentation for its <code>.h</code> file and follow the link.
* (It would be cleaner to link from the class being tested to the class doing the
* testing, but this leaves non-member functions orphaned by this process.)
*
* The handy <code>create_tests</code> script
* in the <code>tests/</code> directory makes it easy to follow this convention
* when writing new unit tests.
* It generates unit test template files that automatically link back to the
* <code>.h</code> file they test, and it reminds you to automatically add the
* reverse link according to the convention.
*
* Note that there is also a page on \link unittest how to do unit testing\endlink.
* </li>
* <li><b>Conventions regarding script unit testing</b> are as follows.
* The <code>trunk/tests/</code> folder contains a <code>script_tests/</code>
* subfolder with many <code>.js</code> files in it. Each is interpreted as a
* script test, and it is assumed that they are to be run using a command like this.
* <pre>
* ../../utils/simple_script/simple_script --batch < filename.js
* </pre>
* Most of these use the <a href='http://labs.trolltech.com/blogs/2007/11/05/unit-testing-with-qt-script/'>QSTestLib framework by Kent Hansen</a>,
* and those that don't will probably soon be converted to use that format.
* It enables test authoring in a manner that looks similar to the C++ unit testing
* framework that comes with Qt, and it gives similarly-formatted output, which
* makes it easy for <a href='http://lurch.svn.sourceforge.net/viewvc/lurch/Lurch/trunk/utils'>testlurch</a>
* to process all the output the same.
* </li>
* </ol>
*/
/** \page scripting Lurch Scripting with simple_script
Developers and advanced users who would like to access Lurch
functionality via a scripting language can do so through the
<code>simple_script</code> command line utility. This page
provides some simple instructions about Lurch scripting via
that program.
<h3>Note that there is
<a href='https://sourceforge.net/apps/trac/lurch/wiki/LurchScripting'>a
more recent scripting introduction in our wiki</a>, which covers scripting in Lurch.
You should check to see which tutorial better suits your needs.
This tutorial covers <code>simple_script</code>, which is a command-line tool.</h3>
<h3>The <code>simple_script</code> Utilitity</h3>
The <code>simple_script</code> program can be obtained from the Lurch
svn repository in the
<a href='http://lurch.svn.sourceforge.net/viewvc/lurch/Lurch/trunk/utils/simple_script/'>
<code>/utils/simple_script/</code></a> folder. The <a
href='http://lurch.svn.sourceforge.net/viewvc/lurch/Lurch/trunk/utils'>
<code>testlurch</code> shell script</a> can be used to download and
install the entire Lurch system and related utilties. After running
<code>testlurch</code> the simple_script program will be in your local
<code>Lurch/trunk/utils/simple_script</code> folder.
<h4>Command line options for simple_script.</h4>
The syntax for invoking the utility is fairly simple. It can either be run interactively
or in batch mode. In batch mode a file containing the script source code is read from the
standard input stream and processed the script after an EOF character is reached,
returning any output on the standard output stream.
Errors are sent to stderr. In interactive mode it provides the user with a prompt and evaluates
the user's input and displays the result. It also takes several optional command line
arguments.
<table>
<tr>
<th style="text-align: center;" colspan="2" rowspan="1">Command line
arguments for simple_script</th>
</tr>
<tr>
<td><code>-I<em>filename</em></code></td>
<td>includes the script file named <code><em>filename</em></code> at the top
of the script file</td>
</tr>
<tr>
<td><code>-P<em>packagename</em></code></td>
<td>loads the Lurch package <code><em>packagename</em></code></td>
</tr>
<tr>
<td><code>-D<em>var</em>=<em>value</em></code></td>
<td>defines the value of the javascript variable <code><em>var</em></code> to the
javascript value <code><em>value</em></code> before
executing the script. This is useful for passing command line arguments
to the script itself.</td>
</tr>
<tr>
<td><code>--batch</code></td>
<td>run the program in batch mode (i.e. no interactive user prompt)</td>
</tr>
<tr>
<td><code>--debug</code></td>
<td>print verbose debugging information</td>
</tr>
</table>
<B>Examples</B><br>
<ul>
<li>Run simple_script interactively. Enter javascript commands at the prompts, press enter,
and see the results. Type <code>quit</code> or <code>exit</code> to exit the program.<br>
<br>
<code>simple_script</code><br>
<br>
</li>
<li>Read input from stdin, and print output on stdout.
Enter this command, type your script, press EOF (ctrl-D), and
watch the output.<br>
<br>
<code>simple_script --batch</code><br>
<br>
</li>
<li>Run the script whose source code is stored in the file <code>myscript.js</code><br>
<br>
<code>simple_script --batch < myscript.js</code><br>
<br>
</li>
<li>Run the script whose source code is stored in the file <code>myscript.js</code>
and show extra debugging information.<br>
<br>
<code>simple_script --batch --debug < myscript.js</code><br>
<br>
</li>
<li>Set the javascript variables <code>quiet=true</code>
and <code>n=7</code>
before executing the script <code>myscript.js</code><br>
<br>
<code>simple_script --batch -Dquiet=true -Dn=7 < myscript.js</code><br>
<br>
</li>
<li>Prepend the file <code>lurchutils.js </code>to
the script <code>myscript.js</code> and
then execute the whole thing<br>
<br>
<code>simple_script --batch -Ilurchutils.js < myscript.js</code><br>
<br>
</li>
<li>Set <code>quiet=false</code> first, then
include the file <code>lurchutils.js</code> before reading and
executing the script <code>myscript.js</code>
<br>
<br>
<code>simple_script --batch -Ilurchutils.js -Dquiet-false < myscript.js</code>
<br>
<br>
</li>
<li>Load the <code>Classify</code> package, set <code>quiet=false</code>, then
include the file <code>lurchutils.js</code> before reading and
executing the script <code>myscript.js</code>
<br>
<br>
<code>simple_script --batch -Ilurchutils.js -Dquiet-false -PClassify <myscript.js</code>
<br>
<br>
</li>
</ul>
<h3>Lurch Scripting</h3>
Currently the only scripting language supported is <em>QtScript</em>,
which is closely related to the <em>javascript</em> scripting language.
<em>QtScript</em> is based on the ECMAScript standard, as is
<em>javascript</em>. Most of the <a
href="http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide">
standard syntax and features of the <em>javascript</em> language</a> are
available for use in QtScript. There is a nice <a
href="http://www.w3schools.com/JS/default.asp">javascript tutorial</a>.
available online. Note that most javascript tutorials assume that you
are writing javascripts for inclusion in a web page, and include a lot
of information about HTML, browser windows, alert dialogs, and so on, that is not
relevant to Lurch scripting.
In addition to normal javascript syntax, a Lurch script can currently
access any of the <B>Public Slots</B> and <B>Properties</B> of the main
Lurch classes, such as the <code>Lob</code> class. It can also load any LurchPackage.
Examples of lurch scripts can be found in the <a
href="http://lurch.svn.sourceforge.net/viewvc/lurch/Lurch/trunk/tests/script_tests/">
<code>/tests/script_tests</code></a>and <a
href="http://lurch.svn.sourceforge.net/viewvc/lurch/Lurch/trunk/utils/simple_script/jsutils/">
<code>/utils/simple_script/jsutils/</code></a>folders in the Lurch svn.<br>
<h4>Sample sessions</h4>
Here are two sample sessions illustrating the difference between running simple_script in
batch mode vs interactive mode.
<ol>
<li>You can run it in batch mode with the <code>--batch</code> parameter,
pass a script to stdin (with an optional <code>--debug</code> flag for verbose
output about debugging progress).
<pre>
* $ ./simple_script --batch --debug < example.script
* *** Activated debugging messages in response to --debug flag.
* *** Loaded this script:
*
* myLob = Lob( '<OMI>3</OMI>' );
* print( myLob.toQString() );
* myLob.numChildren();
*
* *** Processing line 2 col 1: myLob = Lob( '<OMI>3</OMI>' );
* *** Processing line 3 col 1: print( myLob.toQString() );
* <OMI>3</OMI>
*
* *** Processing line 4 col 1: myLob.numChildren();
</pre>
The same script run without the debug flag would simply do this.
<pre>
* $ ./simple_script --batch < example.script
* <OMI>3</OMI>
</pre></li>
<li>You can run it in interactive mode by not passing the <code>--batch</code> paramter,
and interact with it in a read-evaluate-print loop, like most interpreters.
<pre>
* $ ./simple_script
* > 2+2
* 4
* > Fred
* ReferenceError: Fred is not defined
* > quit
</pre></li>
</ol>
<h4>Additional features and illustrations</h4>
<ol>
<li>You can include other scripts into the script passed into stdin
(and so on recursively). The way to do this is to use the added global function
<code>include</code> with one string parameter, the filename. Files are searched
for either by absolute path (if given) or from the working directory (if given
relatively).
<pre>
* include( "myutils.js" );
*
* functionFromMyUtils();
</pre>
</li>
<li>You can request includes from the command line as well. These are added before any
includes in the file, in the order they are found on the command line.
Example: <code>./simple_script -Imyfavorite.js -Imysecondfavorite.js</code>.</li>
<li>You can define variables in the script with command line arguments, somewhat like
preprocessor defines in C/C++. A command line argument
<code>-Dvariable=value</code> will define the variable <code>variable</code>
in the script's global environment to have the value <code>value</code>, which
can be any ECMAScript expression that can be evaluated before any input has been
read. Here is an example (the ^D means you press Ctrl-D to indicate end of stdin).
<pre>
* $ ./simple_script -Dtemp=1000
* print( temp );
* ^D
* 1000
* $
</pre>
</li>
<li>Because the interpreter used is one situated inside a LurchEnvironment,
you have access to its document() and dependencies() arrays.</li>
<li>You can ask that environment to load packages by including in your script anywhere
a line that begins with USEPACKAGE and is followed by the beginning of the package
name, like this.
<pre>
* // here's where my script starts.
* // let's include the Classify Package
* USEPACKAGE Classify
* // now I can make calls like this,
* // using stuff defined in that package:
* var myClass = new Class( ... );
</pre>
Note the following details about importing packages.
<ul>
<li>All packages are loaded before any script code is executed.
They are <i>not</i> loaded at the point in code where they are written.
Thus it is best to simply write them at the top of the file for clarity.</li>
<li>USEPACKAGE is only respected in the input file, not in any files include()d
by it.</li>
<li>It is only necessary to specify enough of the package name to uniquely
identify it; Class might have been enough in the above example.</li>
<li>No package will be loaded more than once, no matter how many times it is
specified, nor even if other packages' dependencies introduce the
redundancy.</li>
<li>This feature is not supported by the interactive interpreter, in the sense
that you cannot type USEPACKAGE in the interactive interpreter and expect it
to retroactively load one. However, you can use the -P flag, as described
below, even in non-batch mode.</li>
</ul>
</li>
<li>You can load packages from the command line as well.
Example: <code>./simple_script -PClassify "-PLob Utilities"</code>.</li>
</ol>
*/
/** \page installation Lurch Installation Guide (Linux, Mac, Unix)
The most recent development version of Lurch can be installed on your
local system using the
<a href='http://lurch.svn.sourceforge.net/viewvc/lurch/Lurch/trunk/utils/'>
the <code>testlurch</code> bash script</a>.
<p><strong>Ordinary users should just install with the binaries provided on the
SourceForge download site (or the intallation script for Linux).
This is only for developers.</strong></p>
<h2>Installing <code>svn</code>, <code>doxygen</code>, and
<code>testlurch</code></h2>
The following programs must be installed first in order to install Lurch by this
method. You can use the command
<pre> which <em>cmd</em></pre>
to see if a command named <code><em>cmd</em></code> is installed and in
your execution path, or one of the suggested commands below to check
version information.
<ol>
<li><em>Subversion</em>: Download and install the
<a href="http://subversion.tigris.org/"><em>subversion</em></a> command
line program for your operating system. Note that you only need the
<code>svn</code> command for <code>testlurch</code> to work. To test your
installation, at a command prompt you can try the command:
<pre> svn --version</pre>
to see if the program is installed and in your execution path.
</li>
<li><em>Qt 4.5</em>: Download and install
<a href="http://trolltech.com/downloads">Qt 4.5</a> for your operating system.
To test your installation, at a command prompt you can try the command:
<pre> qmake --version</pre>
to see if the program is installed and in your execution path. If you
do not already have a <code>g++</code> command installed you will need to
install <a href="http://gcc.gnu.org/"> a C++ compiler as well.</a>
</li>
<li><em>Doxygen</em>: Download and install
<a href="http://www.stack.nl/~dimitri/doxygen/">
Doxygen</a> for your operating system. [Note: this is only required if
you would like to have a local copy of the most recent Lurch documentation
installed.] To test your installation, at a command prompt you can try the
command:
<pre> doxygen --version</pre>
to see if the program is installed and in your execution path.
</li>
<li>Download the <code>testlurch</code> script, and put it somewhere in your
execution path (and set the file permissions to allow it to be
executed if necessary). To test your installation you can try the
command:
<pre> testlurch -v</pre>
which should print the current version of the testlurch script.
</li>
</ol>
<h2>Installing Lurch with testlurch</h2>
<h3>Default installation</h3>
The only thing you need to decide is what folder you want to install Lurch into.
That folder is called <em>lurchbase</em>. The default <em>lurchbase</em> folder
is the user's home folder. If you are happy with that choice, simply issue the
command:
<pre>
testlurch</pre>
and the script should download, compile, test, and create documentation for
Lurch. During a normal installation, <code>testlurch</code> will print an
enormous quantity of compiler warning messages and test reports. To suppress
most of these and obtain a more human-readable output use the command
<pre>
testlurch -q</pre>
instead.
At this time, the only way to use Lurch is via the
<a href="scripting.html">simple_script utility</a> or the <code>LurchJr</code> or
<code>LurchAlph</code> programs found
in the <code>Lurch/trunk/utils</code> subfolder of the Lurch installation folder.
<h3>Advanced <code>testlurch</code> options and use</h3>
1. <b><em>Changing the default installation folder</em></b>
To install lurch into an folder other than your home folder, you can specify the
installation folder in one of two ways. First, you can set the environment
variable <code>lurchbase</code> to the complete path of the folder where you
want Lurch to be installed. Second, you can specify the <em>lurchbase</em>
folder as an argument to <code>testlurch</code> using the
<code>-l<foldername></code> option, where <code><foldername></code> is
replaced by the full path of the desired folder. For example, to install
Lurch to <code>/home/monks/files/monkware/</code> you could call testlurch
as follows:
<code>testlurch -l/home/monks/files/monkware/</code>
Note: be certain to include the final <code>/</code> character in the path.
2. <b><em>Other command line options to testlurch</em></b>
The <code>testlurch</code> script also supports the following command line
arguments.
<table>
<tr>
<th style="text-align: center;" colspan="2" rowspan="1">Command line
arguments for testlurch</th>
</tr>
<tr>
<td><code>-l<em>folderpath</em></code></td>
<td>specifies that Lurch be installed to the <em>folderpath</em>
directory (see explanation of <em>lurchbase</em> above).</td>
</tr>
<tr>
<td><code>-v</code></td>
<td>display the version number of this testlurch script</td>
</tr>
<tr>
<td><code>-s</code></td>
<td>download the latest code from svn</td>
</tr>
<tr>
<td><code>-c</code></td>
<td>run "make clean" on all util and test folders</td>
</tr>
<tr>
<td><code>-t</code></td>
<td>run all tests to ensure the program is working properly</td>
</tr>
<tr>
<td><code>-d</code></td>
<td>run doxygen to build the documentation</td>
</tr>
<tr>
<td><code>-q</code></td>
<td>turn on <em>quiet</em> mode. Suppresses all but essential output.</td>
</tr>
</table>
These command line options shown in the table can be used together in any
combination.
3. <b><em>Examples</em></b>
Here are some common uses of testlurch.
<ul>
<li>Download the latest source code, recompile it clean, test everything,
rebuild the documentation, and report the results succinctly:
<code>testlurch -q</code><br>
</li>
<li>Same as the previous command, but don't clean the folders first to
save a lot of time:
<code>testlurch -s -r -t -d -q</code><br>
</li>
<li>Just run the test battery and report the detailed results:
<code>testlurch -t</code><br>
</li>
<li>Just download the source code from svn:<br>
<code>testlurch -s</code><br>
</li>
<li>Just quietly rebuild the documentation:<br>
<code>testlurch -d -q</code><br>
</li>
</ul>
*/
/** \page uiprotocol Protocol for Document-UI Communication
*
* <h2>Requirements</h2>
*
* <p>What problem does this protocol try to solve? It is a three-part problem.</p>
* <ol>
* <li>A Lurch document (itself or via one of its imported libs or packages)
* needs to be able to answer questions from the UI about the user's actions.<br>
* For example, the when the user double-clicks a Lob, the UI may ask the document
* how it would like that action handled. Or when the user right-clicks a Lob,
* the UI may ask the document what items should populate the context menu.</li>
* <li>It may also need to be able to obey commands from the UI, asking the document
* to perform specific actions in whatever way the document defines.</li>
* <li>The document may also need to make requests of the UI.<br>
* Examples include these kind of requests:<br>
* <b>"Please inform the user that [message]."</b>
* (currently accomlished by <code>alert( "..." );</code>)<br>
* <b>"Please ask the user [question] (yes/no)."</b>
* (currently accomlished by <code>askYN( "..." );</code>)<br>
* <b>"Please have the user input [description of a value]."</b>
* (currently possible, but the code for doing so depends on
* what you want to ask the user)</li>
* </ol>
* <p>In all three of these cases, sensible defaults should apply.
* This is so that documents that ignore their responsibilities to answer questions
* (as in 1.) and obey actions (as in 2.) behave as the document author expects,
* and so that user interfaces that do not pay attention to or are not able to follow
* instructions (as in 3.) still do something sensible. Here are some sensible defaults.</p>
* <ol>
* <li>All questions default to a no/empty answer.</li>
* <li>All commands (from UI to document or document to UI) default to doing nothing
* and returning the "undefined" Javascript value.</li>
* </ol>
* <p>This way documents/libraries/topics invented before a feature was added to Lurch
* continue to function correctly without modification, but do not have access to the new
* features.</p>
*
* <h2>Implementation</h2>
*
* <h3>To handle UI-to-document communication (parts 1. and 2. of requirements):</h3>
*
* <p>Documents may import the UserInterfacePackage that makes it easy to respond to UI
* questions/commands. Thereafter, the document can modify the contents of the global
* <code>uiFeatures</code> object defined in that package to add new handlers for various
* requests the UI may make of the document. Some simple example uses of the package appear
* below; see the documentation for that package for more information/specifics.</p>
* <p>Enabling a feature:</p>
* <pre>uiFeatures.addFeature( 'name of feature' );</pre>
* <p>Making a feature sometimes enabled and sometimes disabled:</p>
* <pre>
* uiFeatures.addFeature( 'name of feature',
* function () {
* // code goes here to decide if the feature is usable
* return true; // or false, as you decide
* },
* function () {
* // code goes here to do the action, if you approved it above.
* } );</pre>
* The addFeature() function takes four arguments,
* <a href='http://sourceforge.net/apps/trac/lurch/browser/Lurch/trunk/packages/uifeaturespackage.js#L35'>described in the comments in its source code</a>.</p>
* <p>Answering a question with a non-boolean value:</p>
* <pre>
* uiFeatures.addFeature( 'contextMenu',
* function ( clickedOnThisLob ) {
* // I'm only adding menu items for Foo Lobs
* return isAFoo( clickedOnThisLob );
* },
* function ( clickedOnThisLob, entriesSoFar ) {
* if ( !( entriesSoFar instanceof Array ) )
* entriesSoFar = [];
* // It's guaranteed to be a Foo Lob here, so this item applies:
* entriesSoFar.push( 'Bar this foo' );
* entriesSoFar.push( function () {
* barThisLikeAFoo( clickedOnThisLob );
* } );
* return soFar;
* } );</pre>
* <p>See the lists of specific features below for documentation about the parameters
* to these functions.</p>
* <p>Note that you can call addFeature() several times with the same first parameter
* and different other parameters; a stack of handlers is created, later handlers given
* higher priority than earlier ones. (You can change this behavior with an optional
* parameter--see the JavaScript code documentation linked to above.)</p>
*
* <h3>To handle document-to-UI communication (part 3. of requirements):</h3>
*
* <p>There is a script function defined in every LurchEnvironment called
* <code>uiCommand()</code>which simply passes on all its arguments to whatever
* UI surrounds the LurchEnvironment, if any, using a signal emitted
* by the LurchEnvironment, to which the UI is free to listen.
* LurchEnvironments also define the <code>UI</code> object, which has in it members which
* are more convenient to use than the <code>uiCommand()</code> function, because they look
* like acutal functions; see the examples below.</p>
* <pre>
* // calling exampleFunction(1,2,3) using uiCommand():
* uiCommand( "exampleFunction", 1, 2, 3 );
* // calling exampleFunction(1,2,3) using the UI object:
* UI.exampleFunction( 1, 2, 3 );
* </pre>
* <p>UIs who do not implement a response (or whose implementation does not know
* about the command that was send), such as a command-line UI being asked to hide
* a toolbar) will just do nothing and return an undefined value.</p>
*
* <h2>User Interface functions available to documents</h2>
*
* <p>Each of these functions already exists in the current version of Lurch.
* In each case, rather than document the function, I include a link to the existing
* documentation in the Doxygen documentation for the C++ function that implements the
* script function.</p>
*
* <ul>
* <li><b>UI.alert( ... )</b> or <b>uiCommand( 'alert', ... )</b><br>
* See CommonGUIExtension::script_alert().</li>
* <li><b>UI.print( ... )</b> or <b>uiCommand( 'print', ... )</b><br>
* See CommonGUIExtension::script_print() and
* LurchGUIExtension::script_print().</li>
* <li><b>UI.trace( 'function expression', 'explanation' )</b>
* or <b>uiCommand( 'trace', 'function expression', 'explanation' )</b><br>
* See CommonGUIExtension::script_trace().</li>
* <li><b>UI.ask( prompt[, default] )</b> or <b>uiCommand( 'ask', prompt[, default] )</b><br>
* See CommonGUIExtension::script_ask().</li>
* <li><b>UI.askYN( prompt )</b> or <b>uiCommand( 'askYN', prompt )</b><br>
* See CommonGUIExtension::script_askYN().</li>
* <li><b>UI.openURL( url )</b> or <b>uiCommand( 'openURL', url )</b><br>
* See CommonGUIExtension::script_openURL().</li>
* <li><b>UI.showText( windowTitle, textString )</b>
* or <b>uiCommand( 'showText', windowTitle, textString )</b><br>
* See CommonGUIExtension::script_showText().</li>
* <li><b>UI.inputDialog( titleString, ... )</b>
* or <b>uiCommand( 'inputDialog', titleString, ... )</b><br>
* See CommonGUIExtension::script_inputDialog().</li>
* <li><b>UI.runTests( codeBlock )</b> or <b>uiCommand( 'runTests', codeBlock )</b><br>
* See CommonGUIExtension::script_runTests().</li>
* <li><b>UI.random( a, b )</b> or <b>uiCommand( 'random', a, b )</b><br>
* See CommonGUIExtension::script_random().</li>
* <li><b>UI.getClipboard()</b> or <b>uiCommand( 'getClipboard' )</b><br>
* See CommonGUIExtension::script_getClipboard().</li>
* <li><b>UI.setClipboard( ... )</b> or <b>uiCommand( 'setClipboard', ... )</b><br>
* See CommonGUIExtension::script_setClipboard().</li>
* <li><b>UI.saveSetting( key, value )</b> or <b>uiCommand( 'saveSetting', key, value )</b><br>
* See CommonGUIExtension::script_saveSetting().</li>
* <li><b>UI.loadSetting( key )</b> or <b>uiCommand( 'loadSetting', key )</b><br>
* See CommonGUIExtension::script_loadSetting().</li>
* <li><b>UI.clearSetting( key )</b> or <b>uiCommand( 'clearSetting', key )</b><br>
* See CommonGUIExtension::script_clearSetting().</li>
* <li><b>UI.syntaxHighlight( code[, format] )</b>
* or <b>uiCommand( 'syntaxHighlight', code[, format] )</b><br>
* See CommonGUIExtension::script_syntaxHighlight().</li>
* <li><b>UI.escapeToJavaScriptString( anyString )</b>
* or <b>uiCommand( 'escapeToJavaScriptString', anyString )</b><br>
* See CommonGUIExtension::script_escapeToJavaScriptString().</li>
* <li><b>UI.cursorPosition()</b> or <b>uiCommand( 'cursorPosition' )</b><br>
* See LurchGUIExtension::script_cursorPosition().</li>
* <li><b>UI.selectionAnchor()</b> or <b>uiCommand( 'selectionAnchor' )</b><br>
* See LurchGUIExtension::script_selectionAnchor().</li>
* <li><b>UI.setCursorPosition( n )</b> or <b>uiCommand( 'setCursorPosition', n )</b><br>
* See LurchGUIExtension::script_setCursorPosition().</li>
* <li><b>UI.setSelectionAnchor( n )</b> or <b>uiCommand( 'setSelectionAnchor', n )</b><br>
* See LurchGUIExtension::script_setSelectionAnchor().</li>
* <li><b>UI.lastPosition()</b> or <b>uiCommand( 'lastPosition' )</b><br>
* See LurchGUIExtension::script_lastPosition().</li>
* <li><b>UI.LobAt( n )</b> or <b>uiCommand( 'LobAt', n )</b><br>
* See LurchGUIExtension::script_LobAt().</li>
* <li><b>UI.startPosition( L )</b> or <b>uiCommand( 'startPosition', L )</b>
* or <b>L.startPosition()</b><br>
* See LurchGUIExtension::script_startPosition().</li>
* <li><b>UI.endPosition( L )</b> or <b>uiCommand( 'endPosition', L )</b>
* or <b>L.endPosition()</b><br>
* See LurchGUIExtension::script_endPosition().</li>
* <li><b>UI.setPalette( array )</b> or <b>uiCommand( 'setPalette', array )</b><br>
* See LurchGUIExtension::script_setPalette().</li>
* <li><b>UI.getPalette()</b> or <b>uiCommand( 'getPalette' )</b><br>
* See LurchGUIExtension::script_getPalette().</li>
* <li><b>UI.setTip( L, text )</b> or <b>uiCommand( 'setTip', L, text )</b><br>
* See LurchGUIExtension::script_setTip().</li>
* <li><b>UI.changeDependencies( [...] )</b>
* or <b>uiCommand( 'changeDependencies', [...] )</b><br>
* See LurchGUIExtension::script_changeDependencies().</li>
* </ul>
*
* <h2>Features user interfaces may request of documents</h2>
*
* <p>Calls to add handlers for these features are of the form
* <code>uiFeature.add( name, canUse, use )</code>, where name is a string (the name of the
* feature in the list below), <code>canUse</code> is a function deciding if the feature
* applies in a certain context, and <code>use</code> is a function that will be run if the
* feature does apply, to execute the use of the feature. What parameters those two
* functions should expect are described separately for each feature below.</p>
*
* <p>So far, only one feature is requested by the UI in the current version of Lurch.</p>
*
* <ul>
* <li><b>uiFeature "contextMenu"</b><br>
* A particular call to <code>uiFeature.add( 'contextMenu', ... )</code> will add
* certain context menu items, those that pertain to the library in which the call
* was made. The final result should be an array of the form
* <code>[ 'Entry text 1', functionToRun1, ..., 'Entry text n', functionToRunN ]</code>.
* Entries with >'s in them will create submenus.<br>
* <code>canUse( target )</code>:
* Does the target Lob get the context menu items in question?<br>
* <code>use( target, soFar )</code>:
* Take the context menu entries already added by other handlers into the array soFar,
* and add to them those that this library defines. When providing functions, use
* closures that capture the local variable target, if necessary. Note that soFar
* may be null if this is the first contextMenu handler, and this routine should
* detect that and initialize it to an empty array.</li>
* <li><b>uiFeature "toolsMenu"</b><br>
* Just like contextMenu, except for populating the Tools Menu in the menu bar.
* Thus it does not pass any Lob as parameter.</li>
* <li><b>uiFeature "representation"</b><br>
* A call to <code>uiFeature.add( 'representation', a, b )</code> will add
* a handler for representing Lobs. If the <code>a</code> function returns true when
* called on a Lob, then the <code>b</code> function should return that Lob's
* representation, in one of the following forms. All of them will be rendered as a
* single character in the word processor, an atomic/indivisible thing.
* <ol>
* <li>HTML: Return a string of the form "<html><i>some html code here</i></html>" and
* it will be the representation of the Lob. The HTML will be rendered using a
* QTextDocument, so refer to
* <a href='http://doc.qt.nokia.com/latest/richtext-html-subset.html'>Qt's
* supported HTML subset</a>.</li>
* <li>TeX: Return a string of the form "$<i>some TeX code here</i>$" and it will be the
* representation of the Lob. The TeX will be rendered by a combination of
* BlahTeX with a QtMmlWidget.</li>
* <li>Image: Any image can be the representation of a Lob by returning a data URI
* with the base-64-encoded version of the image, of the form
* "data:<i>mime type here</i>;base64,<i>encoding here</i>"
* <li>Plain text: Return a string of none of the above forms, and it will be treated
* as plain text, one single line, not word-wrapped.</li>
* <li>OpenMath XML source: A syntax-highlighted version of the Lob in OpenMath XML
* form can be obtained by returning the empty string (or simply providing no
* representation handler) for the Lob. This is the default on which Lurch falls
* back if no representation is available.</li>
* <li>Invisible: A Lob can be made invisible by using the a special case of the
* HTML form given above, the one with no content, "<html></html>".</li>
* </ol></li>
* <li><b>uiFeature "explain"</b><br>
* A call to <code>uiFeature.add( 'explain', a, b )</code> will add a handler for
* explaining Lobs. When the user hovers their mouse over a Lob, this feature is
* called on that Lob. If the <code>a</code> function returns true when called on the
* Lob, then the <code>b</code> function should return that Lob's description, in HTML,
* which will be used to populate a tooltip that will appear near the mouse cursor.
* See <a href='http://doc.qt.nokia.com/latest/richtext-html-subset.html'>Qt's
* supported HTML subset</a> for what tags/styles are available.</li>
* </tr>
* </table>
*/