# -*- coding: utf-8 -*-
from setuptools import setup

packages = \
['jinjang', 'jinjang.config']

package_data = \
{'': ['*']}

setup_kwargs = {
    'name': 'jinjang',
    'version': '0.0.0b0',
    'description': 'This project tries to ameliorate the workflow when working with the template engine Jinja',
    'long_description': 'The `Python` module `jinjaNG`\n=============================\n\n> **I beg your pardon for my english...**\n>\n> English is not my native language, so be nice if you notice misunderstandings, misspellings, or grammatical errors in my documents and codes.\n\n\nAbout `jinjaNG`\n---------------\n\nThis small project tries to ameliorate the workflow when working with the template engine [Jinja](https://palletsprojects.com/p/jinja/).\n\n  1. Structured specifications for tags to be used in a template.\n\n  1. Filler data in `JSON`, `YAML`, or `Python` files.\n\n  1. Work with either files or strings.\n\n\nWorking with files\n------------------\n\n### Our goal\n\nSuppose we want to type the following `LaTeX` code. This corresponds to a file with extension `TEX`.\n\n~~~latex\n\\documentclass{article}\n\n\\begin{document}\n\nOne example.\n\n\\begin{enumerate}\n    \\item Value nb. 1: "one".\n    \\item Value nb. 2: "two".\n    \\item Value nb. 3: "three".\n    \\item Value nb. 4: "four".\n    \\item Value nb. 5: "five".\n\\end{enumerate}\n\n\\end{document}\n~~~\n\nAs you can see, most of the content follows a repetitive logic. So it may be a good idea to automate the typing. Here is where `jinjaNG` can help us.\n\n\n### What we really type\n\nThe first thing we can do is to define the repetitive content. Let\'s use a `YAML` file (a `JSON` file can be used, but it\'s less fun to type). If we need to go further into the numbers in the `LaTeX` file, we just have to add new names to the list in the `YAML` file.\n\n~~~yaml\ntxt_exa: example\nvalues :\n  - one\n  - two\n  - three\n  - four\n  - five\n~~~\n\n\nNext, let\'s type a minimalist `LaTeX` code using special instructions and tags. Explanations are given below.\n\n~~~latex\n\\documentclass{article}\n%: if False\n\\usepackage{jnglatex}\n%: endif\n\n\\begin{document}\n\nOne \\JNGVAR{txt_exa}.\n\n\\begin{enumerate}\n%: for oneval in values\n    \\item Value nb. \\JNGVAR{loop.index}: "\\JNGVAR{oneval}".\n%: endfor\n\\end{enumerate}\n\n\\end{document}\n~~~\n\nThis is how the previous template was typed.\n\n  1. Let\'s start with the content after the `begin{document}`. With `JNGVAR{txt_exa}`, we indicate to use the value associated with the `txt_exa` variable in the `YAML` data file. In our case, `JNGVAR{txt_exa}` corresponds to `example`.\n\n  1. At the begining of the template, the lines between `%: if False` and `%: endif` will not be in the final output. Here we use `%: some Jinja instructions` with an always-false condition which causes the block to be ignored when making the final file. This allows the `jnglatex` package to be used only in the template file, but not in the final output. This package allows `jinjaNG` variables to be clearly highlighted after the `LaTeX` template is compiled: this small feature greatly simplifies template design.\n\n\n>  For now, the `jnglatex.sty` file must be in the same folder as the `LaTeX` template, or it must be installed by hand in your `LaTeX` distribution: you will find it in the `jng-extra-tools` folder.\n\n\n### Building the output via a `Python` code\n\nUsing a `Python` file, it is easy to produce the desired output. Here are the instructions to use where we assume that the `cd` command has been used beforehand, so that running the `Python` scripts is done from the folder containing our `Python`, `YAML` and `LaTeX` files.\n\n~~~python\nfrom jinjang import *\n\nmybuilder = JNGBuilder()\n\nmybuilder.render(\n    datas    = "datas.yaml",\n    template = "template.tex",\n    output   = "output.tex"\n)\n~~~\n\nThis code uses one useful default behaviour: `jinjaNG` associates automatically the `LaTeX` dialect, or flavour because the template has the extension `TEX`. The flavours available are given in the last section of this document.\n\n\n### Building the output via command lines\n\nThe commands below have the same effect as the `Python` code in the previous section.\n\n~~~\n> cd path/to/the/good/folder\n> python -m jinjang --dto datas.yaml template.tex output.tex\nFile successfully built:\n  + output.tex\n~~~\n\n\n\n### Building the data via a `Python` script\n\nIn our case, by knowing the existence of [cvnum](https://pypi.org/project/cvnum/), for example, we can be more efficient in constructing the data. Here is one possible `datas.py` file where `JNG_DATAS` is a reserved name for the data that `jinjaNG` will use. We\'ll see next that producing the final output can no longer be done using the default behaviour of an instance of the `JNGBuilder` class.\n\n~~~python\nfrom cvnum.textify import *\n\nnameof = IntName().nameof\n\nJNG_DATAS = {\n    \'txt_exa\': "example",\n    \'values\' : [nameof(x) for x in range(1, 6)]\n}\n~~~\n\n\nThe `Python` code producing the final output becomes the following one, where `pydatas = True` allows the class `JNGBuilder` to execute the `Python` file. **This choice can be dangerous with untrusted `Python` scripts!**\n\n~~~python\nfrom jinjang import *\n\nmybuilder = JNGBuilder(pydatas = True)\n\nmybuilder.render(\n    datas    = "datas.py",\n    template = "template.tex",\n    output   = "output.tex"\n)\n~~~\n\n\nTo work with a `Python`data file from the terminal, you must use the tag `--pydto` instead of `--dto`. This is because **it can be dangerous to launch a `Python` data file**, so `jinjaNG` must know that you really want to do this. The commands below have the same effect as the `Python` code above.\n\n~~~\n> cd path/to/the/good/folder\n> python -m jinjang --pydto datas.py template.tex output.tex\nWARNING: Using a Python file can be dangerous.\nFile successfully built:\n  + output.tex\n~~~\n\n\nWorking with `Python` variables\n-------------------------------\n\nTo work directly from `Python` without using any file, you need to produce a dictionary for the data, and a string for the template, so as to get a string for the final output. Let\'s take an example where the dialect, or flavour, must be specified always.\n\n~~~python\nfrom jinjang import *\n\nmydatas = {\n    \'txt_exa\': "small example",\n    \'max_i\'  : 4\n}\n\nmytemplate = """\nOne {{ txt_exa }} with automatic calculations.\n{#: for i in range(1, max_i + 1) :#}\n  {{ i }}) I count using squares: {{ i**2 }}.\n{#: endfor :#}\n""".strip()\n\nmybuilder = JNGBuilder(flavour = FLAVOUR_ASCII)\n\noutput = mybuilder.render_frompy(\n    datas    = mydatas,\n    template = mytemplate\n)\n~~~\n\n\nThe content of the string `output` will be the following one.\n\n~~~markdown\nOne small example with automatic calculations.\n\n  1) I count using squares: 1.\n\n  2) I count using squares: 4.\n\n  3) I count using squares: 9.\n\n  4) I count using squares: 16.\n\n~~~\n\n\nAll the flavours\n----------------\n\nA flavour indicates a dialect for a templates. Here are the minimalist technical descriptions of each of these flavours.\n\n\n<!-- FLAVOURS - TECH. DESC. - START -->\n\n---\n\n#### Flavour `ascii`\n\n> **Short description:** generic behaviour of `jinjaNG`.\n\n  1. **Extensions for the auto-detection, and possible tools for the templates.**\n\n      * Any extension not associated to any other flavour is associated to this flavour which is like a default one.\n\n      * No tools are available to assist in typing templates.\n\n  1. **Variables** are typed `{{ one_jinja_var }}`.\n\n  1. **Using `jinja` instructions.**\n\n      * Inline instructions are typed `#: ...` where `...` symbolizes some `Jinja` instructions.\n\n      * Block instructions are typed `{#: ... :#}` where `...` symbolizes some `Jinja` instructions, on several lines if needed.\n\n  1. **Writing comments.**\n\n      * Inline comments are typed `#_ ...` where `...` symbolizes comments only for the template.\n\n      * Block comments are typed `{#_ ... _#}` where `...` symbolizes comments only for the template, on several lines if needed.\n\n---\n\n#### Flavour `html`\n\n> **Short description:** useful settings and tools for HTML templating.\n\n  1. **Extensions for the auto-detection, and possible tools for the templates.**\n\n      * Files having extensions `HTML` are associated to this flavour.\n\n      * Tools to assist in typing templates are available: see the folder `jng-extra-tools/html`.\n\n  1. **Variables** are typed `{{ one_jinja_var }}`.\n\n  1. **Using `jinja` instructions.**\n\n      * No inline instructions are available.\n\n      * Block instructions are typed `<!--: ... :-->` where `...` symbolizes some `Jinja` instructions, on several lines if needed.\n\n  1. **Writing comments.**\n\n      * No inline comments are available.\n\n      * Block comments are typed `<!--_ ... _-->` where `...` symbolizes comments only for the template, on several lines if needed.\n\n---\n\n#### Flavour `latex`\n\n> **Short description:** useful settings and tools for LaTeX templating.\n\n  1. **Extensions for the auto-detection, and possible tools for the templates.**\n\n      * Files having extensions `TEX`, `STY`, or `TKZ` are associated to this flavour.\n\n      * Tools to assist in typing templates are available: see the folder `jng-extra-tools/latex`.\n\n  1. **Variables** are typed `\\JNGVAR{ one_jinja_var }`.\n\n  1. **Using `jinja` instructions.**\n\n      * Inline instructions are typed `%: ...` where `...` symbolizes some `Jinja` instructions.\n\n      * Block instructions are typed `%%: ... :%%` where `...` symbolizes some `Jinja` instructions, on several lines if needed.\n\n  1. **Writing comments.**\n\n      * Inline comments are typed `%_ ...` where `...` symbolizes comments only for the template.\n\n      * Block comments are typed `%%_ ... _%%` where `...` symbolizes comments only for the template, on several lines if needed.\n\n<!-- FLAVOURS - TECH. DESC. - END -->',
    'author': 'Christophe BAL',
    'author_email': 'None',
    'maintainer': 'Christophe BAL',
    'maintainer_email': 'None',
    'url': 'https://github.com/bc-tools/for-dev/tree/main/jinjaNG',
    'packages': packages,
    'package_data': package_data,
    'python_requires': '>=3.9,<4.0',
}


setup(**setup_kwargs)
