Metadata-Version: 2.1
Name: dollar-templates
Version: 1.0.1
Summary: Pandoc style dollar templates for python
Home-page: https://github.com/seifferth/dollar_templates
Author: Frank Seifferth
Author-email: frankseifferth@posteo.net
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Pandoc style dollar templates for python

A slim reimplementation of pandoc's templating engine
in python. This allows you to use pandoc-style templates
(cf. <https://pandoc.org/MANUAL.html#template-syntax>) in any python
project, even if you do not want to use pandoc itself.

While this project aims to follow the template syntax described in
the pandoc documentation, it is a completely separate project and may
therefore behave differently than pandoc in certain situations. Especially
edge cases are not particularly well tested (yet). Also note that, as
of now, not all features found in pandoc's templating engine have been
implemented (see below). If you notice differences between pandoc and
`dollar_templates` concerning features that have been implemented,
feel free to submit a bug report or even a pull request.

## Installing

This repository uses python setuptools and can be installed with pip.
To install dollar_templates into the current user's home directory, for
instance, you can simply invoke `pip install --user .`. Also note that
a stable version of this python module is available at pypi. To install
the stable version, simply run `pip install --user dollar-templates`.

## Usage

The easiest way to expand a template with some data is to use the
`apply_template` function:

```python
from dollar_templates import apply_template

template = "$for(var)$- $var$\n$endfor$"
metadata = {"var": [1,2,3]}

print(apply_template(template, metadata))
```

To parse the template once and apply it multiple times to different
data, use the `parse_template` function that returns an object of
type `dollar_templates.Template`.

```python
from dollar_templates import parse_template

template = "$for(var)$- $var$\n$endfor$"
metadata_a = {"var": [1,2,3]}
metadata_b = {"var": [11,12,13]}

t = parse_template(template)
print(t.apply(metadata_a))
print(t.apply(metadata_b))
```

## Unit tests

Unit tests are implemented in `test_all.py` and can be executed with
[pytest](https://pytest.org). Simply install pytest and then execute
the `pytest` command in this directory without arguments.

## Implementation state

Pandoc lists the following features of its templating engine
(cf. <https://pandoc.org/MANUAL.html#template-syntax>):

- [x] Comments
- [x] Delimiters
- [x] Interpolated variables
- [x] Conditionals
- [x] For loops
- [ ] Partials
- [ ] Nesting
- [ ] Breakable spaces
- [ ] Pipes

The list above shows which ones have been implemented in dollar_templates.
The missing ones might or might not follow in the future.

## License

All files in this repository are made available under the terms of the
GNU General Purpose License, version 3 or later. A copy of that license
is included in the repository as `license.txt`.
