mirror of https://github.com/okdana/twigc.git
Update README
This commit is contained in:
parent
aa45391808
commit
33e945b4bc
226
README.md
226
README.md
|
@ -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 }}'
|
||||
<p>Hello!</p>
|
||||
|
||||
% 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.
|
||||
|
|
Loading…
Reference in New Issue