crossplane

The crossplane command-line interface allows you to perform various operations on NGINX configuration files, such as parsing them into JSON, building them from JSON, lexing tokens, formatting, and minifying.

Available Commands:

• parse: Converts an NGINX config file into a JSON payload.
• build: Reconstructs NGINX config files from a JSON payload.
• lex: Splits a config file into a JSON array of tokens.
• format: Formats an NGINX config file (uses parse internally).
• minify: Removes whitespace from an NGINX config (uses lex internally).

usage: crossplane <command> [options]

You can install both the Command Line Interface (CLI) and the Python Module using pip. This provides access to the crossplane command and the crossplane Python package.

pip install crossplane

The crossplane build command takes a JSON file (structured according to the crossplane parse schema) and reconstructs the NGINX configuration files.

Options:

• -d PATH, --dir PATH: The base directory to build in.
• -f, --force: Overwrite existing files.
• -i NUM, --indent NUM: Number of spaces for indentation.
• -t, --tabs: Use tabs instead of spaces for indentation.
• --no-headers: Do not write header lines to the generated configs.
• --stdout: Write the resulting configs to stdout instead of files.
• -v, --verbose: Enable verbose output.

usage: crossplane build [-h] [-d PATH] [-f] [-i NUM | -t] [--no-headers] [--stdout] [-v] filename

The crossplane lex command splits an NGINX configuration file into individual tokens (removing whitespace and comments) and outputs them as a JSON array.

Options:

• -o OUT, --out OUT: Write output to a file.
• -i NUM, --indent NUM: Number of spaces to indent output.
• -n, --line-numbers: Include the line number for each token in the output.

Example (Standard):

crossplane lex /etc/nginx/nginx.conf
# Output: ["events","{","worker_connections", ...]

Example (With Line Numbers):

crossplane lex -n /etc/nginx/nginx.conf
# Output: [["events",1],["{",1],["worker_connections",2], ...]

usage: crossplane lex [-h] [-o OUT] [-i NUM] [-n] filename

Beyond the CLI, you can use crossplane as a Python module to programmatically parse, build, or lex NGINX configuration files. The module provides three primary functions: parse(), build(), and lex().

import crossplane

Crossplane provides two lightweight utilities for quick configuration adjustments:

Format (crossplane format) Uses crossplane parse internally to re-format an NGINX config file. It is intended as a demonstration tool and is not a feature-rich formatter. For advanced formatting, use the Python API.

Minify (crossplane minify) Uses crossplane lex internally to remove as much whitespace as possible from an NGINX config without changing its functionality.

Usage:

crossplane format [options] filename
crossplane minify [-o OUT] filename

The crossplane.lex() function performs lexical analysis on an NGINX configuration file. It returns a list of 2-tuples representing the tokens found in the file. This is the programmatic equivalent of the crossplane lex CLI command.

import crossplane
tokens = crossplane.lex('/etc/nginx/nginx.conf')

The crossplane.parse() function takes a path to an NGINX configuration file and returns its structure as Python dictionaries. This is the programmatic equivalent of the crossplane parse CLI command, but returns native Python types instead of a JSON string.

import crossplane
payload = crossplane.parse('/etc/nginx/nginx.conf')

The crossplane.build() function takes a list of directive dictionaries and returns a single string containing a complete NGINX configuration file.

import crossplane
config = crossplane.build(
    [{
        "directive": "events",
        "args": [],
        "block": [{
            "directive": "worker_connections",
            "args": ["1024"]
        }]
    }]
)

While the primary implementation is in Python, ports are available for other languages:

• Go: go-crossplane by @aluttik
• Ruby: crossplane by @gdanko