hygen, every time you spot a repetitive task, or a hidden structure in files you're editing, you'll quickly make a new generator.
The moment we add a generator under
_templates, it's ready to use. Here's
hello.ejs.t that was placed in the template folder for you:
To make real mailer, let's copy this file and rename it a bit:
We use a
.t suffix because it disables our editor trying to be smart - use what ever you like. For this example these files represent the HTML and text forms of an email sender.
[[info]] | ###### Creative Freedom | hygen doesn't care about file names or file types in your generator folders. It only cares about folder structure and the contents of your files.
Also note that each template has a frontmatter delimited by a pair of
---'s. In our example, we have a special
to: property which tells
hygen where to put the generated file. We'll see more of these in templates.
Let's look at our folder structure:
Every time you call it,
hygen mailer new automagically picks up the closest
_templates folder, and renders all files in
mailer/new. In this case it's
As of PR 102 Hygen will recursively walk your template folder, so that you can structure your generators as elaborately as you wish.
|###### Hygen is Contextual
hygen simplifies things by asserting "command structure is folder structure".
hygen will pick up the
_templates in your current working directory.
hygen arguments via CLI, we follow this pattern:
Any double-dash (
--) argument becomes a variable we can use later in our templates. In the example above we can use
Here's the contents of the template
html.ejs.t with the variables in place:
Try making the text variant yourself by editing
text.ejs.t. Note: you want to put it in the correct place with
To create an interactive generator, add
prompt.js file to the generator root directory.
For example, to ask for the
message input variable, add to
The format is based on enquirer. Let's use the
message variable now:
Note that the
name variable has to come from the CLI. To generate, we'll do this:
Which will ask the user for the
message, and generate all contents.
Advanced Interactive Prompt
It's possible to create a a multi-step prompt where you ask some questions, run some computation and ask some more questions.
In addition, it's possible to skip prompting, or re-shape parameters that were given to you from either CLI or prompt, so that you can do it in a central place.
You can "enable" advanced params and prompting by replacing your
prompt.js file with an
index.js file in your action:
Here's how you can use
index.js to build a two-step prompting flow. Instead of exporting an array of question types as with the
prompt.js file, you now need to export an object with a function called
prompt function gets a data structure with an
prompter field you can use.
You can skip prompting conditionally using custom logic:
You can skip physically prompting and use
params to build more sophisticated parameters out of your CLI parameters:
| ###### Params and Prompts are The Same
| If you think about it, prompting for variables or reshaping CLI arguments lead to the same goal: new parameters. But to make a future-proof API, we've separated the two intents to the
Documenting Your Generators
Since there's a special
message prop you can use in any template, you can use that to build generator help screens. Ultimately, your generator should be documenting itself.
Looking at our generator layout from before, we add a
index.ejs.t is simply a blank template, with just a
| annotation is a YAML literal block. Should you need it, here's a quick YAML refresher.
Note that in
message you can have a special coloring syntax, which can spice up your self-documenting generators.
Here's a few examples:
For more styles check out chalk.
Selecting Parts of a Generator
In addition to what we've seen until now,
hygen lets the user select parts of a generator.
The complete form is:
SUBACTION is a regular expression or a simple string
hygen uses to pick up the subset of templates you want from a generator.
Using our mailer example, this generates only the text part:
Because we have a file named
text.ejs.t, the string
new:text will match it.
In the same way we could have used a proper regular expression:
That's about it for generators.