Skip to content

Commit 37d0867

Browse files
rrthomasrrthomas
committed
Rework the way external commands are called
Rather than simply run, rather than read, a file found to be executable, add new “external arguments”. Both `$paste` and `$include` can now have regular and/or external arguments. When external arguments are provided, they specify a program and command-line arguments to run. The program is looked up as before, so it can be found via the include mechanism, or on PATH. When an input is provided, feed it to the program on standard input. As before, the command expands to the program’s standard output.
1 parent 1376501 commit 37d0867

File tree

24 files changed

+216
-156
lines changed

24 files changed

+216
-156
lines changed

‎Cookbook.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ The basic page template looks something like this:
3535
<!DOCTYPE html>
3636
<html>
3737
<head>
38-
<link rel="stylesheet" type="text/css" href="$paste{path-to-root.in.sh,$path}/style.css">
38+
<link rel="stylesheet" type="text/css" href="$paste(path-to-root.in.sh,$path)/style.css">
3939
<title>$include{title.in.txt}</title>
4040
</head>
4141
<body>
@@ -163,7 +163,7 @@ Page contents.
163163
164164
--
165165
166-
Last updated: $paste{python,-c,import datetime; print(datetime.now().strftime('%Y-%m-%d'))}
166+
Last updated: $paste(python,-c,import datetime; print(datetime.now().strftime('%Y-%m-%d')))
167167
```
168168

169169
This gives a result looking something like:
@@ -194,11 +194,11 @@ This can be done conveniently with environment variables, by invoking Nancy as f
194194
env VARIABLE1=value1 VARIABLE2=value2 … nancy …
195195
```
196196

