Metadata-Version: 2.1
Name: ovid
Version: 0.6.0
Summary: Text metamorphosis toolbox'
Home-page: https://github.com/veikman/ovid
Author: Viktor Eikman
Author-email: viktor.eikman@gmail.com
License: GPL-3.0-only
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Database
Classifier: Topic :: Games/Entertainment :: Board Games
Classifier: Topic :: Games/Entertainment :: Multi-User Dungeons (MUD)
Classifier: Topic :: Games/Entertainment :: Role-Playing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Filters
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.6
Description-Content-Type: text/markdown; charset=UTF-8

## Ovid: tools for text metamorphosis

This Python package is a templating engine. It will remind you of other such
engines available for Python, such as the standard library’s string.Template,
Jinja, and the Django template system.

Ovid works by pairing up regular expressions with functions. Both are
needed to create an Ovid processor. You apply the processor to a string,
and if the regular expression matches, the function receives the content
of the matching groups from that expression. The function’s output replaces
the match.

### Examples

Here is a trivial example:

```python
from ovid.basic import OneWayProcessor

def f(group):
    return 3 * group

OneWayProcessor('(b)', f).sub('abc')  # Returns 'abbbc'
```

As you can see, the regex matches `b` and identifies it as a group, which
Ovid passes to the function we have defined. The function does not
receive the match object.

A slightly more meaningful example follows, using a different Ovid class,
through a decorator.

```python
import random
from ovid.inspecting import SignatureShorthand as SS

_BARK_STATES = ('mostly stripped', 'brown', 'gray')

@SS.register
def melee(to_hit, damage, defense=''):
    repl = f'{to_hit or "±0"} to hit with {damage or "±0"} damage.'
    if defense:
        repl += f' {defense} to be hit in melee.'
    return repl

@SS.register
def wood():
    return f'The bark is {random.choice(_BARK_STATES)}.'

sample = 'A stick. {{wood}} {{melee||+1|defense=-1}}'
SS.collective_sub(sample)  # Return value:
# 'A stick. The bark is gray. ±0 to hit with +1 damage. -1 to be hit in melee.'
```

Here, the decorator adds our two functions to a registry, and the Ovid class
constructs our regular expressions for us, with delimiters and separators that
can be customized through subclassing. We apply both processors collectively,
through a class method. Collective application supports recursion, nesting, and
the passing of additional contextual information to processors.

Finally, Ovid processors can evert, outputting suitable input.

```python
from ovid.producing import TwoWaySignatureShorthand

def hyperlink(href, text=None):
   return f'<a href="{href}">{text or href}</a>'

processor = TwoWaySignatureShorthand(hyperlink)

processor.produce('https://www.fsf.org/', text='FSF')
# Return value: '{{hyperlink|https://www.fsf.org/|text=FSF}}'

processor.sub('{{hyperlink|https://www.python.org/psf/|text=PSF}}')
# Return value: '<a href="https://www.python.org/psf/">PSF</a>'
```

In this example, an object built from one function can produce a template,
and parse such a template as in the first example.

### Use cases

Ovid grew out of [CBG](https://github.com/veikman/cbg). There, Ovid enables
shorthand expressions in the manual text input that CBG uses to make
playing cards. Because Ovid processors can evert, Ovid also combines with CBG
to generate elegant raw text specifications for larger games.

A more complicated real-world use case is the maintenance of the author’s
website. Here, Ovid refines specifications as a pre-processor to Markdown.
This makes it easy to write a blog article that references a movie review that
hasn’t been written yet. When the review is eventually added to the database,
an Ovid processor finds it and adds a hyperlink to the article’s published
form.

In the same process, the Django model instance that owns each raw string is
passed through the Ovid layer to the encapsulated functions as contextual
information, which enables these functions to map internal references in
addition to replacing substrings.

### Legal

Copyright 2015–2021 Viktor Eikman

Ovid is licensed as detailed in the accompanying file LICENSE.

# Change log
This log follows the conventions of
[keepachangelog.com](http://keepachangelog.com/). It picks up from Ovid
version 0.5.0.

## [Unreleased]
Nothing yet.

## [0.6.0] - 2021-04-17
### Removed
- Ceased to import all modules on loading `__init__.py`, for performance.

### Changed
- Modernized use of `setuptools` (via PyPA `build`) for PyPI publication.
    - Removed Debian system packaging shortcuts.
- Converted unit tests to `pytest` and ceased to distribute them.

### Added
- Flake8 configuration via `pyproject.toml`, for use with `pflake8`.

### Fixed
- Linting.

## [0.5.1] - 2020-10-24
### Changed
- Switched from `distutils.core` to `setuptools` to enable wheel distribution.
- Changed distribution name from `Ovid` to `ovid`.

[Unreleased]: https://github.com/veikman/ovid/compare/ovid-v0.6.0...HEAD
[0.6.0]: https://github.com/veikman/ovid/compare/ovid-v0.5.1...v0.6.0
[0.5.1]: https://github.com/veikman/ovid/compare/ovid-v0.5.0...v0.5.1


