# TL;DR
**pbj** is a command line tool to generate sensible tdd software
development projects from declarative templates written in TOML.
***Typescript*** and ***Python*** project templates are built in. Just
[install](#_installation) it and go.
`pbj generate -t python PROJECT_NAME`
`pbj generate -t typescript PROJECT_NAME`
See the [Templates](#_templates) section for details on customization
and [Origin](#_origin) for why this tool exists.
# Installation
**pbj** is avaialable on <https://crates.io>. Source is available on
it’s github page: <https://github.com/electric-hand/pbj>.
Simplest installation is via cargo.
cargo install pbj
# Commands
Currently there is only one command: `generate`.
`generate`
Generate a project. Aliased to `g`.
the command
- parses and loads a `template` by name — **pbj** looks for a file
named `<<template>>.toml` in a known set of [configuration
folders](#_configuration)
- adds production dependencies
- adds development dependencies (if supported by your
language/tooling)
- runs any post generation commands specified
- generates source, test and config files as declared in the template
examples
- `pbj generate -t python PROJECT_NAME`
- `pbj g PROJECT_NAME` — using config file
High on my list of todos is a command for template skeleton generation
and a command to initialize a config with defaults.
# Configuration
**pjb** looks for a `config.toml` file (used for setting default
arguments) and template files in the following locations in the
following order. First one found wins.
The config dirs are system dependent and provided by the
[dirs](https://docs.rs/dirs) crate)
- `$HOME_DIR/.config/pbj` — Added manually for macos users in a mixed
environment
- [Local Config
Dir](https://docs.rs/dirs/latest/dirs/fn.config_local_dir.html)
- [System Config
Dir](https://docs.rs/dirs/latest/dirs/fn.config_dir.html)
- [Built-ins](https://github.com/electric-hand/pbj/tree/main/templates)
Templates are looked for and loaded from the `templates` subdirectory in
the above config locations.
## config.toml
A simple config file that specifies default arguments. Defaults and
example can be found
[here](https://github.com/electric-hand/pbj/blob/main/default_config.toml).
### `[template]`
The default template to use. Provides a default for the `-t` or
`--template` argument to the `generate` command.
### `[prefix_separator]`
The string to use for prefix separation. Used if you provide a prefix to
your project via the `-p` or `--prefix` argument to the `generate`
command. Defaults to `_`
example
`pbj g -p 1234 many_moons` will generate a project directory
`1234_many_moons` with the [$PROJECT\_NAME](#_project_name) set to
`many_moons`.
### `[variant]`
The file variant to use. Provides a default for the `-v` or `--variant`
argument to the `generate` command.
# Templates
## Custom Templates
A starter template can be copy/pasted from the github [templates
folder](https://github.com/electric-hand/pbj/tree/main/templates) or one
can be manually authored with he format below.
## Sections
### `[language]`
binary
the executable binary used to 'run' the language. This is tested to
exist and be on the path.
version
the version of the language required. NOT USED.
name
user friendly name of the template. NOT USED.
### `[project]`
dependencies
A list of runtime "production" dependencies.
dev\_dependencies
A list of runtime "development" dependencies.
### `[project.tool]`
binary
The project tool used for initialization, dependency management and
running tests.
### `[project.tool.commands]`
initialize
Command for the `project.tool` that initializes a new project using the
`project.tool.binary`
add\_dependency
Command and arguments to add "production" dependencies.
add\_development\_dependency
Command and arguments to add "development" dependencies.
run\_tests
Command to run unit tests.
### `[[project.post.commands]]`
A set of arbitrary commands to execute after the project initialization.
Pretty much allows you do whatever you like.
command
the command to run.
args
list of arguments to pass to the command above.
### `[code.directories]`
source
the (relative to root) project directory to put the source code files
generated by the `[[code.source]]` files.
test
the (relative to root) project directory to put the source code files
generated by the `[[code.test]]` files.
### `[[code.source]]`
files generated relative to the `source` directory in the
`[code.directories]` table. Follows the [file format](#_file_format)
### `[[code.test]]`
files generated relative to the `source` directory in the
`[code.directories]` table. Follows the [file format](#_file_format)
### `[[config]]`
files generated relative to the root directory. Follows the [file
format](#_file_format)
### file format
file
the path to generate the file to (can contain folders). The path is
relative. The directory the path starts from varies.
variant
an optional key used to generate variations of the template. If
specified on the command line, will override files with the same `file`
path. Files without a variant specified have an implicit variant of
`default`.
contents
the contents to write to the file
## Variables
There is a preprocessing pass on the TOML that does ultra basic variable
substitution.
### `$PROJECT_NAME`
Any use of this special variable will be replaced by the project name
provided on the command line.
# Random Bits
## Leetcode support
One of the drivers for building this tool was a desire to work on
algorithmic/interview problems locally.
The intention is to use the prefix argument and `leet` file variant to
do so.
Example
`pbj generate -p 1293 -t python shortest_path` generates a project that
correlates to the problem number but does not include the prefix in any
of the generated code. The files lend themseles to the leetcode format.
# Origin
I needed to do a ton of little projects (mostly coding katas, leetcode,
etc.) and had forgotten how to set up typescript projects from scratch
with:
- good configuration
- healthy layout
- immediately runnable unit tests
There are other project generators out there — yeoman, npm-based create
scripts — but I don’t like how opaque they are. I wanted something fully
declarative with a readable project declaration.
This started as a super basic bashscript but then I wanted to jam on
python and after a copy past decided to do some better automation.