geenee-rate

code generator based on geenee metadata.

• geenee-rate
  • :clipboard: Why
  • :white_check_mark: What
  • :wrench: Usage
  • :bulb: Example
  • :zap: Creating Templates
  • package.json files
  • Related project
  • :ledger: API
    • arguments

:clipboard: Why

File generation consists of three types of files. Each requires different context to generate:

1. standard files that never change. These require no context.
2. static files--they vary from project to project, but do not receive dynamic content. These require a static specification of info for each example in a particular generated code base.
3. dynamic files--they contain dynamic content. These require specification for whatever query is required.

:white_check_mark: What

A single async function that generates code from a specified geenee template and settings, handling the context of all three types of files above. See Context in geenee-rate for details about the context.

geenee-rate ignores anything in the directory of the package, with the exception on a package.json file.

It will overwrite any files with the same path and name.

Because it leaves everything else, you can apply a starter first. That is useful because you can use head-starter with your same geenee template.

:wrench: Usage

Import the package:

npm i geenee-rate

Set the following in your code:

• codeDir: path to your codeBase to generate
• nsInfo: json containing settings for the generated code
• config: json containing the configuration from the template
• templateDir: the directory of the template

Then you can call:

const generate = require('geenee-rate')

try {
    await generate(
      codeDir, nsInfo, config, templateDir
    )
  } catch (error) {
    throw new Error(`could not generate the code: ${error}`)
  }

If you need to get the config, you can use magicalstrings. Here's an example using TypeScript:

const {getConfig} = require('magicalstrings').configs
import {Configuration} from 'magicalstrings'

let config: Configuration
...
config = await getConfig(templateDir)

:bulb: Example

Check out the usage in geenee-spell.

:zap: Creating Templates

You can create such a template easily from a code base using copykat.

Once you have created a basic template, geenee-rate has a built-in context to make the job much simpler. See the documenation of barbells for treatment of handlebars helpers and partials. You may find that you don't need to add any custom helpers.

Also, check out the Creating Templates on the geenee documentation.

package.json files

The biggest gotcha with geenee-rate is the package.json files.

It's not complicated, but you have to understand two things:

1. package.json files are the one exception to the rule that geenee-rate doesn't know or care what was in your project directory--it will simply overwrite or ignore existing files. But the legacy package.json is updated rather than replaced;
2. That said, what's in the template file general/packageinfo.json.hbs, takes precendence over what was in the legacy package.json. That is to say that any value for keys generated by that file will replace the values that you had before. That will be based upon what's in the ns.yml specs file. So in practice you will need to update the ns.yml file with the latest information. We may replace that with a different behavior in the future, such as an option not to regenerate the json.

Note that dependency versioning is not relevant to geenee-rate. Whatever you had before should stay the same.

Related project

A geenee template is normally used for multiple generation of code. To do that, geenee-spell stores a meta directory within the generated code base to allow for regeneration.

But geenee templates are a very powerful tool for one-time creation as well. For instance, you may not want to include a meta directory in your code. That is the reason for geenee-rate existing separately.

:ledger: API

async function generateCode(
  codeDir: string,
  nsInfo: NsInfo,
  config: Configuration,
  templateDir: string,
  addStarter: boolean = true,
  sessionIn: any = {},
)

The NsInfo and Configuration types are exposed in magicalstrings.

arguments

• codeDir: string telling the directory where you want the code to generate.
• nsInfo: NsInfo telling about
• config: Configuration,
• templateDir: string,
• addStarter: boolean set by default to true. It means that if the code contains a head-starter startup sequence, it will be executed.
• sessionIn: object, by default empty. It lets you apply a dynamapping session to change the values of a startup sequence dynamically if you like. codeDir is added to the session automatically, so you can insert $codeDir into your startup sequence already.