https://github.com/gimenete/helical
Helical is a general purpose code generator. It takes a data model definition and a set of templates (called generators) and generates an output.
https://github.com/gimenete/helical
Last synced: 3 months ago
JSON representation
Helical is a general purpose code generator. It takes a data model definition and a set of templates (called generators) and generates an output.
- Host: GitHub
- URL: https://github.com/gimenete/helical
- Owner: gimenete
- License: mit
- Created: 2015-11-17T11:02:29.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2016-02-01T14:55:07.000Z (over 9 years ago)
- Last Synced: 2025-02-01T00:51:07.456Z (3 months ago)
- Language: JavaScript
- Size: 43 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# helical
Helical is a general purpose code generator. It takes a data model definition and a set of templates (called generators) and generates an output.
# Data model definition
It is just a JSON file with no given structure. The structure depends on the templates used. This file can be stored at any location.
# Manifest and generators
You need a manifest file and a set of templates. You have to put all of them in the same directory. The templates can be in subdirectories, but
the manifest file must always be in the root of the directory and it must be called `helical.json`.
The templating language used in all the templates is [nunjucks](https://mozilla.github.io/nunjucks/)
The manifest file is a JSON file with two sections:
- `generators`
- `options`
Here there is an example:
```json
{
"generators": [
{
"source": "generators/entity.js",
"path": "models/{{ object.name | lower }}.js",
"foreach": "entities"
},
{
"source": "generators/endpoint.js",
"path": "controllers/{{ ancestors[0].name | lower }}-{{ object.action | lower }}.js",
"foreach": "entities.endpoints"
},
{
"source": "generators/app.js",
"path": "index.js",
"foreach": ""
}
],
"options": [
{
"name": "css",
"describe": "CSS preprocessor",
"type": "string",
"choices": ["less", "sass"]
}
]
}
```
And this could be a data model suitable of being processed by these generators:
```json
{
"projectName": "project_name",
"entities": [
{
"name": "User",
"fields": [
{
"name": "email",
"type": "string"
},
{
"name": "name",
"type": "string"
}
],
"endpoints": [
{
"action": "show",
"method": "get"
},
{
"action": "create",
"method": "post"
},
{
"action": "edit",
"method": "put"
},
{
"action": "delete",
"method": "delete"
}
]
}
]
}
```
## Generators
Every generator must have at least these attributes: `source`, `path` and `foreach`.
- `source`: this is the relative path to the template.
- `path`: this is an inline template to generate the output filename.
- `foreach`: tells helical which objects should be processed by this generator. Leave it empty if you only want to execute this template once
for the whole data model.
In the example above for the first generator helical will loop over all the `entities` in your data model.
And for each entity it will run the `entity.js` template. If the data model file contains an entity with `{ "name": "User" }`
then after processing that entity the output will be stored in a file called `models/user.js`.
Every template, including the inlined templates to generate the filename (`path` attribute), will receive these objects:
- `object`: the object being processed.
- `ancestors`: an array of ancestor objects.
- `root`: the root of the data model.
- `options`: see section `options` below.
In the example above the second generator will be processed for each endpoint of each entity. Every time the `endpoint.js` template
is processed it will receive these objects:
- `object`: the endpoint being processed.
- `ancestors`: in this example `ancestors[0]` will reference the parent entity of this endpoint.
- `root`: the root of the data model.
## Options
Optionally you can define an array of `options` in your `helical.json` file. These are values that the user can pass in the command line interface
to the generators. Each option has the following attributes:
- `name`. The name of the option. If you have an option called `css` in your templates you can use `options.css` to access the value
- `describe` (optional). A description of this option
- `type` (optional). The type of this option. Can be `string`, `array`, `boolean`, `count` or `string`. See the [yargs](https://www.npmjs.com/package/yargs) documentation about this.
- `choices` (optional). You can specify an array of allowed values for this option.
- `default` (optional). The default value for this option.
If you specify a not boolean option and there's not a default value and the user didn't specify the option in the command line then the application will exit with a message like this:
```
Usage: helical --model model.json --generator /path/to/some-generator
Options:
--model, -m The data model file [string] [required]
--generator, -g The directory that contains the helical generator [string] [required]
--output, -o Output directory [string] [required]
--force, -f Override files existing files [boolean]
-h, --help Show help [boolean]
--css CSS preprocessor [string] [required] [choices: "less", "sass"]
Missing required argument: css
```
## Static files
You can create a `static` directory and everything on it will be copied to the output directory. This is a good place to put files that are not plain text such
as images, fonts, or simply plain text files that don't need to be processed.
## Next steps message
You can render a message after all the files are generated creating a template `next-steps.txt`. This template will have access to the `root` and `options` objects.
# Overriding files
By default `helical` will not override existing files. But you can use the `--force` option to change this behavior.
# Watching for file changes
While developing helical generators or just to see interactively how the generators change when editing your data model, you can use the `--watch` option in the command line.
Note: files starting with a dot (`.`) are ignored.
# Error notifications
If you want to get notified when an error occurs processing any file, parsing the model, etc. you can use the `--notify` option. Right now it only notifies about errors, but in a future it will notify if the whole process got fixed if you change any file and it was giving errors previously.
#Â Installation
```
npm install helical -g
```
# Example
In this repository there is an example in the `example` directory. You can run it with:
```
helical \
--model example/model.json \
--generator example \
--output output \
--css less
```
This is the output:
```
Wrote output/models/user.js
Wrote output/controllers/user-show.js
Wrote output/controllers/user-create.js
Wrote output/controllers/user-edit.js
Wrote output/controllers/user-delete.js
Wrote output/index.js
```
# Skipping objects
You can avoid some objects to be processed by returning an empty file name in the `path` attribute of a generator. Example:
```json
{
"source": "endpoint.js",
"path": "{% if object.action != 'delete' %}controllers/{{ ancestors[0].name | lower }}-{{ object.action | lower }}.js{% endif %}",
"foreach": "entities.endpoints"
}
```
In this case endpoints with `"action": "delete"` won't generate any output.