`` in a name class is recorded in the\n``except`` field of the patterns above.\n\nHere are a couple of examples. The name class for::\n\n element (foo | bar | foo:foo) { ... }\n\nwould be recorded as (after partial beautification)::\n\n {\n a: {\n a: {ns: \"\", name: \"foo\"},\n b: {ns: \"\", name: \"bar\"}\n },\n b: {ns: \"foo:foo\", name: \"foo\"}\n }\n\nThe name class for::\n\n element * - (foo:* - foo:a) { ... }\n\nwould be recorded as (after partial beautification)::\n\n {\n pattern: \"AnyName\",\n except: {\n ns: \"foo:foo\",\n except: {ns: \"foo:foo\", name: \"a\"}\n }\n }\n\nClients may want to call the ``.simple()`` method on a name pattern to determine\nwhether it is simple or not. A pattern is deemed \"simple\" if it is composed only\nof ``Name`` and ``NameChoice`` objects. Such a pattern could be presented to a\nuser as a finite list of possibilities. Otherwise, if the pattern is not simple,\nthen either the number of choices is unbounded or it not a discrete list of\nitems. In such a case, the client code may instead present to the user a field\nin which to enter the name of the element or attribute to be created and\nvalidate the name against the pattern. The method ``.toArray()`` can be used to\nreduce a pattern which is simple to an array of ``Name`` objects.\n\nEvent Asymmetry\n---------------\n\n**Note that the events returned by ``possible()`` are *not identical* to the\nevents that ``fireEvent()`` expects.** While most events returned are exactly\nthose that would be passed to ``fireEvent()``, there are three exceptions: the\n``enterStartTag``, ``endTag`` and ``attributeName`` events returned by\n``possible()`` will have a single parameter after the event name which is an\nobject of ``name_patterns.Base`` class. However, when passing a corresponding\nevent to ``fireEvent()``, the same events take two string parameters after the\nevent name: a namespace URL and a local name. To spell it out, they are of this\nform::\n\n event_name, [uri, local-name]\n\nwhere ``event_name`` is the string which is the name of the event to fire,\n``uri`` is the namespace URI and ``local-name`` is the local name of the element\nor attribute.\n\nError Messages\n--------------\n\nError messages that report attribute or element names use the\n``name_patterns.Name`` class to record names, even in cases where\n``patterns.EName`` would do. This is for consistency purposes, because some\nerror messages **must** use ``name_patterns`` objects to report their\nerrors. Rather than have some error messages use ``EName`` and some use the\nobject in ``name_patterns`` they all use the objects in ``name_patterns``, with\nthe simple cases using ``name_patterns.Name``.\n\nIn most cases, in order to present the end user of your application with error\nmessages that make sense *to the user*, you will need to process error\nmessages. This is because error messages generated by salve provide in the error\nobject ``(ns, local name)`` pairs. A user would most likely like to see a\nnamespace prefix rather than URI (``ns``). However, since namespace prefixes are\na matter of user preference, and there may be many ways to decide how to\nassociate a namespace prefix with a URI, salve does not take a position in this\nmatter and lets the application that uses it decide how it wants to present URIs\nto users. The application also has to determine what strategy to use to present\ncomplex (i.e., non-simple) name patterns to the user. Again, there is no\none-size-fits-all solution.\n\nMisplaced Elements\n==================\n\nA problem occurs when validating an XML document that contains an unexpected\nelement. In such case, salve will issue an error but then what should it do with\nthe contents of the misplaced element? Salve handles this in two ways:\n\n1. If the unexpected element is known in the schema and has only one definition,\n then salve will assume that the user meant to use the element defined in the\n schema and will validate it as such.\n\n2. Otherwise, salve will turn off validation until the element is closed.\n\nConsider the following case::\n\n Here we have a JohnDoe\n because the person's name is not known.
\n\nIf ``name`` cannot appear in ``p`` but ``name`` has only one definition in the\nschema, then salve will emit an error upon encountering the ``enterStartTag``\nevent for ``name``, and then validate ``name`` as if it had been found in a\nvalid place. If it turns out that the schema defines one ``name`` element which\ncan appear inside a ``person`` element and another ``name`` element which can\nappear inside a ``location`` element (which would be possible with Relax NG),\nthen salve will emit an error but won't perform any validation inside\n``name``. Validation will resume after the ``endTag`` event for\n``name``. (Future versions of salve may implement logic to figure out ambiguous\ncases such as this one.) This latter scenario also occurs if ``name`` is not\ndefined at all by the schema.\n\nDocumentation\n=============\n\nThe code is documented using ``typedoc``. The following command will generate\nthe documentation::\n\n $ gulp doc\n\nYou may need to create a ``gulp.local`` module to tell ``gulp`` where to get\n``rst2html``. (Defaults are such that ``gulp`` will use your ``PATH`` to locate\nsuch tools.) The formatted documentation will appear in the ``build/api/``\nsubdirectory, and the ``README.html`` in the root of the source tree.\n\n**NOTE**: All the public interfaces of salve are available through the\n``validate`` module. However, ``validate`` is a facade that exposes interfaces\nthat are implemented in separate modules like ``patterns`` and ``formats``.\n\nDependencies\n============\n\nIn Node\n-------\n\nWhenever you call on salve's functionalities to read a Relax NG schema, the\n``fetch`` function must be available in the global space for salve to use. On\nNode, this means you must load a polyfill to provide this function.\n\nRunning salve's tests **additionally** requires that the development\ndependencies be installed. Please see the ``package.json`` file for details\nregarding these dependencies. Note that ``gulp`` should be installed so that its\nexecutable is in your path. Either this, or you will have to execute\n``./node_modules/.bin/gulp``\n\nIf you want to contribute to salve, your code will have to pass the checks\nlisted in ``.glerbl/repo_conf.py``. So you either have to install glerbl to get\nthose checks done for you or run the checks through other means. See\n[Contributing](#contributing).\n\nIn The Browser\n--------------\n\nThe following lists the most prominent cases. It is not practical for us to keep\ntrack of every single feature that old browsers like IE11 don't support.\n\n* ``fetch`` must be present.\n\n* ``Promise`` must be present.\n\n* ``Object.assign`` must be present.\n\n* ``URL`` must be present.\n\n* ``Symbol`` [and ``Symbol.iterator``] must be present.\n\n* The String methods introduced by ES6 (``includes``, ``endsWith``, etc.)\n\n* ``Array.prototype.includes``\n\n* Old ``Set`` and ``Map`` implementations like those in IE11 are either broken\n or incomplete.\n\nOn old browsers, we recommend using ``core-js`` to take care of many of these in\none fell swoop. You'll have to provide polyfills for ``fetch`` and ``URL`` from\nother sources.\n\nNote that we do not support old browsers. Notably, salve won't run on any\nversion of IE.\n\nBuild System\n============\n\nSalve uses gulp. Salve's build setup gets the values for its configuration\nvariables from three sources:\n\n* Internal default values.\n\n* From an optional ``gulp.local.js`` module that can override the\n internal defaults.\n\n* From command line options that can override everything above.\n\nThe variables that can be set are:\n\n+-----------------------+------------------------------------------------------+\n|Name | Meaning |\n+=======================+======================================================+\n|``doc_private`` | Whether to produce documentation for private |\n| | entities. You can set ``doc_private`` to ``false`` |\n| | using ``no_doc_private``. |\n+-----------------------+------------------------------------------------------+\n|``mocha_grep`` | ``--grep`` parameter for Mocha |\n+-----------------------+------------------------------------------------------+\n|``rst2html`` | ``rst2html`` command to run |\n+-----------------------+------------------------------------------------------+\n\nNote that when used on the command line, underscores become dashes, thus\n``--mocha-grep`` and ``--doc-private``.\n\nThe ``gulp.local.js`` file is a module. You must export values\nlike this::\n\n exports.doc_private = true\n\nBuilding\n========\n\nRun::\n\n $ gulp\n\nThis will create a ``build/dist/`` subdirectory in which the JavaScript\nnecessary to validate XML files against a prepared Relax NG schema. You could\ncopy what is in ``build/dist>`` to a server to serve these files to a client\nthat would then perform validation.\n\nDeploying\n=========\n\nWhen you install salve through `npm`, you get a package that contains:\n\n* a hierarchy of CommonJS modules in `lib`,\n* a minified UMD build as `salve.min.js`.\n\nThe UMD build can be loaded in a CommonJS environment, in a AMD environment or\nas \"plain scripts\" in a browser. If you use the latter, then salve will be\naccessible as the `salve` global.\n\nTesting\n=======\n\nRunning the following command from the root of salve will run the tests::\n\n $ gulp test\n\nRunning ``mocha`` directly also works, but this may run the test against stale\ncode, whereas ``gulp test`` always runs a build first.\n\nContributing\n============\n\nContributions must pass the commit checks turned on in\n``glerbl/repo_conf.py``. Use ``glerbl install`` to install the hooks. Glerbl\nitself can be found at https://github.com/lddubeau/glerbl. It will eventually\nmake its way to the Python package repository so that ``pip install glerbl``\nwill work.\n\nSchema File Format\n==================\n\n``writeTreeToJSON`` converts a Relax NG file formatted in XML into a more\ncompact format used by salve at validation time. Salve supports version 3 of\nthis file format. Versions 0 to 2 are now obsolete. The structure is::\n\n {\"v\":,\"o\":,\"d\":[...]}\n\nThe ``v`` field gives the version number of the data. The ``o`` field is a bit\nfield of options indicating how the file was created. Right now the only thing\nit records is whether or not element paths are present in the generated\nfile. The ``d`` field contains the actual schema. Each item in it is of the\nform::\n\n [, ...]\n\nThe first element, ````, determines how to interpret the array. The\narray type could indicate that the array should be interpreted as an actual\narray or that it should be interpreted as an object of type ``Group`` or\n``Choice``, etc. If it is an array, then ```` is discarded and the\nrest of the array is the converted array. If it is another type of object then\nagain the ```` is discarded and an object is created with the rest\nof the array as its constructor's parameters. All the array's elements after\n```` can be JSON primitive types, or arrays to be interpreted as\nactual arrays or as objects as described above.\n\nLicense\n=======\n\nOriginal Code\n-------------\n\nCode completely original to salve is released under the [Mozilla Public License\nversion 2.0](http://www.mozilla.org/MPL/2.0/). Copyright 2013-2016 Mangalam\nResearch Center for Buddhist Languages, Berkeley, CA.\n\nRNG Simplification Code\n-----------------------\n\nThe RNG simplification files coded in XSL were adapted from [Nicolas Debeissat's\ncode](https://github.com/ndebeiss/jsrelaxngvalidator/commit/8d353c73880ff519b31193905638cc97a93d1fad). These\nfiles were originally released under the [CeCILL\nlicense](http://www.cecill.info/index.en.html). Nicolas in [March\n2016](https://github.com/ndebeiss/jsrelaxngvalidator/commit/f7336b2472baec60ab16571b865447e1146196ab)\nthen changed the license to the Apache License 2.0.\n\nIn the version of these files bundled with salve, multiple bugs have been\ncorrected, some minor and some major, and some changes have been made for\nsalve's own internal purposes. For the sake of simplicity, these changes are\nalso covered by the original licenses that apply to Nicolas' code.\n\nCredits\n=======\n\nSalve is designed and developed by Louis-Dominique Dubeau, Director of\nSoftware Development for the Buddhist Translators Workbench project,\nMangalam Research Center for Buddhist Languages.\n\nJesse Bethel has contributed to salve's documentation, and migrated salve's\nbuild system from Make to Grunt.\n\n[](http://www.mangalamresearch.org/)\n\nThis software has been made possible in part by a Level I Digital Humanities\nStart-up Grant and a Level II Digital Humanities Start-up Grant from the\nNational Endowment for the Humanities (grant numbers HD-51383-11 and\nHD-51772-13). Any views, findings, conclusions, or recommendations expressed in\nthis software do not necessarily represent those of the National Endowment for\nthe Humanities.\n\n[](http://www.neh.gov/)\n\n# LocalWords: fireEvent js chai semver json xmllint xsltproc npm\n# LocalWords: RNG minified rng XSLT xsl constructTree newWalker mk\n# LocalWords: xml enterStartTag uri leaveStartTag endTag nxml html\n# LocalWords: attributeName attributeValue Debeissat's API\n# LocalWords: CeCILL tokenizer Makefile README boolean anyName RST\n# LocalWords: nsName URIs uris enterContext leaveContext xmlns rst\n# LocalWords: definePrefix useNameResolver foons resolveName HD NG\n# LocalWords: args param TEI glerbl Github reStructuredText readme\n# LocalWords: validator namespace RequireJS subdirectory DOM cli\n# LocalWords: Dubeau Mangalam argparse Gruntfile Bethel unclosed\n# LocalWords: runnable namespaces reparsing amd executables usr lt\n# LocalWords: deployable schemas LocalWords api dir maxInclusive\n# LocalWords: minInclusive minExclusive maxExclusive cd abcd jing\n# LocalWords: github jison NaN baz emph lodash xregexp XRegExp ns\n# LocalWords: init positiveInteger NCName NameChoice superName\n# LocalWords: EName\n","readmeFilename":"README.md"}