/ 
File-Stubb-0.03
River stage zero No dependents
/ stubb

NAME

stubb - Stub file creator

SYMOPSIS

stubb [options] file template
stubb [options] file.template
stubb [options] -t template file ...
stubb [options] -l template

DESCRIPTION

stubb is a program that can create stub files/directories from pre-existing templates.

By default, stubb will create the stub file from the given template. The template can either be provided by a second argument to stubb or derived from file's suffix if a specific template isn't provided. A template can also be specified by the -t option. template can either be the name of a template in stubb's template directory or a path to a template file.

If file is a single dash (-), stubb will write the rendered file to stdout. This only works when rendering single files, not directories or multiple files at once.

Templates

stubb creates stubs from pre-existing template files and directories found in one of stubb's template directories. A stubb template file can contain "substitution targets" that allow you to customize a render by supplying substitution parameters.

stubb looks for stub templates in a template directory. The default location for this directory is ~/.stubb, but it can be configured to look in other locations via the STUBB_TEMPLATES environment variable or through the -d command-line option. Templates in the template directory must be named after the files they're templating followed by the .stubb path suffix.

# *template* can be 'pl', 'pm', or 'py'
STUBB_TEMPLATES
L pl.stubb
L pm.stubb
L py.stubb

stubb can perform text substitution on the contents of stub files through the use of substitution targets. Substitution targets are strings enclosed by double carets (^^) that tell stubb how the text should be rendered. Substitution parameters can be supplied to stubb via the -s option to customize the generation of a stub.

The following are a list of valid substitution target types:

^^ target ^^
^^ target // default value ^^

A basic substitution target. Has no sigil. If a substitution for the target is provided, the target will be replaced by the corresponding string. A default value can be specified by following the target with a // and the default string. If no substitution is provided the target will be rendered as the default string instead. If no substitution is provided and no default value is present, the target will be rendered as-is in the outputted stub file.

# Can be set via -s "foo => ...", otherwise is left alone.
This is a ^^foo^^ file.

# Can be set via -s "foo => ...", otherwise is rendered as "text".
This is a ^^foo // text^^ file.
?^^ target ^^

A conditional target is preceded by a question mark (?) sigil. It is similar to the basic target, but if no substitution is provided for the target the target will not be rendered at all. It does not support being provided default values.

# Can be set via -s "name => ...", otherwise is rendered as an empty string.
Hey ?^^name^^
$^^ perl code ^^

A Perl target is preceded by a dollar sign ($) sigil. The text inside the target will be interpretted as Perl code and evaluated using Perl's eval function. stubb will substitute the target with returned value from the evaled Perl code.

Substitution parameters can be accessed via the topic hash variable (%_) in the code. %_ will be set to a hash of target names as keys and their substituted text as values. The %_ hash is also special in that it does not return undef if a target does not exist, it instead returns an empty string, which should hopefully make writing safe Perl a little simpler.

Because this uses an unprotected eval, it is possible to modify some of stubb's internal data structures through the evaluated code, and cause breakages. Don't do that.

# Target will be rendered as some random number.
My favorite number: $^^rand^^

# $_{ name } can be set via -s "name => ...", otherwise is an empty string.
My name is $^^uc $_{ name }^^
#^^ shell code ^^

