protein-lang 0.6.0

Protein: a macro language for data composition and templating

Protein, a Data Composer and Templating Tool

Problem

Nowadays, a lot of software is piloted by data files, typically JSON or YAML files.

JSON and YAML are excellent file formats but they are essentially static. Sometimes, the content of a file must change according to circumstances (typically when the environment changes or when you have different configuratons for test or production, etc.).

Manually maintaining different versions with the same boiler-plate data can be time-consuming and error-prone.

Introducing Protein

What if we had a way to generate a new data file (or more than one) according to a single set of source data?

The purpose of Protein is to help programmers prepare data files in various formats, (JSON, YAML, but also HTML, etc.) with rules that produce your data according to source data.

It extends standard YAML with constructs for variable declaration, conditionals, iteration, functions, importing and exporting YAML files, and importing Python modules.

YAMLpp is a macro language, since it manipulates the YAML tree on which it resides.

Here is a simple example:

YAMLpp:

.local:
  name: "Alice"

message: "Hello, {{ name }}!"

Output:

message: "Hello, Alice!"

General principles

The language is composed of constructs, which are denoted keys starting with a dot (.), such as .local, .if, .switch, etc.

The YAMLpp preprocessor uses these constructs modify the tree, and the constructs disappear.

The result is pure YAML.

Protein obeys the rules of YAML syntax:

• It provides declarative constructs without breaking YAML syntax.
• It allows modular, reusable, and expressive constructs that create YAML files

🚀 Quickstart

Installation

pip install protein-lang

Command-line usage

protein input.yaml -o output.yaml

• input.yaml → your YAML file with YAMLpp directives
• output.yaml → the fully expanded YAML after preprocessing

To consult the help:

protein --help

🔧 A Sample of Protein Constructs

Construct	Purpose	Minimal Example
.local	Define local variables valid for siblings and descendants.	.local: name: "Alice" message: "Hello {{ name }}"
.do	Execute a sequence or map of instructions.	.do: - step: "Init" - step: "Run"
.foreach	Iterate over values with a loop body.	.local: items: [1,2] .foreach: .values: [x, items] .do: - val: "{{ x }}"
.switch	Branch to a different node based on an expression and cases.	.switch: .expr: "{{ color }}" .cases: red: {msg: "Stop"} .default: {msg: "?"}
.if	Conditional node creation with then and else.	.if: .cond: "{{ x>0 }}" .then: {res: "Pos"} .else: {res: "Neg"}
.load	Insert and preprocess another YAMLpp (or YAML) file.	.import_module: "other.yaml"
.function	Define a reusable block with arguments and a body.	.function: .name: "greet" .args: ["n"] .do: - msg: "Hi {{ n }}"
.call	Invoke a previously defined function with arguments.	.call: .name: "greet" .args: ["Bob"]
.import_module	Import a Python module exposing functions, filters, and variables.	.module: "module.py"
.export	Export a portion of the tree into an external file.	.export: .filename: "out.yaml" .do: - foo: "bar"