197-
Then, you can use `$include{printenv,VARIABLE1}` (or the equivalent in Python or other languages) in the template files. [python-project-template](https://github.com/rrthomas/python-project-template) uses this technique to generate skeleton Python projects.
197+
Then, you can use `$include(printenv,VARIABLE1)` (or the equivalent in Python or other languages) in the template files. [python-project-template](https://github.com/rrthomas/python-project-template) uses this technique to generate skeleton Python projects.
198198

199199
## Adding code examples and command output to Markdown
200200

201-
Source code examples can be added inline as normal in Markdown [code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks), but it’s often more convenient to include code directly from a source file. This can be done directly with `$paste`, or you can use the `cat` command to include a file that is not in the Nancy input tree: `$paste{cat,/path/to/source.js}`.
201+
Source code examples can be added inline as normal in Markdown [code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks), but it’s often more convenient to include code directly from a source file. This can be done directly with `$paste`, or you can use the `cat` command to include a file that is not in the Nancy input tree: `$paste(cat,/path/to/source.js)`.
202202

203203
The output of commands can similarly be included in documents. The output of terminal commands may be better included in a code block, to preserve formatting that depends on a fixed-width font.
204204

@@ -219,5 +219,5 @@ zip -r archive.zip .
219219
Assuming it is called `make-zip.in.sh`, it can be used thus, from a file called `make-zip.in.nancy`:
220220

221221
```
222-
$paste{make-zip.in.sh,\$outputpath}
222+
$paste(make-zip.in.sh,\$outputpath)
223223
```

‎Cookbook.nancy.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -21,32 +21,32 @@ Suppose further that the web site has the following structure, where each line c
2121

2222
```
2323
├── Home page
24-
$paste{sh,-c,build-aux/dirtree tests/test-files/cookbook-example-website-expected | sed -e 's/\.html//g' | grep -v index | grep -v \\.}
24+
$paste(sh,-c,build-aux/dirtree tests/test-files/cookbook-example-website-expected | sed -e 's/\.html//g' | grep -v index | grep -v \\.)
2525
```
2626

2727
The basic page template looks something like this:
2828

2929
```
30-
$paste{cat,tests/test-files/cookbook-example-website-src/template.in.html}
30+
$paste(cat,tests/test-files/cookbook-example-website-src/template.in.html)
3131
```
3232

3333
Making the menu an included file is not strictly necessary, but makes the template easier to read. The pages will be laid out as follows:
3434

3535
```
36-
$paste{build-aux/dirtree,tests/test-files/cookbook-example-website-expected}
36+
$paste(build-aux/dirtree,tests/test-files/cookbook-example-website-expected)
3737
```
3838

3939
The corresponding source files are laid out as follows. This may look a little confusing at first, but note the similarity to the HTML pages, and hold on for the explanation!
4040

4141
```
42-
$paste{build-aux/dirtree,tests/test-files/cookbook-example-website-src}
42+
$paste(build-aux/dirtree,tests/test-files/cookbook-example-website-src)
4343
```
4444

4545
Note that there is only one menu fragment (the main menu is the same for every page), while each section has its own breadcrumb trail (`breadcrumb.in.html`), and each page has its own content (`main.in.html`).
4646

47-
Now consider how Nancy builds the page whose URL is `Places/Vladivostok/index.html`. Assume the source files are in the directory `source`. This page is built from `source/Places/Vladivostok/index.nancy.html`, whose contents is `$paste{cat,tests/test-files/cookbook-example-website-src/Places/Vladivostok/index.nancy.html}`. According to the rules given in the [Operation](README.md#operation) section of the manual, Nancy will look first for files in `source/Places/Vladivostok`, then in `source/places`, and finally in `source`. Hence, the actual list of files used to assemble the page is:
47+
Now consider how Nancy builds the page whose URL is `Places/Vladivostok/index.html`. Assume the source files are in the directory `source`. This page is built from `source/Places/Vladivostok/index.nancy.html`, whose contents is `$paste(cat,tests/test-files/cookbook-example-website-src/Places/Vladivostok/index.nancy.html)`. According to the rules given in the [Operation](README.md#operation) section of the manual, Nancy will look first for files in `source/Places/Vladivostok`, then in `source/places`, and finally in `source`. Hence, the actual list of files used to assemble the page is:
4848

49-
$paste{env,NANCY_TMPDIR=/tmp/cookbook-dest.$$,sh,-c,rm -rf ${NANCY_TMPDIR} && DEBUG="*" PYTHONPATH=. python -m nancy --path Places/Vladivostok tests/test-files/cookbook-example-website-src ${NANCY_TMPDIR} 2>&1 | grep Found | cut -d " " -f 4 | sort | uniq | sed -e 's|^'\''tests/test-files/cookbook-example-website-src\(.*\)'\''$|* `source\1`|' && rm -rf ${NANCY_TMPDIR}}
49+
$paste(env,NANCY_TMPDIR=/tmp/cookbook-dest.$$,sh,-c,rm -rf ${NANCY_TMPDIR} && DEBUG="*" PYTHONPATH=. python -m nancy --path Places/Vladivostok tests/test-files/cookbook-example-website-src ${NANCY_TMPDIR} 2>&1 | grep Found | cut -d " " -f 4 | sort | uniq | sed -e 's|^'\''tests/test-files/cookbook-example-website-src\(.*\)'\''$|* `source\1`|' && rm -rf ${NANCY_TMPDIR})
5050

5151
For the site’s index page, the file `index/logo.in.html` will be used for the logo fragment, which can refer to the larger graphic desired.
5252

@@ -74,13 +74,13 @@ Given a simple page template, a datestamp can be added by using the `date`
7474
command with `\$paste`:
7575

7676
```
77-
$paste{sh,-c,sed -e 's|datetime(2016\\\,10\\\,12)|now()|' < tests/test-files/page-template-with-date-src/Page.nancy.md}
77+
$paste(sh,-c,sed -e 's|datetime(2016\\\,10\\\,12)|now()|' < tests/test-files/page-template-with-date-src/Page.nancy.md)
7878
```
7979

8080
This gives a result looking something like:
8181

8282
```
83-
$include{cat,tests/test-files/page-template-with-date-src/Page.nancy.md}
83+
$include(cat,tests/test-files/page-template-with-date-src/Page.nancy.md)
8484
```
8585

8686
## Dynamically naming output files and directories according
@@ -99,11 +99,11 @@ This can be done conveniently with environment variables, by invoking Nancy as f
9999
env VARIABLE1=value1 VARIABLE2=value2 … nancy …
100100
```
101101

102-
Then, you can use `\$include{printenv,VARIABLE1}` (or the equivalent in Python or other languages) in the template files. [python-project-template](https://github.com/rrthomas/python-project-template) uses this technique to generate skeleton Python projects.
102+
Then, you can use `\$include(printenv,VARIABLE1)` (or the equivalent in Python or other languages) in the template files. [python-project-template](https://github.com/rrthomas/python-project-template) uses this technique to generate skeleton Python projects.
103103

104104
## Adding code examples and command output to Markdown
105105

106-
Source code examples can be added inline as normal in Markdown [code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks), but it’s often more convenient to include code directly from a source file. This can be done directly with `\$paste`, or you can use the `cat` command to include a file that is not in the Nancy input tree: `\$paste{cat,/path/to/source.js}`.
106+
Source code examples can be added inline as normal in Markdown [code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks), but it’s often more convenient to include code directly from a source file. This can be done directly with `\$paste`, or you can use the `cat` command to include a file that is not in the Nancy input tree: `\$paste(cat,/path/to/source.js)`.
107107

108108
The output of commands can similarly be included in documents. The output of terminal commands may be better included in a code block, to preserve formatting that depends on a fixed-width font.
109109

@@ -124,5 +124,5 @@ zip -r archive.zip .
124124
Assuming it is called `make-zip.in.sh`, it can be used thus, from a file called `make-zip.in.nancy`:
125125

126126
```
127-
\$paste{make-zip.in.sh,\$outputpath}
127+
\$paste(make-zip.in.sh,\$outputpath)
128128
```

‎README.md‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,11 @@ Nancy expands a template file as follows:
114114
each command, and replace the command by the result.
115115
2. Output the result.
116116

117-
A command takes the form `$COMMAND` or `$COMMAND{ARGUMENT, ...}`.
117+
A command is written as its name prefixed with a dollar sign: `$COMMAND`.
118+
Some commands take an argument, given in braces: `$COMMAND{ARGUMENT}`.
119+
Finally, some commands also take an optional external command and arguments:
120+
`$COMMAND(EXTERNAL-COMMAND, ARGUMENT, …){ARGUMENT}`; the argument in braces
121+
is optional in this case.
118122

119123
Nancy treats its input as 8-bit ASCII, but command names and other
120124
punctuation only use the 7-bit subset. This means that any text encoding
@@ -167,27 +171,24 @@ worked example.
167171
### Running other programs
168172

169173
In addition to the rules given above, Nancy also allows `$include` and
170-
`$paste` to take their input from programs. This can be useful in a variety
171-
of ways: to insert the current date or time, to make a calculation, or to
172-
convert a file to a different format.
174+
`$paste` to run external programs, whose output becomes the result of the
175+
command. If an input is given, it is supplied to the program’s standard
176+
input. This can be useful in a variety of ways: to insert the current date
177+
or time, to make a calculation, or to convert a file to a different format.
173178

174-
Nancy can run a program in two ways:
179+
Nancy looks for programs in two ways:
175180

176-
1. If a file found by an `$include` or `$paste` command has the “execute”
177-
permission, it is run.
181+
1. Using the same rules as for finding an `$include` or `$paste` input,
182+
Nancy looks for a file which has the “execute” permission.
178183

179184
2. If no file of the given name can be found using the rules in the previous
180185
section, Nancy looks for an executable file on the user’s `PATH` (the
181-
list of directories specified by the `PATH` environment variable). If one
182-
is found, it is run.
183-
184-
In either case, arguments may be passed to the program: use
185-
`$include{FILE,ARGUMENT_1,ARGUMENT_2,…}`, or the equivalent for `$paste`.
186+
list of directories specified by the `PATH` environment variable).
186187

187188
For example, to insert the current date:
188189

189190
```
190-
$paste{date,+%Y-%m-%d}
191+
$paste(date,+%Y-%m-%d)
191192
```
192193

193194
See the [date example](Cookbook.md#date-example) in the Cookbook for more
@@ -203,14 +204,13 @@ To prevent a comma from being interpreted as an argument separator, put a
203204
backslash in front of it:
204205

205206
```
206-
$include{cat,I\, Robot.txt,3 Rules of Robotics.txt}
207+
$include(cat,I\, Robot.txt,3 Rules of Robotics.txt)
207208
```
208209

209-
This will run the `$include` command with the following arguments:
210+
This will run the `cat` command with the following arguments:
210211

211-
1. `cat`
212-
2. `I, Robot.txt`
213-
3. `3 Rules of Robotics.txt`
212+
1. `I, Robot.txt`
213+
2. `3 Rules of Robotics.txt`
214214

215215
Note that the filenames supplied to `cat` refer not to the input tree, but
216216
to the file system.

‎README.nancy.md‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
![logo](logo/nancy-small.png) _logo by Silvia Polverini_
44

5-
$paste{/bin/sh,-c,PYTHONPATH=. python -m nancy --version | tail +2 | head -2 | sed -e 's/$/ /'}
5+
$paste(/bin/sh,-c,PYTHONPATH=. python -m nancy --version | tail +2 | head -2 | sed -e 's/$/ /')
66

77
Nancy is a simple templating system that copies a file or directory, filling
88
in templates as it goes. It has just one non-trivial construct:
@@ -35,7 +35,7 @@ $ pip install nancy
3535
## Invocation
3636

3737
```
38-
$paste{/bin/sh,-c,PYTHONPATH=. python -m nancy --help | sed -e 's/usage: nancy/nancy/'}
38+
$paste(/bin/sh,-c,PYTHONPATH=. python -m nancy --help | sed -e 's/usage: nancy/nancy/')
3939
```
4040

4141
## Operation <a name="operation"></a>
@@ -99,7 +99,11 @@ Nancy expands a template file as follows:
9999
each command, and replace the command by the result.
100100
2. Output the result.
101101

102-
A command takes the form `\$COMMAND` or `\$COMMAND{ARGUMENT, ...}`.
102+
A command is written as its name prefixed with a dollar sign: `\$COMMAND`.
103+
Some commands take an argument, given in braces: `\$COMMAND{ARGUMENT}`.
104+
Finally, some commands also take an optional external command and arguments:
105+
`\$COMMAND(EXTERNAL-COMMAND, ARGUMENT, …){ARGUMENT}`; the argument in braces
106+
is optional in this case.
103107

104108
Nancy treats its input as 8-bit ASCII, but command names and other
105109
punctuation only use the 7-bit subset. This means that any text encoding
@@ -152,27 +156,24 @@ worked example.
152156
### Running other programs
153157

154158
In addition to the rules given above, Nancy also allows `\$include` and
155-
`\$paste` to take their input from programs. This can be useful in a variety
156-
of ways: to insert the current date or time, to make a calculation, or to
157-
convert a file to a different format.
159+
`\$paste` to run external programs, whose output becomes the result of the
160+
command. If an input is given, it is supplied to the program’s standard
161+
input. This can be useful in a variety of ways: to insert the current date
162+
or time, to make a calculation, or to convert a file to a different format.
158163

159-
Nancy can run a program in two ways:
164+
Nancy looks for programs in two ways:
160165

161-
1. If a file found by an `\$include` or `\$paste` command has the “execute”
162-
permission, it is run.
166+
1. Using the same rules as for finding an `\$include` or `\$paste` input,
167+
Nancy looks for a file which has the “execute” permission.
163168

164169
2. If no file of the given name can be found using the rules in the previous
165170
section, Nancy looks for an executable file on the user’s `PATH` (the
166-
list of directories specified by the `PATH` environment variable). If one
167-
is found, it is run.
168-
169-
In either case, arguments may be passed to the program: use
170-
`\$include{FILE,ARGUMENT_1,ARGUMENT_2,…}`, or the equivalent for `\$paste`.
171+
list of directories specified by the `PATH` environment variable).
171172

172173
For example, to insert the current date:
173174

174175
```
175-
\$paste{date,+%Y-%m-%d}
176+
\$paste(date,+%Y-%m-%d)
176177
```
177178

178179
See the [date example](Cookbook.md#date-example) in the Cookbook for more
@@ -188,14 +189,13 @@ To prevent a comma from being interpreted as an argument separator, put a
188189
backslash in front of it:
189190

190191
```
191-
\$include{cat,I\, Robot.txt,3 Rules of Robotics.txt}
192+
\$include(cat,I\, Robot.txt,3 Rules of Robotics.txt)
192193
```
193194

194-
This will run the `\$include` command with the following arguments:
195+
This will run the `cat` command with the following arguments:
195196

196-
1. `cat`
197-
2. `I, Robot.txt`
198-
3. `3 Rules of Robotics.txt`
197+
1. `I, Robot.txt`
198+
2. `3 Rules of Robotics.txt`
199199

200200
Note that the filenames supplied to `cat` refer not to the input tree, but
201201
to the file system.

0 commit comments

Comments
 (0)