Build interactive config-based command-line interfaces with JavaScript :wink:

Table of Contents

• Install
• Usage
  • As a global dependency
  • As a local dependency
• Configuration
• Prompts
  • Input prompts.input()
  • Fuzzy path search prompts.fuzzyPath()
  • Choices prompts.choices()
  • Multi choices prompts.multiChoices()
• Actions
  • Print message actions.printMessage()
  • Spawn actions.spawn()
• Build your own binary

Install

npm install garson

Usage

As a global dependency

Run:

npx garson

This command will look for garson.config.js file in the current directory. You can change the default path with --config option.

See npx garson --help for a full list of options.

As a local dependency

Create a script in package.json:

{
  "scripts": {
    "garson": "garson --config=./path-to/garson.config.js"
  }
}

Now you can run npm run garson.

Configuration

A garson.conf.js file should export a garson object, which is represented by a chain of prompts that ends with an action:

const { garson, prompts, actions } = require('garson');

module.exports = garson()
  .prompt(/* some prompt */)
  .action(/* some action  */);

There could be many prompts, but they must end with a single action:

const { garson, prompts, actions } = require('garson');

module.exports = garson()
  .prompt(/* some prompt */)
  .prompt(/* another prompt */)
  .prompt(/* one more prompt */)
  .action(/* the only action  */); // you can't chain anything to .action()

It's possible to return another garson object from the action callback:

const { garson, prompts, actions } = require('garson');

const branchA = garson()
  .prompt(/* branch A prompt */)
  .action(/* branch A action */);

const branchB = garson()
  .prompt(/* branch B prompt */)
  .action(/* branch B action */);

module.exports = garson()
  .prompt(/* prompt */)
  .action(results => {
    if (results.someKey) {
      return branchA; // will show branch A prompt and then branch A action
    } else {
      return branchB; // will show branch B prompt and then branch B action
    }
  });

Prompts

Each .prompt() takes two arguments:

1. prompt key
2. prompt object

Prompt key is needed to define a property in the result object which is passed into an action callback. Prompt objects defines a type of a prompt.

Input prompts.input()

Provides a text input.

Example:

// garson.config.js
const { garson, prompts, actions } = require('garson');

module.exports = garson()
  // first prompt
  .prompt(
    'firstName',
    prompts.input({
      message: "What's your first name?",
      placeholder: 'E.g. John',
    })
  )
  // second prompt
  .prompt(
    'lastName',
    prompts.input({
      message: "What's your last name?",
      placeholder: 'E.g. Smith',
    })
  )
  // final action
  .action(results => {
    // note the keys of the result object
    const { firstName, lastName } = results;
    actions.printMessage({ message: `Hello, ${firstName} ${lastName}` });
  });

Fuzzy path search prompts.fuzzyPath()

Provides a fuzzy search for a file or a folder in a specified directory.

Example:

// garson.config.js
const { garson, prompts, actions } = require('garson');

const cwd = '/Users/goliney/Workspace/garson/src';
module.exports = garson()
  .prompt(
    'file',
    prompts.fuzzyPath({
      message: 'Enter file:',
      pattern: '**',
      options: {
        nodir: true,
        cwd,
      },
    })
  )
  .action(results => {
    const { file } = results;
    actions.spawn(`nano ${cwd}/${file.path}`);
  });

Choices prompts.choices()

Allows to select a value from the list.

Example:

// garson.config.js
const { garson, prompts, actions } = require('garson');

module.exports = garson()
  .prompt(
    'command',
    prompts.choices({
      message: 'What git command you want to run?',
      items: [
        { label: 'See current branch', value: 'git branch' },
        { label: 'Checkout to master', value: 'git checkout master' },
        { label: 'See status', value: 'git status' },
      ],
    })
  )
  .action(results => {
    const { command } = results;
    actions.spawn(command, { showCommand: true });
  });

Multi choices prompts.multiChoices()

Allows to select multiple values from the list.

Example:

// garson.config.js
const { garson, prompts, actions } = require('garson');

module.exports = garson()
  .prompt(
    'wcOptions',
    prompts.multiChoices({
      message: 'What do you want to count in garson.config.js file?',
      items: [
        { label: 'Lines', value: 'l', isSelected: true },
        { label: 'Words', value: 'w', isSelected: true },
        { label: 'Characters', value: 'm' },
        { label: 'Everything', value: 'lwm', isSelected: false },
      ],
      // optional handler
      onChangeMiddleware(newItems, oldItems, allItems) {
        const isEverything = item => item.value === 'lwm';
        const newItemsHaveEverythingSelected = newItems.some(isEverything);
        const oldItemsHaveEverythingSelected = oldItems.some(isEverything);

        if (newItemsHaveEverythingSelected && !oldItemsHaveEverythingSelected) {
          // if "Everything" just got selected, deselect everything else
          return allItems.filter(isEverything);
        }

        if (oldItemsHaveEverythingSelected) {
          // if "Everything" was selected, deselect it
          return newItems.filter(item => !isEverything(item));
        }

        return newItems;
      },
    })
  )
  .action(results => {
    const { wcOptions } = results;
    const options = wcOptions.length ? `-${wcOptions.join('')}` : '';
    actions.spawn(`wc ${options} ./examples/multi-choices/garson.config.js`);
  });

Actions

The action takes a single argument - a callback which is invoked with the results of all the prompts that were already shown.

It's up to you to decide what to do next with the result data. Since it's JavaScript environment, your further actions are limited only by Node.

For your convenience garson is shipped with a couple of actions that might get handy.

Print message actions.printMessage()

Shows a text message on the screen.

Example:

// garson.config.js
const { garson, prompts, actions } = require('garson');

module.exports = garson()
  .prompt('name', prompts.input({ message: 'Name:' }))
  .action(results => {
    actions.printMessage({
      boxTitle: 'Greetings',
      message: `Hello, ${results.name}`
    });
  });

Spawn actions.spawn()

A wrapper over Node's spawn. It can get handy when you want to run a command in the terminal.

actions.spawn accepts two arguments:

1. A mandatory command string
2. An optional spawn options objects. See spawn docs for a full list of parameters. Optionally, you can set { showCommand: true } to see the command before executing it.

Example:

// garson.config.js
const { garson, prompts, actions } = require('garson');

module.exports = garson()
  .prompt(
    'command',
    prompts.choices({
      items: [
        { label: 'See current path', value: 'pwd' },
        { label: 'See current folder content', value: 'ls -al' }
      ]
    })
  )
  .action(results => {
    actions.spawn(results.command, { showCommand: true });
  });

Build your own binary

If you want to build your own binary on top of garson, you can use runner:

#!/usr/bin/env node
const { runner, garson, prompts, actions } = require('garson');

const config = garson()
  .prompt(/* config prompts */)
  .action(/* config actions */);

runner(config);