usfm-grammar-web 3.2.1 → 3.2.2

package/README.md

@@ -3,6 +3,8 @@
 ## Description
 This is the web alternative to the (USFM-Grammar 3.x)[https://www.npmjs.com/package/usfm-grammar] library to be used from HTML, react etc. USFM Grammar is a JavaScript library for parsing and converting USFM (Unified Standard Format Markers) to/from USJ (Unified Standard JSON) format. This library provides functionalities to parse USFM strings into a syntax tree and convert them into a JSON-like structure (USJ), and vice versa.
 
+> :information_source: For Node.js, use the [usfm-grammar](https://www.npmjs.com/package/usfm-grammar) package; `usfm-grammar-web` is for browsers and bundlers.
+
 ## Installation
 You can install USFM Grammar via npm:
 
@@ -23,10 +25,10 @@ function App() {
 
   useEffect(() => {
     const initParser = async () => {
-      await USFMParser.init("https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.1/tree-sitter-usfm.wasm",
-                            "https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.1/tree-sitter.wasm");
-      await Validator.init("https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.1/tree-sitter-usfm.wasm",
-                            "https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.1/tree-sitter.wasm");
+      await USFMParser.init("https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.2/tree-sitter-usfm.wasm",
+                            "https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.2/web-tree-sitter.wasm");
+      await Validator.init("https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.2/tree-sitter-usfm.wasm",
+                            "https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.2/web-tree-sitter.wasm");
 
     };
     initParser();
@@ -60,13 +62,13 @@ It can be used directly in the HTML script tag too. Please ensure its dependenci
 
 ```html
 <script type="module">
-  import { USFMParser, Filter, Validator } from 'https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.1/dist/bundle.mjs';
+  import { USFMParser, Filter, Validator } from 'https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.2/dist/bundle.mjs';
   console.log('Hello world');
   (async () => {
-  await USFMParser.init("https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.1/tree-sitter-usfm.wasm",
-                            "https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.1/tree-sitter.wasm");
-  await Validator.init("https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.1/tree-sitter-usfm.wasm",
-                            "https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.1/tree-sitter.wasm");
+  await USFMParser.init("https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.2/tree-sitter-usfm.wasm",
+                            "https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.2/web-tree-sitter.wasm");
+  await Validator.init("https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.2/tree-sitter-usfm.wasm",
+                            "https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.2/web-tree-sitter.wasm");
   const usfmParser = new USFMParser('\\id GEN\n\\c 1\n\\p\n\\v 1 In the begining..\\v 2 more text')
   const output = usfmParser.toUSJ()
   console.log({ output })
@@ -109,7 +111,7 @@ Working with USJ, also gives options like filtering selected markers, to edit th
 
 To work with the XML format, USX:
 ```javascript
-import { DOMImplementation, XMLSerializer } from 'xmldom';
+import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
 
 const USFM = '\\id GEN\n\\c 1\n\\p\n\\v 1 In the begining..\\v 2 some more text'
 const usfmParser = new USFMParser(USFM);
@@ -123,6 +125,11 @@ console.log(usx);
 const usfmParser2 = new USFMParser(null, null, usxElem) // USX to USFM
 const usfmGen = usfmParser2.usfm;
 console.log(usfmGen);
+
+// USX from a string e.g. uploaded file contents
+const usxText = '<usx version="3.1"><book code="GEN" style="id"/><chapter number="1" style="c"/><para style="p"><verse number="1" style="v"/>In the beginning...</para></usx>'; 
+const usxDoc = new DOMParser().parseFromString(usxText.replace(/^/, ''), 'text/xml'); // strip BOM, if any
+const usfmParser3 = new USFMParser(null, null, usxDoc.documentElement);
 ```
 ### BibleNLP format
 Bible NLP format consists of two `txt` files: the first, with verse texts, one per line and the second, with corresponding references. The API generates a JSON with two fields, `text` and `vref`, each containing an array of strings.
@@ -197,9 +204,9 @@ const simpleUSJ = {
     { type: 'book', marker: 'id', code: 'GEN', content: [] },
     { type: 'chapter', marker: 'c', number: '1', sid: 'GEN 1' },
     { type: 'para', marker: 'p', content: [
-        {type: 'verse', marker: 'v', number: 1 },
+        {type: 'verse', marker: 'v', number: '1' },
         "In the begining..",
-        {type: 'verse', marker: 'v', number: 2 }
+        {type: 'verse', marker: 'v', number: '2' }
       ] }
   ]
 }
@@ -222,7 +229,7 @@ The filtering on USJ, the JSON output, is a feature incorporated to allow data e
 
 - *combineTexts*
 
-   Fourth input parameter to `toUSJ()` and `toList` of `USFMParser` class. Defaults to `true`. After filtering out makers like paragraphs and characters, we are left with texts from within them, if 'text-in-excluded-parent' is also not excluded. These text snippets may come as separate components in the contents list. When this option is `True`, the consequetive text snippets will be concatinated together. The text concatination is done in a puctuation and space aware manner. If users need more control over the space handling or for any other reason, would prefer the texts snippets as different components in the output, this can be set to `False`.
+   Fourth input parameter to `toUSJ()` and `toList` of `USFMParser` class. Defaults to `true`. After filtering out makers like paragraphs and characters, we are left with texts from within them, if 'text-in-excluded-parent' is also not excluded. These text snippets may come as separate components in the contents list. When this option is `True`, the consequetive text snippets will be concatenated together. The text concatenation is done in a puctuation and space aware manner. If users need more control over the space handling or for any other reason, would prefer the texts snippets as different components in the output, this can be set to `False`.
 
 - *usfm_grammar.Filter*
 
@@ -234,12 +241,13 @@ The filtering on USJ, the JSON output, is a feature incorporated to allow data e
     PARAGRAPHS : paragraph markers like \p, poetry markers, list table markers
     CHARACTERS : all character level markups like \em, \w, \wj etc and their nested versions with +
     NOTES : foot note, cross-reference and their content markers
+    LISTS : list markers like \li, \lh, \lim and the \list-s/\list-e milestones
     STUDY_BIBLE : \esb and \cat
     BCV : \id, \c and \v
-    TEXT : 'text-in-excluded-parent'
+    TEXT : 'text-in-excluded-parent' and 'text'
     ZNAMESPACES : all user-extended \z markers, as one group
     ```
-    To inspect which are the markers in each of these options, it could be just printed out, `print(Filter.TITLES)`. These could be used individually or concatinated to get the desired filtering of markers and data:
+    To inspect which are the markers in each of these options, it could be just printed out, `console.log(Filter.TITLES)`. These could be used individually or concatenated to get the desired filtering of markers and data:
     ```javascript
     output = usfmParser.toUSJ(null, Filter.BCV) //to include
     output = usfmParser.toUSJ(null, [...Filter.BCV, ...Filter.TEXT]) //to include
@@ -265,8 +273,8 @@ The USFM spec reserves markers beginning with `\z` for [user-defined extensions]
   ```javascript
   import {USFMParser, Filter} from 'usfm-grammar-web';
 
-  await USFMParser.init("https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.1/tree-sitter-usfm.wasm",
-                        "https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.1/tree-sitter.wasm");
+  await USFMParser.init("https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.2/tree-sitter-usfm.wasm",
+                        "https://cdn.jsdelivr.net/npm/usfm-grammar-web@3.2.2/web-tree-sitter.wasm");
 
   const myParser = new USFMParser(inputUsfm, null, null, null, null, markersExt);
   const output = myParser.toUSJ();
@@ -307,7 +315,7 @@ The USFM spec reserves markers beginning with `\z` for [user-defined extensions]
 
   A `\category` outside this list, or a block with no `\category` at all, raises an error.
 
-  :warning: Only the major type is used. The minor type, and the rules the spec attaches to it about where such a marker may occur, are not enforced — a declared extension marker is accepted anywhere in the document. So declaring `\category title` rather than `\category para` changes nothing about the output; both produce a `para`.
+  :warning: Only the major type is used. The minor type, and the rules the spec attaches to it about where such a marker may occur, are not enforced — a declared extension marker is accepted anywhere in the document. So declaring `\category title` rather than `\category para` changes nothing about the output; both produce a `para`. In particular, a `versepara` extension is not treated as verse text: its content is not attributed to the preceding verse (e.g. for `vid` on continuation paragraphs or the BibleNLP/list outputs and filtered USJs).
 
 - *Expected syntax per major type*
 
@@ -331,7 +339,10 @@ The USFM spec reserves markers beginning with `\z` for [user-defined extensions]
   ```
   \zbadge outer \nd Lord\nd* text\zbadge*
   \zbadge content|lemma="value"\zbadge*
+  \c 1
+  \zheading A line \v 1 verse text
   ```
+  A verse cannot be part of a custom para either. A `\v` ends the custom para. When the custom para sits within a verse para such as `\p`, the verse continues in that enclosing para; otherwise, as in the last example, it is a parsing error.
 
 - *When no markers.ext is given*