arguments.md

Template Arguments

The cyto-helloworld template is great for explaining the core mechanics of Cyto but glosses over some important details. In this section, we're going to dive into more detail about the args section of a Cyto template, using the cyto-arguments template to help demonstrate the different types of arguments Cyto accepts. This template will already be installed if you installed cyto-preset-tutorials in the previous doc section. If you still haven't brushed up on Mustache syntax, you should really do so before reading on.

node_modules/cyto-template-cyto-arguments/cyto.config.js

module.exports = {
  templateId: "cyto-arguments",
  dependencies: [
    'demo.txt',
  ],
  args: [
    {
      id: 'stringArg',
      default: "I'm a string"
    },
    {
      id: 'booleanArg',
      type: 'boolean',
      default: false
    },
    {
      id: 'listArg',
      type: 'list',
      default: []
    },
    {
      id: 'functionArg',
      type: 'function',
      default: () => {
        return (text, render) => {
          return render(text)
            .then((renderedText) => {
              return renderedText.replace('Replace me', 'Got replaced');
            });
        }
      },
      dontPrompt: true
    },
    {
      id: 'runtimeArg',
      type: 'string',
      default: (args) => `stringArg was set to ${args.stringArg}`,
      dontPrompt: true
    }
  ],
  options: {
    createDirectory: false,
  }
};

node_modules/cyto-template-cyto-arguments/demo.txt

{{id}}
Generated by: {{author}}

{{stringArg}}

{{# booleanArg}}
The boolean arg was set to true!
{{/ booleanArg}}
{{^ booleanArg}}
The boolean arg was set to false!
{{/ booleanArg}}

{{# listArg}}
{{id}}
{{/listArg}}
{{^ listArg}}
There were no values provided to `listArg`
{{/listArg}}

{{# functionArg}}
The text after the colon will be replaced: Replace me
{{/functionArg}}

{{runtimeArg}}

Arg types

Remember that the args section of each cyto.config.js file is just an array of objects that declares what values to prompt a user for during generation. These values are then passed to mustache when each dependency is rendered. Let's take a look at an argument with all of the possible keys you can use:

{
  id: 'demoArg',
  type: 'list', // default: string
  default: [] // default: undefined
  dontPrompt: false, // default: false
}

1. id: A unique identifier for an argument. This only needs to be unique for the given template, not globally.
2. type: A string identifier for what type an argument is. Cyto supports four different types of arguments: string (default), list, boolean, and function. If the argument has a string type, you can omit this key.
3. default: A default value for the argument. Pretty self explanatory.
4. dontPrompt: A boolean flag that indicates if Cyto should avoid prompting the user for a value for this argument during generation and use its default.

That's all there is to arguments! Cyto will automatically handle prompting a user for you, so all you need to do is declare what you need. Cyto uses the awesome Inquirer.js library to handle prompting. Boolean arguments are prompted using the confirm prompt type, while all other types use the input prompt type. Input for a list argument is treated as a CSV, so in order to supply multiple values for it, separate each value with a ,.

Pre-supplied arguments

Cyto will provide 2 arguments for you by default: id and author. id is a required arg for all templates so you don't have to specify it in your args section. author is prepopulated with the name stored in your global .gitconfig file.

Function arguments

There are a couple caveats regarding arguments with the function type. Let's take a look at the functionArg from the cyto-arguments template:

{
  id: 'functionArg',
  type: 'function',
  default: () => {
    return (text, render) => {
      return render(text)
        .then((renderedText) => {
          return renderedText.replace('Replace me', 'Got replaced');
        });
    }
  },
  dontPrompt: true
}

Currently, Cyto is unable to prompt the user for functions via the command line, so they must be provided via the default key and have dontPrompt set to true. Function arguments also look a bit different than how they are detailed in the Mustache documentation. This is because Cyto uses a slightly modified version of Mustache.js where the rendering process is asynchronous. This means that the render function returns a Promise that resolves with the rendered text, instead of returning the rendered text immediately. The reason behind this is due to how Cyto handles Mustache partials, which will be explained later. If you are familiar with async/await and you are running a version of Node that supports them, function arguments can be written in a much cleaner fashion:

{
  id: 'functionArg',
  type: 'function',
  default: () => {
    return async (text, render) => {
      const renderedText = await render(text);
      return renderedText.replace('Replace me', 'Got replaced');
    }
  },
  dontPrompt: true
}

Runtime args

You may have noticed that although the runtimeArg argument has a type of string, it's default value is a function! This is a special type of argument called a runtime argument. It means that the value for that argument will be generated at runtime after the user has been prompted for all other arguments. This way, you can provide a value based on what everything else is set to. An argument is a runtime argument if it has a function for a default value but it's type isn't function.

Now that you understand how arguments work with Cyto, let's generate the cyto-arguments template!

> cyto gen cyto-arguments LookAtTheArguments
? stringArg: I'm a string
? booleanArg:  Yes
? listArg:  'hello', world
> cat demo.txt
test
Generated by: Connor Taylor

I'm a string

The boolean arg was set to true!

'hello'
world


The text after the colon will be replaced: Got replaced

stringArg was set to I'm a string

I think you're starting to get the hang of it :)