{"id":19019007,"url":"https://github.com/bridgeconn/usfm-grammar","last_synced_at":"2026-02-03T06:17:34.889Z","repository":{"id":33695940,"uuid":"100146103","full_name":"Bridgeconn/usfm-grammar","owner":"Bridgeconn","description":"An elegant USFM parser.","archived":false,"fork":false,"pushed_at":"2025-01-23T07:02:56.000Z","size":16717,"stargazers_count":40,"open_issues_count":16,"forks_count":16,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-01-26T09:23:04.761Z","etag":null,"topics":["grammar","javascript","parser","parser-generator","scripture-open-components","usfm","usfm-converter","usfm-grammar","usfm-json","usfm-validator"],"latest_commit_sha":null,"homepage":"https://usfmgrammar.vachanengine.org/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Bridgeconn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-13T01:14:02.000Z","updated_at":"2025-01-24T15:45:45.000Z","dependencies_parsed_at":"2023-09-22T13:32:03.173Z","dependency_job_id":"37ee607f-1f1e-497e-85da-e1f4b8ea222c","html_url":"https://github.com/Bridgeconn/usfm-grammar","commit_stats":{"total_commits":407,"total_committers":8,"mean_commits":50.875,"dds":"0.18918918918918914","last_synced_commit":"565b292dfe4ebd57b58129f806203de833df38fc"},"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bridgeconn%2Fusfm-grammar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bridgeconn%2Fusfm-grammar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bridgeconn%2Fusfm-grammar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bridgeconn%2Fusfm-grammar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bridgeconn","download_url":"https://codeload.github.com/Bridgeconn/usfm-grammar/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247339149,"owners_count":20923014,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["grammar","javascript","parser","parser-generator","scripture-open-components","usfm","usfm-converter","usfm-grammar","usfm-json","usfm-validator"],"created_at":"2024-11-08T20:10:30.631Z","updated_at":"2026-02-03T06:17:34.881Z","avatar_url":"https://github.com/Bridgeconn.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# USFM Grammar\n\nAn elegant [USFM](https://docs.usfm.bible) parser (or validator) that uses a Context Free Grammar to model USFM. The grammar is written using [tree sitter](https://tree-sitter.github.io/tree-sitter/). **Supports USFM 3.x** onward. \n\nThe USFM is parsed into a syntax tree, which may then be futher converted to more easy-to-manipulate file formats that allow for painless extraction of scriptural and other content from the markup. USFM Grammar is also capable of reconverting the generated formats back into USFM.\n\n## Features\n- Parses scripture in USFM, USX (as XML) and USJ (as JSON) formats. See [specification docs](https://docs.usfm.bible/usfm/latest/syntax.html) for more information.\n- And then can convert to any of USJ, USX, USFM, CSV/TSV or [BibleNLP](https://github.com/BibleNLP/ebible?tab=readme-ov-file#data-format) formats.\n- Bindings available for [Python](https://pypi.org/project/usfm-grammar/), [NodeJS](https://www.npmjs.com/package/usfm-grammar) and the [Web](https://www.npmjs.com/package/usfm-grammar-web).\n- Command Line Interface (CLI) via the Python package.\n- Ability to selectively include or exclude markers in the converted output.\n- USFM validation and error detection.\n- Auto-fix errors in USFM (experimental).\n\n## Try it out \n\nCheckout the demo application at https://usfmgrammar.vachanengine.org/.\n\nFor guidance on using the libraries, refer to the example usages and documentation: [Python Docs](./py-usfm-parser/README.md), [Node Docs](./node-usfm-parser/README.md) and [Web Docs](./web-usfm-parser/README.md).\n\n## Example Input/Output\n\n### Input USFM\u003c/th\u003e\u003c/tr\u003e\u003ctd\u003e\n\n```\n\\id hab 45HABGNT92.usfm, Good News Translation, June 2003\n\\c 3\n\\s1 A Prayer of Habakkuk\n\\p\n\\v 1 This is a prayer of the prophet Habakkuk:\n\\b\n\\q1\n\\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```\n  \n### JSON (USJ) Output\n\n```\n{   \"type\": \"USJ\",\n    \"version\": \"3.1\",\n    \"content\": [\n        {   \"type\": \"book\",\n            \"marker\": \"id\",\n            \"content\": [\"45HABGNT92.usfm, Good News Translation, June 2003\"],\n            \"code\": \"HAB\" },\n        {   \"type\": \"chapter\",\n            \"marker\": \"c\",\n            \"number\": \"3\",\n            \"sid\": \"HAB 3\" },\n        {   \"type\": \"para\",\n            \"marker\": \"s1\",\n            \"content\": [\"A Prayer of Habakkuk\\n\"] },\n        {   \"type\": \"para\",\n            \"marker\": \"p\",\n            \"content\": [\n                {   \"type\": \"verse\",\n                    \"marker\": \"v\",\n                    \"number\": \"1\",\n                    \"sid\": \"HAB 3:1\" },\n                \"This is a prayer of the prophet Habakkuk:\\n\"\n            ] },\n        {   \"type\": \"para\",\n            \"marker\": \"b\" },\n        {   \"type\": \"para\",\n            \"marker\": \"q1\",\n            \"content\": [\n                {   \"type\": \"verse\",\n                    \"marker\": \"v\",\n                    \"number\": \"2\",\n                    \"sid\": \"HAB 3:2\" },\n                \"O \",\n                {   \"type\": \"char\",\n                    \"marker\": \"nd\",\n                    \"content\": [ \"Lord\" ] },\n                \", I have heard of what you have done,\\n\"\n            ] },\n        {   \"type\": \"para\",\n            \"marker\": \"q2\",\n            \"content\": [ \"and I am filled with awe.\\n\" ] },\n        {   \"type\": \"para\",\n            \"marker\": \"q1\",\n            \"content\": [ \"Now do again in our times\\n\" ] },\n        {   \"type\": \"para\",\n            \"marker\": \"q2\",\n            \"content\": [ \"the great deeds you used to do.\\n\" ] },\n        {   \"type\": \"para\",\n            \"marker\": \"q1\",\n            \"content\": [ \"Be merciful, even when you are angry.\" ] }\n    ]\n}\n\n```\n\nThe converted JSON structure adheres to the JSON Schema specification defined by the USFM/USX/USJ Committee [here](https://github.com/usfm-bible/tcdocs/blob/main/grammar/usj.js).\n\n### XML (USX) output\n\n```\n\u003cusx version=\"3.1\"\u003e\n  \u003cbook code=\"HAB\" style=\"id\"\u003e45HABGNT92.usfm, Good News Translation, June 2003\u003c/book\u003e\n  \u003cchapter number=\"3\" style=\"c\" sid=\"HAB 3\"/\u003e\n  \u003cpara style=\"s1\"\u003eA Prayer of Habakkuk\n\u003c/para\u003e\n  \u003cpara style=\"p\"\u003e\u003cverse number=\"1\" style=\"v\" sid=\"HAB 3:1\"/\u003eThis is a prayer of the prophet Habakkuk:\n\u003c/para\u003e\n  \u003cpara style=\"b\"\u003e\n    \u003cverse eid=\"HAB 3:1\"/\u003e\n  \u003c/para\u003e\n  \u003cpara style=\"q1\"\u003e\u003cverse number=\"2\" style=\"v\" sid=\"HAB 3:2\"/\u003eO \u003cchar style=\"nd\" closed=\"true\"\u003eLord\u003c/char\u003e, I have heard of what you have done,\n\u003c/para\u003e\n  \u003cpara style=\"q2\"\u003eand I am filled with awe.\n\u003c/para\u003e\n  \u003cpara style=\"q1\"\u003eNow do again in our times\n\u003c/para\u003e\n  \u003cpara style=\"q2\"\u003ethe great deeds you used to do.\n\u003c/para\u003e\n  \u003cpara style=\"q1\"\u003eBe merciful, even when you are angry.\u003cverse eid=\"HAB 3:2\"/\u003e\u003c/para\u003e\n  \u003cchapter eid=\"HAB 3\"/\u003e\n\u003c/usx\u003e\n```\n\n\n### TSV output\n  \n```\nBook    Chapter Verse   Text                                                Type    Marker\nHAB                     45HABGNT92.usfm, Good News Translation, June 2003   book    id\nHAB     3               \"A Prayer of Habakkuk\\n\"                            para    s1\nHAB     3       1       \"This is a prayer of the prophet Habakkuk:\\n\"       para    p\nHAB     3       2       O                                                   para    q1\nHAB     3       2       Lord                                                char    nd\nHAB     3       2       \", I have heard of what you have done,\\n\"           para    q1\nHAB     3       2       \"and I am filled with awe.\\n\"                       para    q2\nHAB     3       2       \"Now do again in our times\\n\"                       para    q1\nHAB     3       2       \"the great deeds you used to do.\\n\"                 para    q2\nHAB     3       2       Be merciful, even when you are angry.               para    q1\n\n```\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbridgeconn%2Fusfm-grammar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbridgeconn%2Fusfm-grammar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbridgeconn%2Fusfm-grammar/lists"}