# textx-lang-json
**textx-lang-json** is a python implementation of the JSON (JavaScript Object Notation) data interchange format [RFC8259](https://www.rfc-editor.org/rfc/rfc8259) using the [textX](https://textx.github.io/textX/) meta-language. Though it is not intended to replace the standard python JSON encoder and decoder [Lib/json](https://docs.python.org/3/library/json.html), which is much faster, it is a good alternative when you want to mix some JSON in your own textX grammar, or a good starting point should you want to develop your own JSON-like grammar.
The `textxjson` package provides a parser (basically a *textX* *metamodel*), able to build a *textx* *model* from a JSON file or string. This model can be visualized, for educational purpose, but more importantly can be *decoded* to obtain the usual (as done by [Lib/json](https://docs.python.org/3/library/json.html)) python representation of the JSON document.
**textx-lang-json** has been created by Jean-François Baget at the [Boreal](https://team.inria.fr/boreal/) team ([Inria](https://www.inria.fr/fr) and [LIRMM](https://www.lirmm.fr/)). It is part of the [textx-lang-dlgpe]() project.
### Walkthrough
The following code demonstrates, in python, how to build a `parser`, generate a `model` from a python string respecting the JSON standard, and `decode` the model to obtain the usual python representation of the python string (in that case a dictionary). It also shows that `parser.model_from_str(data).decode()` returns the same python object as the standard `json.loads(data)`.
```python
from textx import metamodel_for_language
parser = metamodel_for_language('textxjson') # building the parser
data = '{"Hello": "World"}' # data is a python string respecting the JSON format
model = parser.model_from_str(data) # model is a JsonText object
textxresult = model.decode() # textxresult is a python dictionary
test1 = textxresult == {'Hello' : 'World'} # test1 is True
import json
jsonresult = json.loads(data) # using the standard python function to decode data
test2 = textxresult == jsonresult # test2 is True
```
Note that a parser can also read a JSON file:
```python
model = parser.model_from_file("./path/to/data.json")
```
## Installation
```
pip install textx-lang-json
```
### Testing
You can test that everything behaves correctly (but first you have to clone the whole repository).
```
git clone https://github.com/Jean-Francois-Baget/textx-lang-json.git
cd textx-lang-json
python -m unittest
```
```
..............
----------------------------------------------------------------------
Ran 14 tests in 11.538s
OK
```
Thanks to [ArenaNet](https://www.arena.net/) whose [GW2 API](https://wiki.guildwars2.com/wiki/API:Main) provided some data used in our testbed.
## Usage
### Building the parser
The first thing to do is to build the Json parser. This can be done with the following code.
```python
from textx import metamodel_for_language
parser = metamodel_for_language('textxjson')
```
#### Visualizing the grammar
This parser can be used to obtain a graphical representation of the grammar [json.tx](./src/textxjson/grammar/json.tx). For more details on textx visualization, see https://textx.github.io/textX/visualization.html.
```python
from textx.export import metamodel_export
metamodel_export(parser, 'json.dot')
```
This codes generates a file `json.dot` that can be visualized with [Graphviz](https://graphviz.org/), as shown below.
### Parsing JSON
Most importantly, the parser can be used to generate a *model* from a python string encoding some JSON data, or directly from a JSON file.
#### Parsing a python string
The parsing below is demonstrated using a python string.
```python
some_json = r'''
{
"name" : "textx-lang-json",
"authors" : [
"Jean-François Baget"
],
"year" : 2024,
"tested" : true
}
'''
model = parser.model_from_str(some_json)
```
#### Parsing a JSON file
If we have the following JSON file **data.json**...
```json
{
"name" : "textx-lang-json",
"authors" : [
"Jean-François Baget"
],
"year" : 2024,
"tested" : true
}
```
... the parser can build the model directly from the file:
```python
model = parser.model_from_file("data.json")
```
#### Visualizing the model
As for the parser, the model can be visualized.
```python
from textx.export import model_export
model_export(model, 'model.dot')
```
This file `model.dot` can also be visualized with [Graphviz](https://graphviz.org/).
### Decoding the model
The method `decode()` is called on a *model* to obtain the usual python representation of JSON strings. The test shows the interest of this representation.
```python
result = model.decode()
test = result['authors'][0] == 'Jean-François Baget' # test is True
```
Raw data
{
"_id": null,
"home_page": null,
"name": "textx-lang-json",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "one, two",
"author": null,
"author_email": "Jean-Fran\u00e7ois Baget <baget@lirmm.fr>",
"download_url": "https://files.pythonhosted.org/packages/bb/af/2150023edae8c87070fd386dbff86a6036876160b79f1f82ca7cad0a7a93/textx_lang_json-0.0.dev3.tar.gz",
"platform": null,
"description": "# textx-lang-json\r\n\r\n\r\n\r\n\r\n**textx-lang-json** is a python implementation of the JSON (JavaScript Object Notation) data interchange format [RFC8259](https://www.rfc-editor.org/rfc/rfc8259) using the [textX](https://textx.github.io/textX/) meta-language. Though it is not intended to replace the standard python JSON encoder and decoder [Lib/json](https://docs.python.org/3/library/json.html), which is much faster, it is a good alternative when you want to mix some JSON in your own textX grammar, or a good starting point should you want to develop your own JSON-like grammar.\r\n\r\nThe `textxjson` package provides a parser (basically a *textX* *metamodel*), able to build a *textx* *model* from a JSON file or string. This model can be visualized, for educational purpose, but more importantly can be *decoded* to obtain the usual (as done by [Lib/json](https://docs.python.org/3/library/json.html)) python representation of the JSON document.\r\n\r\n**textx-lang-json** has been created by Jean-Fran\u00e7ois Baget at the [Boreal](https://team.inria.fr/boreal/) team ([Inria](https://www.inria.fr/fr) and [LIRMM](https://www.lirmm.fr/)). It is part of the [textx-lang-dlgpe]() project.\r\n\r\n### Walkthrough\r\n\r\nThe following code demonstrates, in python, how to build a `parser`, generate a `model` from a python string respecting the JSON standard, and `decode` the model to obtain the usual python representation of the python string (in that case a dictionary). It also shows that `parser.model_from_str(data).decode()` returns the same python object as the standard `json.loads(data)`.\r\n\r\n```python\r\nfrom textx import metamodel_for_language\r\n\r\nparser = metamodel_for_language('textxjson') # building the parser\r\n\r\ndata = '{\"Hello\": \"World\"}' # data is a python string respecting the JSON format\r\nmodel = parser.model_from_str(data) # model is a JsonText object\r\ntextxresult = model.decode() # textxresult is a python dictionary\r\n\r\ntest1 = textxresult == {'Hello' : 'World'} # test1 is True\r\n\r\nimport json\r\n\r\njsonresult = json.loads(data) # using the standard python function to decode data\r\n\r\ntest2 = textxresult == jsonresult # test2 is True\r\n```\r\n\r\nNote that a parser can also read a JSON file:\r\n\r\n```python\r\nmodel = parser.model_from_file(\"./path/to/data.json\")\r\n\r\n```\r\n\r\n## Installation\r\n\r\n```\r\npip install textx-lang-json\r\n```\r\n\r\n### Testing\r\n\r\nYou can test that everything behaves correctly (but first you have to clone the whole repository).\r\n\r\n```\r\ngit clone https://github.com/Jean-Francois-Baget/textx-lang-json.git\r\ncd textx-lang-json\r\npython -m unittest\r\n```\r\n```\r\n..............\r\n----------------------------------------------------------------------\r\nRan 14 tests in 11.538s\r\n\r\nOK\r\n```\r\n\r\nThanks to [ArenaNet](https://www.arena.net/) whose [GW2 API](https://wiki.guildwars2.com/wiki/API:Main) provided some data used in our testbed.\r\n\r\n## Usage\r\n\r\n### Building the parser\r\n\r\nThe first thing to do is to build the Json parser. This can be done with the following code.\r\n\r\n```python\r\nfrom textx import metamodel_for_language\r\n\r\nparser = metamodel_for_language('textxjson')\r\n```\r\n\r\n#### Visualizing the grammar\r\n\r\nThis parser can be used to obtain a graphical representation of the grammar [json.tx](./src/textxjson/grammar/json.tx). For more details on textx visualization, see https://textx.github.io/textX/visualization.html.\r\n\r\n```python\r\nfrom textx.export import metamodel_export\r\n\r\nmetamodel_export(parser, 'json.dot')\r\n```\r\nThis codes generates a file `json.dot` that can be visualized with [Graphviz](https://graphviz.org/), as shown below.\r\n\r\n\r\n\r\n### Parsing JSON\r\n\r\nMost importantly, the parser can be used to generate a *model* from a python string encoding some JSON data, or directly from a JSON file.\r\n\r\n#### Parsing a python string\r\n\r\nThe parsing below is demonstrated using a python string.\r\n\r\n```python\r\nsome_json = r'''\r\n{\r\n \"name\" : \"textx-lang-json\",\r\n \"authors\" : [\r\n \"Jean-Fran\u00e7ois Baget\"\r\n ],\r\n \"year\" : 2024,\r\n \"tested\" : true\r\n}\r\n'''\r\n\r\nmodel = parser.model_from_str(some_json)\r\n```\r\n\r\n#### Parsing a JSON file\r\n\r\nIf we have the following JSON file **data.json**...\r\n\r\n```json\r\n{\r\n \"name\" : \"textx-lang-json\",\r\n \"authors\" : [\r\n \"Jean-Fran\u00e7ois Baget\"\r\n ],\r\n \"year\" : 2024,\r\n \"tested\" : true\r\n}\r\n```\r\n... the parser can build the model directly from the file:\r\n\r\n```python\r\nmodel = parser.model_from_file(\"data.json\")\r\n```\r\n\r\n#### Visualizing the model\r\n\r\nAs for the parser, the model can be visualized.\r\n\r\n```python\r\nfrom textx.export import model_export\r\n\r\nmodel_export(model, 'model.dot')\r\n```\r\nThis file `model.dot` can also be visualized with [Graphviz](https://graphviz.org/).\r\n\r\n\r\n\r\n\r\n### Decoding the model\r\n\r\nThe method `decode()` is called on a *model* to obtain the usual python representation of JSON strings. The test shows the interest of this representation.\r\n\r\n```python\r\nresult = model.decode()\r\n\r\ntest = result['authors'][0] == 'Jean-Fran\u00e7ois Baget' # test is True\r\n```\r\n\r\n\r\n\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "MIT AND (Apache-2.0 OR BSD-2-clause)",
"summary": "A textX implementation of JSON.",
"version": "0.0.dev3",
"project_urls": null,
"split_keywords": [
"one",
" two"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "26c9444757fef115ee1d8b2c18d2939264f26a1fedd9cf111c35f92cd3a9c07c",
"md5": "a54bfb0e77b4e1744011ccef86cdb829",
"sha256": "a5ee316f214aeb464a03d769c81c3f9f03fdbe8192a00e63e0ee8c59aac96e30"
},
"downloads": -1,
"filename": "textx_lang_json-0.0.dev3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a54bfb0e77b4e1744011ccef86cdb829",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 10935,
"upload_time": "2024-09-28T14:17:32",
"upload_time_iso_8601": "2024-09-28T14:17:32.733537Z",
"url": "https://files.pythonhosted.org/packages/26/c9/444757fef115ee1d8b2c18d2939264f26a1fedd9cf111c35f92cd3a9c07c/textx_lang_json-0.0.dev3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bbaf2150023edae8c87070fd386dbff86a6036876160b79f1f82ca7cad0a7a93",
"md5": "ddc2727aac0693632f478537506f37be",
"sha256": "aaa8f22059739d409af39f8206327453da13775d8abf739a5a03b2764f63d032"
},
"downloads": -1,
"filename": "textx_lang_json-0.0.dev3.tar.gz",
"has_sig": false,
"md5_digest": "ddc2727aac0693632f478537506f37be",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 11652,
"upload_time": "2024-09-28T14:17:34",
"upload_time_iso_8601": "2024-09-28T14:17:34.128961Z",
"url": "https://files.pythonhosted.org/packages/bb/af/2150023edae8c87070fd386dbff86a6036876160b79f1f82ca7cad0a7a93/textx_lang_json-0.0.dev3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-28 14:17:34",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "textx-lang-json"
}
JSON