43 stable releases
new 2.21.1 | Dec 5, 2024 |
---|---|
2.21.0 | Oct 25, 2024 |
2.20.1 | Aug 23, 2024 |
2.19.1 | Jul 23, 2024 |
1.0.1 | Feb 21, 2023 |
#22 in Template engine
157 downloads per month
87KB
453 lines
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" viachmod +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
. Seebuild.md
for an example.
While kapow is designed around Markdown syntax, it can be used with any text format that works with its directives.
Block directives
Directive | Description |
---|---|
!inc:path |
Include file contents; path is relative to its containing file |
!run:command |
Run command and insert stdout |
!start:name - !stop:name |
Optional content included only if name is provided in -f value |
Notes:
- Block directives must be placed at the beginning of a line.
- Long commands can be backslash-wrapped.
- 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
. - 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.
- 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` |
2024-12-05T01:56:52Z | Current date/time in UTC / RFC 3339 |
`!now:local` |
Wed 04 Dec 2024 20:56:52 EST | Current date/time in local timezone |
`!now:local:%A %H:%M` |
Wednesday 20:56 | Current date/time in local timezone and custom format |
`!now:MST7MDT` |
Wed 04 Dec 2024 18:56:52 MST | Current date/time in custom timezone |
`!now:MST7MDT:%A %H:%M` |
Wednesday 18:56 | Current date/time in custom timezone and format |
`!now:US/Hawaii` |
Wed 04 Dec 2024 15:56:52 HST | Current date/time in custom locale |
`!now:US/Hawaii:%A %H:%M` |
Wednesday 15:56 | Current date/time in custom locale and format |
`!now:UTC:%A %H:%M` |
Thursday 01:56 | Current date/time in UTC and custom format |
`!now:x` |
XiB41uq | Current date/time in "x" format |
`!today` |
2024-12-05 | Current date in UTC / RFC 3339 |
`!today:local` |
2024-12-04 | Current date in local timezone |
`!today:MST7MDT` |
2024-12-04 | Current date in custom timezone |
`!today:MST7MDT:%e-%b-%Y` |
4-Dec-2024 | Current date in custom timezone and format |
`!today:US/Hawaii` |
2024-12-04 | Current date in custom locale |
`!today:US/Hawaii:%m/%d/%y` |
12/04/24 | Current date in custom locale and format |
`!today:UTC:%A` |
Thursday | 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:\!
.
Other features
- Escaped wrap: End a line with a single backslash
\
and it will be unwrapped in the output; this enables an author to wrap long lines in the source but have them be unwrapped by kapow. If trailing backslash(es) need to be maintained, add an additional backslash and the line will not be unwrapped and the extra backslash will be removed. - Relative image paths: Markdown images (
![alt](path "title")
) with a local path are processed relative to the containing file, unless the-R
option is used to disable this feature. - Eliminate multiple empty lines.
Install
cargo install kapow bat
NOTE: Installing bat
is optional, but if installed, kapow uses it for syntax
highlighting and paging (if on a Linux, macOS, or UNIX system; see the -p
,
-P
, -H
, -l
, and -r
options); also it's a nice utility to have around.
Usage
$ kapow -V
kapow 2.21.1
$ kapow -h
KAPOW!
Usage: kapow [OPTIONS] [PATH]...
Arguments:
[PATH]... Source file(s) [default: -]
Options:
-f <FLAGS> Flags (comma-separated list of flags to enable)
-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 Disable relative image paths
-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
fromt/VERSION.t.md
!run:../target/release/kapow -V
- Generates
t/USAGE.md
fromt/USAGE.t.md
!run:../target/release/kapow -h
- Generates
README.md
fromt/README.md
!inc:VERSION.md
!inc:USAGE.md
`!now`
(all variants)- Escaped wraps
- Relative image path
Changelog
Please find the CHANGELOG.md
in the repository.
Development
cargo install b3sum bat cargo-audit cargo-edit cargo-make \
cargo-outdated dtg kapow miniserve
Dependencies
~9–20MB
~274K SLoC