A system for compiling text files from raw text and program output.
textc essentially allows for scriptable text. You write a text file with embedded commands, pass it to textc and it executes those commands, embedding the output inside the raw text in the output file. Where this becomes especially powerful is with directory-based compilation: give textc a directory as input and it will traverse it, compiling each file it finds to the output directory.
I use the directory-based compilation feature of textc to generate the HTML for this site (which was the original aim of the program): I have a standard header, footer and breadcrumb trail generator which each page makes use of. This allows me to have the flexibility and simplicity of static HTML with the convenience of a shared header and footer, as well as an automatically-generated breadcrumb trail. Previously I had used PHP for all this, but I prefer the simplicity of this system.
Input files and compilation
When textc encounters a text file that is not otherwise excluded or marked for direct copy, it will compile it to stdout or to the output file or directory. When textc encounters a non-excluded binary file it will copy it directly with no further processing.
Compilation proceeds by copying any raw text character-for-character to the output, until a command is encountered. Commands are enclosed by backticks (
`), and will be executed by textc and the command output substituted into the compilation output. If you want to include a literal backtick in your file, you may escape it using a backslash (
\), and a literal backslash is escaped using another backslash.
textc [-h] [-o OUTPUT] [-n] [-v] [-a] [-e EXCLUDED] [-c CWD] [-d DIRECT] [-t] input
- Specify the input file or directory.
- Print a help message and exit.
- Show verbose output. This will show compiled, copied and excluded files, executed commands and any special characters (
- Specify the output location for compiled/copied files. This may either be a file or a directory. If omitted, output will be written to stdout instead.
- If both
inputwill be compiled or copied to
inputis a file and
OUTPUTis a directory,
inputwill be compiled or copied straight into
OUTPUT. If they are both directories, the directory structure of
inputwill be preserved in
OUTPUTand each file processed within that structure. If
inputis a directory and
OUTPUTis a file an error is produced.
- Prevent any trailing newlines in command output from being stripped before substitution into the file.
- Ask before overwriting existing files or executing commands.
- Do not use timestamps to determine whether a file should be re-compiled. If omitted, if the input file is older than the output file then recompilation of that file is skipped. You may want to use this flag if you have changed something that your files depend on without changing the files themselves.
- Specify a regex matching files to exclude from processing. This option can be used several times to define several regexes to check.
- Specify a regex matching files to exclude from compilation, instead directly copying them to the output. This option can be used several times to define several regexes to check.
- Set the directory which all executed commands will use as their working directory. If omitted, commands will be executed from the directory containing the input file.
textc adds one more variable to the environment that each command is executed in.
- The path to the input file.
- The operation completed successfully
- User attempted to compile a directory into a file
- Input file not found
- Failed to create output directory
- Failed to read directory listing while traversing input directory
- Failed to read from input file
- Failed to write to output file
- Failed to execute command
- Failed to perform direct copy of file
- Other error
- Write in chunks rather than character-by-character
- Add marker to top of files to be compiled, rather than having to directly copy lots of files
- Finer control over verbose output
- Globs instead of regexes for file matching (or as well as)