maandree/gpp: [Complete] Bash-based preprocessor for anything - Codeberg.org

NAME
	gpp - Bash-based preprocessor for anything
SYNOPSIS
	gpp [-D name[=value]] [-f file | [-i input-file]
	 [-o output-file]] [-n count] [-s symbol]
	 [-R macroline-replacement-text] [-u [-u]]
	 [shell [argument] ...]
ETYMOLOGY
	gpp stands for General Preprocessor.
DESCRIPTION
	gpp lets a developer embed directives written in GNU
	Bash (this can be changed) into any text document.
	These directives are used to automate the writing of
	parts of the document.
	The preprocessing directives start with a symbol
	(or text string) specified by the developer. By default
	this symbol is @ (at).
	Any line starting with @< (where @ is the selected
	symbol for preprocessing directives) or @>, or is
	between a line starting with @< and a line starting
	with @>, is parsed as a line, written in Bash, that
	is executed during preprocessing. A @< line must have
	an associated @> line somewhere after it, all lines
	between them are parsed as preprocessing directives.
	A @> does however not need an associated @< line
	somewhere before it, making @> suitable for single
	line directives.
	Preprocessing directives can also be inline. For this,
	use @(COMMAND) where COMMAND is the Bash code to run.
	Additionally, gpp supports variable substitution.
	@{VARIABLE} will be replaced by the value of the
	variable (possibly an environment variable) VARIABLE.
	gpp supports all modifiers that Bash (or whichever
	shell is selected) supports. For example, if you want
	the value to be included but uppercase you can write
	@{VARIABLE^^}, or @{VARIABLE,,} for lowercase. gpp
	also supports mathematical expressions via the shell's
	$((EXPRESSION)) syntax, by using @((EXPRESSION)).
	Everything that is not a preprocessing directive is
	echo verbatim, except all @@ are replaced by @.
OPTIONS
	-D name=value
		Set the environment variable name to hold
		the value value.
	-D name
		Set the environment variable name to hold
		the value 1.
	-f file
		Equivalent to -i FILE -o FILE.
	-i input-file
		Select file to process. Default value is /dev/stdin.
	-n count
		Process the file recursively count times.
		Default value is 1.
	-o output-file
		Select output file. Defaults value is /dev/stdout.
	-R macroline-replacement-text
		Text to replace macrolines with in the output.
		You may for example want to use % for TeX files.
		Default value is the empty string.
	-s symbol
		Set the prefix symbol for preprocessor directives.
		Default value is @.
	-u
		Clear the shebang line, remove it if this flag
		is used twice. If used twice, an empty line
		will be inserted after the new first line.
OPERANDS
	shell
		The shell to run instead of bash. The shell
		must be compatible with POSIX shell.
	argument ...
		Command line arguments for the shell.
EXAMPLES
 Conditional hello world
	This example only includes the "Hello world" line if
	the environment variable HELLO is defined and is not
	empty.
	@>if [ -z "$HELLO" ]; then
	Hello world
	@>fi
 Multiline preprocessor directive
	This example creates the function uppercase() that
	converts lower case ASCII letters to upper case.
	@<uppercase () {
	 lower=qwertyuiopasdfghjklzxcvbnm
	 upper=QWERTYUIOPASDFGHJKLZXCVBNM
	 sed y/$lower/$upper/ <<<"$*"
	@>}
 Inline directives
	This example uses the uppercase() function above to
	convert the user's username to upper case. If the user's
	username is john, the code will expand to You are logged
	in as JOHN.
	You are logged in as @(uppercase $USER).
 Variable expansions
	In this example, if the user's username john, the code
	will expand to You are logged in as john.
	You are logged in as @{USER}.
 Variable expansion with substitution
	This example uses a substitution mechanism in Bash to
	convert the first letter in a variable to upper case.
	In this example, if the user's username john, the code
	will expand to You are logged in as John.
	You are logged in as @{USER^}.
RATIONALE
	Programmers need more automation when we write software
	and documentation. An unrestricted preprocessor lets
	you automate just about anything. Of course, it can be
	used for anything, not just writing software and
	documentation. Preprocessing can be used for more than
	automation, it can also be used to increase the flexibility
	of the work.
	C is one of the few languages that includes a preprocessor,
	sometimes it is not enough; and all languages need
	preprocessors.
SEE ALSO
	bash(1), jpp(1), cpp(1), env(1)