A shell target is preceded by a hash (#) sigil. The text inside the target will be interpretted as shell code and evaluated using Perl's qx// operator. stubb will substitute the target with the returned text from the code.

The code can access the substitution targets through the target's environment variables.

# Target will be rendered as the output of the date command.
Today is #^^date^^

# $number can be set via -s "numer => ..." on POSIX shells.
My favorite number is #^^printf "%x" "$number"^^
\?^^ target ^^
\$^^ target ^^
etc...

An escaped target is preceded by a backslash (\) and some other sigil. It should be used when you want to render sigil literally followed by a target instead of as a special target.

# "date" is a normal substitution target, not a shell target. The '\#' will
# be rendered as a '#'.
Today is \#^^date^^
!^^ not a target ^^

A non-target is preceded by an exclamation mark (!) sigil. Should be used when you have a piece of text that you do not want stubb to interpret as a normal substitution target. When rendered, stubb will render the text as-is except with the exclamation mark removed.

# Will be rendered literally, except with the '!' gone.
This isn't a target: !^^phony^^

stubb can also perform text substitution on stub path names, both ones specified through the command-line and ones located in template directories. Path names can only contain basic targets, and the substitutions cannot contain illegal path characters.

# Will create 'abc'
stubb -s "prgnam => abc" ^^prgnam^^ template

Directory templates can contain their own rendering configuration in a special file called .stubb.json. This file is a JSON file that conveniently stores a template's unique configuration so that one does not have to manually specify a bunch of command-line flags each time they wish to generate a stub from it. The following are a list of valid .stubb.json fields:

"defaults": { ... }

Key-value map of default substitution parameters to use for parameters that aren't supplied via the -s option. This field can be ignored with the --no-defaults option.

"render_hidden": bool

Boolean determining whether to render hidden files or not. Can be overridden with the --hidden and --no-hidden options. Defaults to false.

"follow_symlinks": bool

Boolean determining whether to render symlinks by following them or by creating a new symlink that points to a path that was determined by performing text substitution on the template symlink's target. Can be overridden with the --follow-symlinks and --no-follow-symlinks options. Defaults to true.

"copy_perms": bool

Boolean determining whether to the copy the permissions of a template file to its stub when rendering it. Can be overridden with the --copy-perms and --no-copy-perms options. Defaults to false.

OPTIONS

-d|--template-dir=dir

Specify a directory to search for templates in. This option can be used multiple times to specify multiple different directories. This option works on top of the STUBB_TEMPLATES environment variable.

By default, stubb will search for templates in ~/.stubb.

-t|--template=template

Specify the template to use for batch file creation. Command-line arguments will be interpretted as a list of stub files to create from the given template.

-s|--substitute=params

Supply substitution parameters to stubb. params is a string of comma-seperated key-value pairs of targets and their corresponding substitution, seperated by a "fat comma" (=>).

As an example, the following option will replaced prgnam targets with "abc", prgver with "0.01", and srcnam with "abc-0.01".

-s "prgnam => abc, prgver => 0.01, srcnam => abc-0.01"

Commas preceded by a backslash will be interpretted as literal commas and not be used to split parameters.

This option can be used multiple times to supply multiple different parameter strings, if you would prefer that to supplying one single parameter string.

-a|--hidden
-A|--no-hidden

Enable/disable the rendering of hidden files in stub directories. Default is to not render hidden files.

-c|--copy-perms
-C|--no-copy-perms

Enable/disable the copying of the template files' permissions when rendering stub files. Default behavior is to not copy permissions.

-w|--follow-symlinks
-W|--no-follow-symlinks

Enable/disable the following of symlinks in template directories. If disabled, stubb will create new symlinks in the stub directory that point to paths that are determined from performing text substitution on the targets of the original template symlinks. Default behavior is to just follow symlinks.

-U|--no-defaults

Disable the use of any default substitution parameters provided in a template's .stubb.json.

-I|--no-config

Ignore the .stubb.json configuration file if it is present in a directory template.

-l|--list

Print a list of substitution targets in the given template.

-q|--quiet

Disable informative output.

-h|--help

Print stubb's usage message and exit.

-v|--version

Print stubb's version and copyright information, then exit.

ENVIRONMENT

STUBB_TEMPLATES

Colon-seperated list of directories for stubb to search for templates in.

FILES

~/.stubb

Default directory stubb searches for templates in.

AUTHOR

Written by Samuel Young, <samyoung12788@gmail.com>.

This project's source can be found on its Codeberg page. Comments and pull requests are welcome!

COPYRIGHT

Copyright (C) 2025 Samuel Young

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

SEE ALSO

perl(1)