Skip to content

Commit 09d651d

Browse files
rrthomasrrthomas
committed
Rejig Nancy’s command set, in particular how it runs programs
Have a separate $run command, rather than allowing $include and $paste to take external arguments. Add $expand to allow the output of $run to be expanded.
1 parent 29e9a0b commit 09d651d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

51 files changed

+230
-238
lines changed

‎Cookbook.md‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -35,17 +35,17 @@ 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">
39-
<title>$include{title.in.txt}</title>
38+
<link rel="stylesheet" type="text/css" href="$run(path-to-root.in.sh,$path)/style.css">
39+
<title>$include(title.in.txt)</title>
4040
</head>
4141
<body>
4242
<div class="wrapper">
43-
<div class="logo">$include{logo.in.html}</div>
44-
<div class="breadcrumb.in"><div class="breadcrumb-content">$include{breadcrumb.in.html}</div></div>
43+
<div class="logo">$include(logo.in.html)</div>
44+
<div class="breadcrumb.in"><div class="breadcrumb-content">$include(breadcrumb.in.html)</div></div>
4545
</div>
4646
<div class="wrapper">
47-
<div class="menu">$include{menu.in.html}</div>
48-
<div class="main">$include{main.in.html}</div>
47+
<div class="menu">$include(menu.in.html)</div>
48+
<div class="main">$include(main.in.html)</div>
4949
</div>
5050
</body>
5151
</html>
@@ -127,7 +127,7 @@ The corresponding source files are laid out as follows. This may look a little c
127127

128128
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`).
129129

130-
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 `$include{template.in.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:
130+
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 `$include(template.in.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:
131131

132132

133133

@@ -136,7 +136,7 @@ For the site’s index page, the file `index/logo.in.html` will be used for the
136136
The `breadcrumb.in.html` fragments, except for the top-level one, contain the command
137137

138138
```
139-
$include{breadcrumb.in.html}
139+
$include(breadcrumb.in.html)
140140
```
141141

142142
When expanding `source/Places/breadcrumb.in.html`, Nancy ignores that file, since it is already expanding it, and goes straight to `source/breadcrumb.in.html`. This means that the breadcrumb trail can be defined recursively: each `breadcrumb.in.html` fragment includes all those above it in the source tree.
@@ -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: $expand{$run(python,-c,import datetime; print(datetime.now().strftime('%Y-%m-%d')))}
167167
```
168168

169169
This gives a result looking something like:
@@ -175,14 +175,14 @@ Page contents.
175175
176176
--
177177
178-
Last updated: $paste(python,-c,import datetime; print(datetime.datetime(2016\,10\,12).strftime('%Y-%m-%d')))
178+
Last updated: $expand{$run(python,-c,import datetime; print(datetime.datetime(2016\,10\,12).strftime('%Y-%m-%d')))}
179179
```
180180

181181
## Dynamically naming output files and directories according
182182

183183
Since output file and directory names are expanded from input names, you can use commands to determine the name of an output file or directory.
184184

185-
For example, given a file called `author.in.txt` containing the text `Jo Bloggs`, an input file in the same directory called `$include{author.in.txt}.txt` would be called `Jo Bloggs.txt` in the output.
185+
For example, given a file called `author.in.txt` containing the text `Jo Bloggs`, an input file in the same directory called `$include(author.in.txt).txt` would be called `Jo Bloggs.txt` in the output.
186186

187187
## Dynamic customization
188188

@@ -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 `$run(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: `$run(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+
$run(make-zip.in.sh,\$outputpath)
223223
```

‎Cookbook.nancy.md‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -21,39 +21,39 @@ 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+
$expand{$run(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+
$expand{$run(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+
$expand{$run(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+
$expand{$run(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 `$expand{$run(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+
$expand{$run(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

5353
The `breadcrumb.in.html` fragments, except for the top-level one, contain the command
5454

5555
```
56-
\$include{breadcrumb.in.html}
56+
\$include(breadcrumb.in.html)
5757
```
5858

5959
When expanding `source/Places/breadcrumb.in.html`, Nancy ignores that file, since it is already expanding it, and goes straight to `source/breadcrumb.in.html`. This means that the breadcrumb trail can be defined recursively: each `breadcrumb.in.html` fragment includes all those above it in the source tree.
@@ -74,20 +74,20 @@ 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+
$expand{$run(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+
$expand{$run(cat,tests/test-files/page-template-with-date-src/Page.nancy.md)}
8484
```
8585

8686
## Dynamically naming output files and directories according
8787

8888
Since output file and directory names are expanded from input names, you can use commands to determine the name of an output file or directory.
8989

90-
For example, given a file called `author.in.txt` containing the text `Jo Bloggs`, an input file in the same directory called `\$include{author.in.txt}.txt` would be called `Jo Bloggs.txt` in the output.
90+
For example, given a file called `author.in.txt` containing the text `Jo Bloggs`, an input file in the same directory called `\$include(author.in.txt).txt` would be called `Jo Bloggs.txt` in the output.
9191

9292
## Dynamic customization
9393

@@ -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 `\$run(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: `\$run(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+
\$run(make-zip.in.sh,\$outputpath)
128128
```

0 commit comments

Comments
 (0)