Add usage examples in README and python-notebook

Bridgeconn · Oct 4, 2023 · 7c50c78 · 7c50c78
1 parent 0a4e618
commit 7c50c78
Show file tree

Hide file tree

Showing 3 changed files with 124 additions and 16 deletions.
diff --git a/docs/API guide for python usfm_grammar.ipynb b/docs/API guide for python usfm_grammar.ipynb
@@ -94,7 +94,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 14,
    "id": "5d06e40a",
    "metadata": {},
    "outputs": [],
@@ -104,7 +104,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 15,
    "id": "932320b5",
    "metadata": {},
    "outputs": [],
@@ -172,7 +172,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 16,
    "id": "ad92e648",
    "metadata": {},
    "outputs": [],
@@ -739,20 +739,82 @@
    "source": []
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "a680a0b6",
+   "cell_type": "markdown",
+   "id": "a35acb88-7300-4b84-bd2f-90b7cd90d8fb",
    "metadata": {},
-   "outputs": [],
-   "source": []
+   "source": [
+    "#### USJ to USFM (round tripping)"
+   ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 17,
    "id": "0fac8a56",
    "metadata": {},
-   "outputs": [],
-   "source": []
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\\id EXO 02EXOGNT92.SFM, Good News Translation, June 2003\n",
+      "\\h പുറപ്പാടു്\n",
+      "\\toc1 പുറപ്പാടു്\n",
+      "\\toc2 പുറപ്പാടു്\n",
+      "\\mt പുറപ്പാടു്\n",
+      "\\c 1\n",
+      "\\p \\v 1 യാക്കോബിനോടുകൂടെ കുടുംബസഹിതം ഈജിപ്റ്റിൽ വന്ന\n",
+      "\\p യിസ്രായേൽമക്കളുടെ പേരുകൾ :\\v 2 രൂബേൻ, ശിമെയോൻ, ലേവി,\\v 3 \n",
+      "\\li1 യെഹൂദാ,\n",
+      "\\li1 യിസ്സാഖാർ,\n",
+      "\\li1 സെബൂലൂൻ,\n",
+      "\\li1 ബെന്യാമീൻ\n",
+      "\\p \\v 4 ദാൻ, നഫ്താലി, ഗാദ്, ആശേർ.\\v 12-83 They presented their offerings in the following order:\n",
+      "\\tr \\th1 Day\\th2 Tribe\\th3 Leader\n",
+      "\\tr \\tcr1 1st\\tc2 Judah\\tc3 Nahshon son of Amminadab\n",
+      "\\tr \\tcr1 2nd\\tc2 Issachar\\tc3 Nethanel son of Zuar\n",
+      "\\tr \\tcr1 3rd\\tc2 Zebulun\\tc3 Eliab son of Helon\n",
+      "\\p \\v 5 യാക്കോബിന്റെ സന്താനപരമ്പരകൾ എല്ലാം കൂടി എഴുപതു പേർ ആയിരുന്നു; യോസേഫ് മുമ്പെ തന്നെ ഈജിപ്റ്റിൽ ആയിരുന്നു.\\w gracious\\+nd Lord\\+nd* |lemma=\"grace\" \\+w* and then a few words later\\w gracious|lemma=\"grace\" x-myattr=\"metadata\" \\w* \n",
+      "\\c 2\n",
+      "\\s1 A Prayer of Habakkuk\n",
+      "\\p \\v 1 This is a prayer of the prophet Habakkuk:\n",
+      "\\b \n",
+      "\\q1 \\v 2 O\\nd Lord\\nd* , I have heard of what you have done,\n",
+      "\\q2 and I am filled with awe.\n",
+      "\\q1 Now do again in our times\n",
+      "\\q2 the great deeds you used to do.\n",
+      "\\q1 Be merciful, even when you are angry.\n",
+      "\\p \\v 20 Adam\\f + \\fr 3.20:\\fr* \\fk Adam:\\fk* \\ft This name in Hebrew means “all human beings.”\\ft* \\f* named his wife Eve,\\f + \\fr 3.20:\\fr* \\fk Eve:\\fk* \\ft This name sounds similar to the Hebrew\n",
+      "word for “living,” which is rendered in this context as “human beings.”\\ft* \\f* because she\n",
+      "was the mother of all human beings.\\v 21 And the\\nd Lord\\nd* God made clothes out of animal skins for Adam and his wife,\n",
+      "and he clothed them.\\qt-s |who=\"Pilate\" sid=\"qt_123\" \\*\n",
+      "“Are you the king of the Jews?”\\qt-e |eid=\"qt_123\" \\*\n",
+      "\\esb \\cat History\\cat*\n",
+      "\\ms Fish and Fishing\n",
+      "\\p In Jesus' time, fishing took place mostly on lake Galilee, because Jewish people\n",
+      "could not use many of the harbors along the coast of the Mediterranean Sea, since these\n",
+      "harbors were often controlled by unfriendly neighbors. The most common fish in the Lake\n",
+      "of Galilee were carp and catfish.\\wj The Law of Moses\\wj* allowed people to eat any fish with\n",
+      "fins and scales, but since catfish lack scales (as do eels and sharks) they were not to\n",
+      "be eaten. Fish were also probably brought from Tyre and Sidon,\n",
+      "where they were dried and salted.\n",
+      "...\n",
+      "\\p Among early Christians, the fish was a favorite image for Jesus, because the Greek\n",
+      "word for fish (\\tl ichthus\\tl* ) consists of the first letters of the Greek words that\n",
+      "tell who Jesus is:\\fig Christian Fish Image\\fig* \n",
+      "\\esbe\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "from usfm_grammar import USFMGenerator\n",
+    "\n",
+    "usj_obj = my_parser.to_usj()\n",
+    "\n",
+    "my_generator = USFMGenerator()\n",
+    "my_generator.usj_to_usfm(usj_obj)\n",
+    "print(my_generator.usfm_string)"
+   ]
   },
   {
    "cell_type": "code",
@@ -764,11 +826,30 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 18,
    "id": "1ea6bb28",
    "metadata": {},
-   "outputs": [],
-   "source": []
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\\id EXO 02EXOGNT92.SFM, Good News Translation, June 2003\n",
+      "\\c 1\n",
+      "\\v 1 യാക്കോബിനോടുകൂടെ കുടുംബസഹിതം ഈജിപ്റ്റിൽ വന്ന യിസ്രായേൽമക്കളുടെ പേരുകൾ :\\v 2 രൂബേൻ, ശിമെയോൻ, ലേവി,\\v 3 യെഹൂദാ, യിസ്സാഖാർ, സെബൂലൂൻ, ബെന്യാമീൻ\\v 4 ദാൻ, നഫ്താലി, ഗാദ്, ആശേർ.\\v 12-83 They presented their offerings in the following order: Day Tribe Leader 1st Judah Nahshon son of Amminadab 2nd Issachar Nethanel son of Zuar 3rd Zebulun Eliab son of Helon\\v 5 യാക്കോബിന്റെ സന്താനപരമ്പരകൾ എല്ലാം കൂടി എഴുപതു പേർ ആയിരുന്നു; യോസേഫ് മുമ്പെ തന്നെ ഈജിപ്റ്റിൽ ആയിരുന്നു. gracious Lord and then a few words later gracious \\c 2\n",
+      "\\v 1 This is a prayer of the prophet Habakkuk:\\v 2 O Lord, I have heard of what you have done, and I am filled with awe. Now do again in our times the great deeds you used to do. Be merciful, even when you are angry.\\v 20 Adam named his wife Eve, because she\n",
+      "was the mother of all human beings.\\v 21 And the Lord God made clothes out of animal skins for Adam and his wife,\n",
+      "and he clothed them. “Are you the king of the Jews?” \n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "usj_obj2 = my_parser.to_usj(include_markers=Filter.BCV+Filter.TEXT)\n",
+    "my_generator2 = USFMGenerator()\n",
+    "my_generator2.usj_to_usfm(usj_obj2)\n",
+    "print(my_generator2.usfm_string)"
+   ]
   },
   {
    "cell_type": "code",

diff --git a/py-usfm-parser/README.md b/py-usfm-parser/README.md
@@ -86,6 +86,33 @@ print(table_output)
 
 ```
 
+To round trip
+```
+from usfm_grammar import USFMParser, Filter
+from usfm_grammar import USFMParser, USFMGenerator
+
+my_parser = USFMParser(input_usfm_str)
+usj_obj = my_parser.to_usj()
+
+my_generator = USFMGenerator()
+my_generator.usj_to_usfm(usj_obj)
+print(my_generator.usfm_string)
+
+```
+:warning: There will be differences between first USFM and the generated one in 1. Spaces and lines 2. Default attributes will be given their names 3. Closing markers may be newly added
+
+To remove unwanted markers from USFM
+```
+from usfm_grammar import USFMParser, Filter, USFMGenerator
+
+my_parser = USFMParser(input_usfm_str)
+usj_obj = my_parser.to_usj(include_markers=Filter.BCV+Filter.TEXT)
+
+my_generator = USFMGenerator()
+my_generator.usj_to_usfm(usj_obj)
+print(my_generator.usfm_string)
+```
+
 ### From CLI
 
 ```

diff --git a/py-usfm-parser/src/usfm_grammar/usfm_generator.py b/py-usfm-parser/src/usfm_grammar/usfm_generator.py
@@ -84,6 +84,6 @@ def usj_to_usfm(self, usj_obj: dict, nested=False) -> None: # pylint: disable=to
                 self.usfm_string += "\n"
 
     # def usx_to_usfm(self, usx_xml_tree) -> str: # should we call it just from_usx() instead
-    #     '''Traverses xml tree and converts nodes to usfm elements based on type and style fields'''
+    #     '''Traverses xml tree and converts nodes to usfm elements
+    #     based on type and style fields'''
     #     return self.usfm_string
-