moo 無 Model Oriented Objects

Overview

moo is a tool for schema driven code generation.

Taxonomy

moo defines a conceptual taxonmy

schema: a data structure describing the structure of data (including schema).
model: a data structure which is valid against a schema
template: text in some target format which is marked up with directives that are parameterized in terms of a schema and provided by a valid model
codegen: an artifact generated by applying a model to a template each adhering to a schema.

Operations

moo may operate on instances of the moo taxonomy in various ways

compile: transform a model or a schema from one representation to another
imports: calculate an implicit file dependencies in the file representation of a model, schema or template
validate: determine if a model adheres to a schema
render: generate code (or other forms) by applying a model to a template

Uses

moo can be used for many things

define a unified data model with generated types in multiple languages
produce serialization methods for objects in a data model
translate from moo schema to others such as Avro, Protobuf, JSON Schema
generate "perfect" instances of complex code patterns such as finite state machines from simple models
…and more

Version

The current moo version is…

0.6.1

…as of last time this file was updated. See moo/version.py for the definitive version.

License

moo is free software and may be used under the terms described in file COPYING. These terms explicitly do NOT extend to any of your own files which may be input to or output from moo software.

Installation

moo requires Python 3.5 or newer.

moo installs in to your favorite Python environment in most of the usual ways. Some examples are given below. Due to a name conflict (this) moo is currently not distributed through PyPI.

Python environment

Here, python is assumed to be Python 3. Use whatever your favorite Python environment is to assure that. Some suggestions:

Python3 built in virtual environment

$ python3 -m venv venv
$ source venv/bin/activiate

Direnv

Install direnv and activate it in your shell, then:

$ echo "layout python3" > .envrc
$ direnv allow

See more at https://github.com/direnv/direnv

Install a release

Via a release tarball:

$ python -m pip install https://github.com/brettviren/moo/archive/0.4.1.tar.gz

Or, via git:

$ python -m pip install git+git://github.com/brettviren/moo.git@0.4.1#egg=moo

Install development

Just install:

$ python -m pip install git+git://github.com/brettviren/moo.git#egg=moo

Or, maybe you want to hack on the code:

$ git clone git@github.com:brettviren/moo.git
$ cd moo
$ pyton -m pip install -e .

Testing

moo source provides many types of tests. Below shows how to run the different types of tests and their output from last time this document was regenerated. Besides these explicit examples, regenerating moo documents runs various tests which are embedded as examples.

Shell level tests

The shell-level tests require BATS and bats-core is the recommended implementation.

bats -j 8 test

Python level tests

The Python-level tests require pytest. Note, developers should not disable warnings when running tests. For the sake of brevity in this document they are turned off as some 3rd party packages trigger noisy but currently innocuous deprecation warnings.

pytest --disable-warnings

============================= test session starts ==============================
platform linux -- Python 3.9.2, pytest-7.1.3, pluggy-1.0.0
rootdir: /home/bv/dev/moo
collected 25 items

test/test_issue11.py .                                                   [  4%]
test/test_issue13.py ....                                                [ 20%]
test/test_issue16.py ..                                                  [ 28%]
test/test_issue27.py ...                                                 [ 40%]
test/test_issue38.py .                                                   [ 44%]
test/test_moo_ogen.py .                                                  [ 48%]
test/test_moo_otypes.py .....                                            [ 68%]
test/test_moo_templates.py ..                                            [ 76%]
test/test_moo_util.py ....                                               [ 92%]
test/test_ogen_schema.py .                                               [ 96%]
test/test_validate.py .                                                  [100%]

============================== 25 passed in 0.94s ==============================

Quick start

The moo command line interface provides various commands and online help:

$ moo --help

See links below for documentation which provides various examples.

Documentation

Links

home page

https://brettviren.github.io/moo

code repo

https://github.com/brettviren/moo

documentation

moo high level documentation (this file)
moo object schema paradigm how to define schema and use it to validate models, apply models to templates for example to implement codegen
moo object types way to create objects with a valid-by-construction pattern in Python
moo object validation to strongly check if existing objects are valid against moo schema.
moo and build systems how to integrate moo codegen into various build systems
moo and top-level arguments flexible way to inject values into a Jsonnet program
moo as Wire-Cell user package generator how moo can be used to generate a skeleton of an entire software project
moo for LaTeX and spreadsheet generator using moo in production of documentation

Releases

While moo has a 0.y.z release, backward compatibility is not a strong priority as all uses are also in flux. y will increment with major new features which may or may not be backward compatible. z will increment with minor bug fixes.

Releasing

Notes to self on making a release:

edit moo/version.py to set release version
reexport this and other documentation files, no cache and check for failures
- bats/pytest runs as part of exporting this file
git commit and git tag -am 'Pithy release message' X.Y.Z using matching string
edit moo/version.py to go back to a dev version
git commit and git push and git push --tags
visit github release page and add any useful details

Etc

The name moo is a play on the Japanese term 無 which may be interpreted to English in a few ways. Some are listed below along with how the meaning reflects on aspects of moo.

Untainted pure mind: moo avoids being "opinionated", is centered on ideas expressed as abstract data structures and so can be used for a wide variety of things from generating code, documents or package skeletons. moo forms its data structures by ingesting most of the popular file formats likely to be used. And, moo can produce any file format for which a user may create a template.
No strings attached: moo is not intended to be an invasive tool. moo artifacts can be generated as desired and moo may be left behind. moo does not lock-in particular formats. moo extends this freedom to your own applications. By adopting moo codegen philosophy an app need not lock-in itself to particular data formats, representations, or serializations technologies.
Nothingness: moo is not really anything itself but rather it is the bits that go between other real things which perform the "heavy lifting" (Jsonnet, anyconfig, Jinja, JSON Schema, user templates). moo lets apps embrace the power of this nothingness by switching developer effort away from repetitive programming tasks and toward data structure and template development and then through code generation that effort gains multiplicative power.