kapow 2.10.0

Template processor
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

# About

Kapow is a *template processor* that provides the following directives to
support injecting file contents, command output, current date/time, elapsed
time, etc in generated output.

It can be used in some different ways:

* Standard: Create a (Markdown) file with kapow directives then run
  `kapow [OPTIONS] path/to/file.ext`; optionally save the output via
  redirection: `kapow [OPTIONS] path/to/file.ext >output.ext`
* Shebang: Place `#!/usr/bin/env kapow` as the first line of a (Markdown) file,
  make it "executable" via `chmod +x file.ext`, then run via `./file.ext` (see
  note #3 under [block directives]).
  Use env's `-S` option if passing options to kapow, for example:
  `#!/usr/bin/env -S kapow -w 60`.

While kapow is designed around Markdown syntax, it can be used with any text
format that works with its directives.

[block directives]: #block-directives

## Block directives

Directive | Description
---|---
`!inc:path` | Include file contents; path is relative to its containing file
`!run:command` | Run command and insert stdout

Notes:

1. Block directives must be placed at the beginning of a line.
2. Long commands can be backslash-wrapped.
3. Included file paths and commands are processed from the directory where the
   source file is located when it is passed as an argument.
   However, if the source file is read on stdin or run via shebang, included
   file paths and commands are processed relative to the current directory.
   So, if any included files use relative paths or commands that depend on the
   current directory, it will be necessary to manually change to the source
   file's directory and then run via `./file.ext`.
4. Block directives are entirely replaced by their contents/output, so you are
   free to embed them inside or as Markdown syntax... for example, as listing
   contents, prepend a prompt showing the command, etc.
5. If a `!run` directive fails, kapow prints the error and stops processing,
   unless the user specifies the `-k` option.

## Span directives

Directive | Example | Description
---|---|---
`` `!elapsed` `` | 0s | Processing time
`` `!now` `` | 2023-05-12T13:19:11Z | Current date/time in UTC / RFC 3339
`` `!now:local` `` | Fri 12 May 2023 09:19:11 EDT | Current date/time in local timezone
`` `!now:local:%A %H:%M` `` | Friday 09:19 | Current date/time in local timezone and custom format
`` `!now:MST7MDT` `` | Fri 12 May 2023 07:19:11 MDT | Current date/time in custom timezone
`` `!now:MST7MDT:%A %H:%M` `` | Friday 07:19 | Current date/time in custom timezone and format
`` `!now:US/Hawaii` `` | Fri 12 May 2023 03:19:11 HST | Current date/time in custom locale
`` `!now:US/Hawaii:%A %H:%M` `` | Friday 03:19 | Current date/time in custom locale and format
`` `!now:UTC:%A %H:%M` `` | Friday 13:19 | Current date/time in UTC and custom format
`` `!now:x` `` | Xh4BDJB | Current date/time in "x" format
`` `!today` `` | 2023-05-12 | Current date in UTC / RFC 3339
`` `!today:local` `` | 2023-05-12 | Current date in local timezone
`` `!today:MST7MDT` `` | 2023-05-12 | Current date in custom timezone
`` `!today:MST7MDT:%v` `` | 12-May-2023 | Current date in custom timezone and format
`` `!today:US/Hawaii` `` | 2023-05-12 | Current date in custom locale
`` `!today:US/Hawaii:%x` `` | 05/12/23 | Current date in custom locale and format
`` `!today:UTC:%A` `` | Friday | Current date in UTC and custom format

* Span directives must be placed inside a code span and may appear zero or more
  times in any line.
* Disable processing a span directive by escaping `!` with a backslash: `\!`.

# Install

```bash
cargo install kapow bat
```

NOTE: Installing [`bat`] is optional, but if installed, kapow uses it for syntax
highlighting and paging (see the `-p`, `-P`, `-H`, `-l`, and `-r` options); also
it's a nice utility to have around.

[`bat`]: https://crates.io/crates/bat

# Usage

```text
$ kapow -V
kapow 2.10.0
```

```text
$ kapow -h
KAPOW!

Usage: kapow [OPTIONS] [PATH]...

Arguments:
  [PATH]...  Source file(s) [default: -]

Options:
  -p               Page output
  -P               Do not page output
  -H               Disable syntax highlighting
  -L               Display all syntax highlight languages
  -l <LANG>        Syntax higlight language [default: md]
  -w <WRAP>        Wrap !run directive columns [default: 0]
  -c <STRING>      Wrap !run directive continuation [default: \]
  -k               Ignore !run directive failures
  -r, --readme     Print readme
  -h, --help       Print help
  -V, --version    Print version
```

# Errors

Code | Description
---|---
101 | Could not read input file
102 | Could not read included file
103 | Could not change directory
104 | !run directive command failed

NOTE: The kapow process may not *appear* to have exited with these error codes
in "normal usage" because output is piped to [`bat`] as a pager if it is
installed and output is a TTY and unfortunately [`bat`] masks the error code.

# Example

See the `readme` task in `Makefile.toml`:

* Generates `t/VERSION.md` from `t/VERSION.t.md`
    * `!run:../target/release/kapow -V`
* Generates `t/USAGE.md` from `t/USAGE.t.md`
    * `!run:../target/release/kapow -h`
* Generates `README.md` from `t/README.md`
    * `!inc:VERSION.md`
    * `!inc:USAGE.md`
    * `` `!now` `` (all variants)

# Changelog

Please find the [`CHANGELOG.md`] in the [repository].

[`CHANGELOG.md`]: https://github.com/qtfkwk/kapow/blob/main/CHANGELOG.md
[repository]: https://github.com/qtfkwk/kapow/

# Development

```bash
cargo install cargo-audit cargo-edit cargo-make cargo-outdated dtg \
kapow miniserve
```