Update README

This commit is contained in:
dana 2018-06-02 01:42:26 -05:00
parent aa45391808
commit 33e945b4bc
1 changed files with 180 additions and 46 deletions

226
README.md
View File

@ -5,99 +5,201 @@
for interacting with Twig through shell scripts and other command-line
applications.
## Usage overview
```
Usage:
twigc [options] [--] [<template>]
Arguments:
template Twig template file to render (use `-` for STDIN)
Options:
-h, --help Display this usage help
-V, --version Display version information
--credits Display dependency credits (including Twig version)
-d, --dir=DIR Add search directory to loader (multiple values allowed)
--env Treat environment variables as input data
-e, --escape=ESCAPE Set autoescape environment option
-j, --json=JSON Pass variables as JSON (dictionary string or file path)
-p, --pair=PAIR Pass variable as key=value pair (multiple values allowed)
--query=QUERY Pass variables as URL query string
-s, --strict Enable strict_variables environment option
```
## Usage
**twigc** can render Twig templates supplied via either standard input or a file
path. Input data can be passed to the template using a simple key=value syntax:
path.
```
Usage: twigc [options] [<template>]
Options:
-h, --help Display this usage help and exit
-V, --version Display version information and exit
--credits Display dependency information and exit
--cache <dir> Enable caching to specified directory
-d, --dir <dir> Add specified search directory to loader
-e, --escape <strategy> Specify default auto-escaping strategy
-E, --env Derive input data from environment
-j, --json <dict/file> Derive input data from specified JSON file or
dictionary string
-p, --pair <input> Derive input data from specified key=value pair
--query <input> Derive input data from specified URL query string
-s, --strict Throw exception when undefined variable is referenced
```
### Passing input data
Input data can be passed to the template using a simple key=value syntax with
`-p`:
```
% twigc -p 'name=dana' <<< 'Hello, {{ name }}!'
Hello, dana!
```
Of course, only simple string values can be provided this way. For more complex
data, you can use the JSON option:
Of course, only basic string values can be provided this way. For more complex
data, you can use the JSON option `-j`:
```
% twigc -j '{ "numbers": [1, 2, 3] }' <<< '{{ numbers|join("... ") }}!'
% twigc -j '{"numbers": [1, 2, 3]}' <<< '{{ numbers|join("... ") }}!'
1... 2... 3!
```
JSON data can also be provided by file path or on standard input:
```
# JSON from file, template from standard input
% cat numbers.json
{ "numbers": [1, 2, 3] }
{"numbers": [1, 2, 3]}
% twigc -j numbers.json <<< '{{ numbers|join("... ") }}!'
1... 2... 3!
# JSON from standard input, template from file
% cat numbers.twig
{{ numbers|join("... ") }}!
% twigc -j - numbers.twig <<< '{ "numbers": [1, 2, 3] }'
% twigc -j - numbers.twig <<< '{"numbers": [1, 2, 3]}'
1... 2... 3!
```
(**twigc** determines whether the argument to `-j` is a dictionary string or a
file name based on whether the first character is a `{`; if you have a file name
that looks like that, use the absolute path or put `./` in front of it — for
example, `twigc -j './{myfile}.json'`.)
If
[`variables_order`](http://php.net/manual/en/ini.core.php#ini.variables-order)
is configured appropriately in your `php.ini`, you can use the `-E` option to
inherit input data from the environment:
```
% NAME=dana twigc -E <<< 'Hello, {{ NAME }}!'
Hello, dana!
```
(If you *don't* have `E` in `variables_order`, you'll get an error.)
Lastly, there's a `--query` option in case you want to pass input as a URL query
string:
```
% twigc --query '?foo=&name=dana&bar=' <<< 'Hello, {{ name }}!'
Hello, dana!
```
All of the aforementioned input options can be given multiple times and in any
combination, but the values associated with each input type override other
values with the same name using the following order of precedence (from lowest
to highest): environment, query, JSON, pair. In other words:
```
# Pair has higher precedence than environment
% name=foo twigc -p name=bar -E <<< '{{ name }} wins'
bar wins
# JSON has higher precedence than query
% twigc -j '{"name": "foo"}' --query name=bar <<< '{{ name }} wins'
foo wins
# Inputs of the same type have equal precedence and are taken in the order given
% twigc -j '{"name": "foo"}' -p name=bar -p name=baz <<< '{{ name }} wins'
baz wins
```
### Configuring auto-escaping
Normally, input data is [auto-escaped](http://twig.sensiolabs.org/doc/api.html)
based on the template file extension (or disabled by default if using standard
input), but this is configurable:
during rendering based on the template file extension (or disabled by default if
using standard input), but this is configurable:
```
# No auto-escaping by default on standard input
% twigc -p 'html=<p>Hello!</p>' <<< '{{ html }}'
<p>Hello!</p>
% twigc -p 'html=<p>Hello!</p>' -e 'html' <<< '{{ html }}'
# Explicit HTML auto-escaping
% twigc -e html -p 'html=<p>Hello!</p>' <<< '{{ html }}'
&lt;p&gt;Hello!&lt;/p&gt;
% twigc -p 'html=<p>Hello!</p>' -e 'js' <<< '{{ html }}'
# Explicit JavaScript auto-escaping
% twigc -e js -p 'html=<p>Hello!</p>' <<< '{{ html }}'
\x3Cp\x3EHello\x21\x3C\x2Fp\x3E
% twigc -p 'html=<p>Hello!</p>' -e 'url' <<< '{{ html }}'
# Explicit URL auto-escaping
% twigc -e url -p 'html=<p>Hello!</p>' <<< '{{ html }}'
%3Cp%3EHello%21%3C%2Fp%3E
```
Of course, you can always control escaping from within the template using the
[`escape`](https://twig.symfony.com/doc/2.x/filters/escape.html) filter.
The following auto-escape methods are available:
* **`none`** (aka **`false`**, **`no`**, **`never`**, &c.) —
No escaping is performed; the input is rendered as-is. This is the default for
templates taken from standard input and for files with unrecognised
extensions.
* **`html`** (aka **`true`**, **`yes`**, **`always`**, &c.) —
Ampersand-escaping as suitable for inclusion in an HTML body. This is the most
common escaping method used for rendering Web pages with Twig, and the default
method used by the `escape` filter.
* **`css`** —
Hex-escaping as suitable for inclusion in a CSS value or identifier.
* **`html_attr`** —
Ampersand-escaping as suitable for inclusion in an HTML attribute value. This
is similar to the `html` method, but more characters are escaped.
* **`js`** —
Hex-escaping as suitable for inclusion in a JavaScript string or identifier.
* **`json`** —
Serialisation according to JSON rules. Strings are quoted and escaped,
integers are left bare, &c. JSON escaping can often be used to produce strings
for config files and even languages like C (though incompatibilities do exist
 be careful).
* **`sh`** —
Double-quoting and meta-character escaping according to shell rules. This
method uses double-quoted strings rather than the single-quote method used by
e.g. `escapeshellarg()` because it is more compatible with software that
supports only a sub-set of the shell's string syntax (such as 'dotenv'
libraries).
* **`url`** —
Percent-escaping as suitable for inclusion in a URL path segment or query
parameter.
### Enabling strict mode
By default, references in the template to undefined variables are silently
ignored; you can make Twig return an error instead:
ignored, but you can make Twig throw an exception with the `-s` option:
```
% twigc <<< 'Hello, {{ name }}!'
Hello, !
% twigc -s <<< 'Hello, {{ name }}!'
[Twig_Error_Runtime]
Variable "name" does not exist in "-" at line 1
twigc: Variable "name" does not exist in "-" at line 1.
```
If a template file name was provided, the file's parent directory is used for
Twig's include search path; if standard input was used, no search path is set at
all by default. In either case, one or more additional search paths can be
explicitly supplied on the command line:
Use of this option is recommended for reliability in scripting scenarios.
### Specifying search directories
If a template file name was provided, the file's parent directory is
automatically added as an include search path; if standard input was used, no
search path is set at all by default. In either case, one or more additional
search paths can be explicitly supplied on the command line:
```
% cat include.twig
Hello!
% twigc <<< '{% include "include.twig" %}'
[Twig_Error_Loader]
Template "include.twig" is not defined in "-" at line 1.
twigc: Template "include.twig" is not defined in "-" at line 1.
% twigc -d '.' <<< '{% include "include.twig" %}'
Hello!
@ -108,7 +210,7 @@ Hello!
**twigc** is provided as a self-contained executable archive; to download it,
see the [releases](https://github.com/okdana/twigc/releases) page.
Of course, you can also build and install it from source:
Of course, you can also build it from source:
```
% git clone https://github.com/okdana/twigc
@ -118,12 +220,40 @@ Of course, you can also build and install it from source:
## Requirements
The **twigc** executable is bundled with Twig and all of its other dependencies;
the only thing you need to run it is PHP version 5.5 or higher.
The **twigc** executable archive is bundled with Twig and all of its other
dependencies; the only thing you need to run it is PHP version 7.0 or higher.
## Limitations, todos, requests
Earlier versions of this tool were implemented in the manner of a Symfony
Console application. I like Symfony components a lot, but the way Console
handles arguments in particular leaves a great deal to be desired if you're
trying to create something that works like a traditional UNIX CLI tool — the API
is confused, the functionality is limited, and worst of all it's buggy. I ended
up switching out the Console application/command/input components for a lazier
and uglier, but ultimately better-behaved, design incorporating the GetOpt.php
library.
If you have any ideas as to how to improve on this situation, please let me
know.
I'd also like to achieve the following goals at some point:
* Add to Packagist
* Improve unit/integration tests
* Create man page
* Create zsh completion function
In the longer term, if i get really bored, maybe i'll add more input and escape
methods. One thing that occurred to me is a custom escape option that takes an
arbitrary escape character and a mask of characters to be escaped with it. For
example, `-e 'custom:%:%'` might escape `printf(3)` format strings. idk
Anyway, if you find a bug or have a request, please let me know.
## Licence and acknowledgements
**twigc** is available under the MIT licence. For information about the licences
**twigc** itself is available under the MIT licence. For information about the licences
of its dependencies, run `twigc --credits`.
The `\Dana\Twigc\PharCompiler` class used to build the executable archive is
@ -134,17 +264,21 @@ based on
* [twigphp/Twig](https://github.com/twigphp/Twig) —
The Twig project on GitHub.
* [farazdagi/twig-cli](https://github.com/farazdagi/twig-cli) —
Another project that aims to bring Twig to the command line. It's actually
quite similar in design (though no code is shared); it just didn't have the
features i wanted.
features i wanted and isn't actively developed.
* [twigjs/twig.js](https://github.com/twigjs/twig.js) —
A pure JavaScript implementation of Twig. It comes with its own command-line
tool, `twigjs`, which can be used to render Twig templates, but it's quite
limited.
* [indigojs/twig-cli](https://github.com/indigojs/twig-cli) —
Another command-line Twig renderer based on Twig.js. Its functionality is very
similar to (almost exactly the same as?) `twigjs`.
* [mattrobenolt/jinja2-cli](https://github.com/mattrobenolt/jinja2-cli) —
A command-line [Jinja2](http://jinja.pocoo.org/) renderer. Very comparable to
**twigc** in terms of features.