How-to guides
Each guide solves one task and assumes you know the basics: the tutorial teaches those. The guides come from the generator repository, where the test suite runs every example in them or states why it does not.
Install
Getting Jostraca into a project, in either implementation.
- Install Jostraca for TypeScript
Add the jostraca package to a Node project, and run a generator to check the install.
- Install Jostraca for Go
Add the Go port to a module, and run a generator to check the install.
Compose the output tree
Declaring folders, files, and the content that goes inside them.
- Write a file tree
Declare folders and files with nested components, and know which props move the output path.
- Insert values from your model
Substitute values from the data model into file content with the double-dollar syntax.
- Repeat content inside one file
Emit one block of content per array item inside a single file, with List.
Templates and fragments
Filling files from a data model, and from template files on disk.
- Fill a template file's slots
Read a template file with Fragment and fill its marked regions with Slot.
- Extract part of a template
Use eject to take one marked region out of a larger template file.
- Replace markers in a template
Swap named placeholders in a template for strings, computed values, or generated components.
- Indent generated content
Indent a block of generated content to match the code around it.
Reusable components
Factoring a generator into pieces you call more than once.
- Make a reusable component
Wrap a function with cmp so it can be called anywhere in a component tree.
- Pass data to child components
Give a custom component a body, and call that body once per item with data.
- Branch and loop in a generator
Use ordinary JavaScript control flow to decide what a generator emits.
Regenerating over existing files
Running the generator again over code a person has edited.
- Keep a backup when overwriting
Turn on preserve so the bytes you are about to overwrite are kept in a sibling file.
- Offer a new version instead of overwriting
Leave the existing file untouched and write the new version beside it with present.
- Merge your changes with the user's
Three-way merge the new generate with hand edits, using the previous run as the base.
- Show a diff instead of writing
Rewrite the target as an annotated two-way diff so a reviewer can see both versions.
- Let a user take a file over
Mark a generated file with JOSTRACA_PROTECT so no later run overwrites it.
- Preview a run without writing
Run the whole generator with control.dryrun so it reports what it would do and writes nothing.
Files, copying, and permissions
Getting existing assets into the output, and setting how they land.
- Copy a directory into the output
Bring an existing file or directory tree into the output, templating text on the way.
- Skip files when copying
Keep editor backups, caches and named paths out of a copied tree.
- Make a generated script executable
Give a generated script its execute bit with the File mode prop.
- Edit a file you did not generate
Use Inject to replace the region between two markers in a file that already exists.
Embedding Jostraca
Run the generator from your tool using memory or disk.
- Generate in memory
Run a generator on a virtual filesystem with mem, and read the result back from the volume.
- Report what a run did
Read the result arrays and the audit trail to tell a user what a generate changed.
- Test a generator
Assert on a generator's output without a temp directory, using in-memory generation.
- Call Jostraca from Go
Drive the Go port from your own program, and know where its surface differs.