donotturnoff

textc

View this project on GitHub.

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.

Documentation

A flowchart indicating the process of compiling a file with textc

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.

Progam arguments

Usage: textc [-h] [-o OUTPUT] [-n] [-v] [-a] [-e EXCLUDED] [-c CWD] [-d DIRECT] [-t] input

Positional arguments
input
Specify the input file or directory.
Optional arguments
-h, --help
Print a help message and exit.
-v, --verbose
Show verbose output. This will show compiled, copied and excluded files, executed commands and any special characters (` or \) encountered.
-o OUTPUT, --output OUTPUT
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 input and OUTPUT are files, input will be compiled or copied to OUTPUT. If input is a file and OUTPUT is a directory, input will be compiled or copied straight into OUTPUT. If they are both directories, the directory structure of input will be preserved in OUTPUT and each file processed within that structure. If input is a directory and OUTPUT is a file an error is produced.
-n, --keep-newlines
Prevent any trailing newlines in command output from being stripped before substitution into the file.
-a, --ask
Ask before overwriting existing files or executing commands.
-t, --ignore-timestamps
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.
-e EXCLUDED, --exclude EXCLUDED
Specify a regex matching files to exclude from processing. This option can be used several times to define several regexes to check.

-d DIRECT, --direct-copy DIRECT
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.

-c CWD, --cwd CWD
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.

Environment variables

textc adds one more variable to the environment that each command is executed in.

SCRIPTPATH
The path to the input file.

Status codes

0
The operation completed successfully
1
User attempted to compile a directory into a file
2
Input file not found
3
Failed to create output directory
4
Failed to read directory listing while traversing input directory
5
Failed to read from input file
6
Failed to write to output file
7
Failed to execute command
8
Failed to perform direct copy of file
127
Other error

To do