Help Text

Sywac is able to automatically generate help text for your program based on the configured expected input. While you can customize every part of it (or even completely override it), sywac aims to build beautiful and useful help text by default.

Triggering

The output of help text is triggered in one of four ways:

1. By configuring a help option/command for your program and then running your program with that option/command as an argument e.g. program --help
2. By configuring your program to show help by default and then running your program without any arguments (or, for command-driven programs, without specifying a runnable command) e.g. program
3. By running your program in a way that causes a validation error e.g. without a required argument
4. By calling the .getHelp(opts) method anywhere in your program

In the first three scenarios, the rendered help text is exposed via the result.output string from the parse method, which your program can display to the user. If your program is a CLI and uses the parseAndExit method instead, the help text will be printed to stdout automatically for these three scenarios.

In the fourth scenario, the .getHelp(opts) method returns the help text as a string directly.

The following section takes a closer look at what exactly the help text consists of.

Parts

The generated help text consists of the following sections, each separated by an empty line (i.e. by two line feeds, \n\n):

1. The preface (logo and slogan)
2. The usage block
3. Ordered groups of commands, arguments, and flagged options
4. Ordered examples
5. The epilogue
6. Any validation error messages

Here’s a complete example:

$ sygit remote remove
                     .__  __   
  _________.__. ____ |__|/  |_
 /  ___<   |  |/ ___\|  \   __\
 \___ \ \___  / /_/  >  ||  |  
/____  >/ ____\___  /|__||__|  
     \/ \/   /_____/           
Like git, but better!

Usage: sygit remote remove  [options]

Arguments:
  <name>  Name of the remote to remove      [required] [string]

Remote Options:
  -v, --verbose  Show remote url after name           [boolean]

Global Options:
  --help     Show help               [commands: help] [boolean]
  --version  Show version number  [commands: version] [boolean]

Examples:
  Remove the remote named upstream
  $ sygit remote remove upstream

  Remove the remote named origin
  $ sygit remote remove origin

This program demonstrates how to use sywac

Missing required argument: name

The first section is the preface, which includes the ASCII art logo and the “Like git, but better!” slogan.

The second section is the usage block, which is a single line showing the “Usage” synopsis. This is auto-generated by sywac, but you can also choose to customize each part of it or completely override it with your own string.

The “Arguments”, “Remote Options”, and “Global Options” make up the third section, showing flags, description, and hints for each argument or option, grouped via common heading. In this example, “Arguments” was defined by sywac, and the other two headings were defined by the program configuration.

The “Examples” make up the fourth section, with its own heading, showing description (if any) and command per given example.

The epilogue string “This program demonstrates how to use sywac” makes up the fifth section.

And, finally, the last line is a validation error message, which is the sixth section.

Let’s go over these in detail.

Preface

You probably put a lot of work into your program - why not give it a logo, perhaps with some ASCII art via figlet and some color via chalk? And what’s a logo without a slogan?

const figlet = require('figlet')

require('sywac')
  .preface(figlet.textSync('sygit', 'Graffiti'), 'Like git, but better!')
  .help().outputSettings({ maxWidth: 50 }).parseAndExit()

$ sygit --help
                     .__  __   
  _________.__. ____ |__|/  |_
 /  ___<   |  |/ ___\|  \   __\
 \___ \ \___  / /_/  >  ||  |  
/____  >/ ____\___  /|__||__|  
     \/ \/   /_____/           
Like git, but better!

Usage: sygit [options]

Options:
--help  Show help     [commands: help] [boolean]

Unless you call the preface method, no preface will be included in help text.

For command-driven apps, if you wish to show a preface at the top-level but not for each command, overwrite the preface in the top-level commands. (Needs example!)

Usage

The usage block is included by default and will be auto-generated by sywac, tailoring its content based on what’s available or expected at each command level. There are 3 different parts built into the usage string:

1. Usage prefix

   This is Usage: $0 by default. The $0 will be replaced by the program name and any commands for the current level.

2. Expected arguments

   If positional arguments are defined for the current command level, then the explicit flags/placeholders for those arguments will be used here.

   Otherwise, if additional commands/subcommands are available (i.e. if “Commands” are listed in the third section of help text), a generic command placeholder will be used. The default generic command placeholder is <command>.

   If the generic command placeholder is used and at least one of the available commands/subcommands includes its own positional arguments, then an args placeholder will be appended to the command placeholder. The default value for this is <args>.

3. Generic options placeholder

   This will only be used if there are any flagged options available at the current command level or above (i.e. if “Options” are listed in the third section of help text). The default value is [options].

Each part of the auto-generated usage string can be customized via an object passed to the usage configuration method.

// only do this to override defaults
sywac.usage({
  prefix: 'Usage:\n  $0',      // add a line feed to default
  commandPlaceholder: '<cmd>', // shorter than default
  argsPlaceholder: '[args]',   // square brackets instead of lt/gt
  optionsPlaceholder: '[opts]' // shorter than default
})

However, if you would like to disable the auto-generated usage string and define your own, just pass a string to the usage configuration method.

// only do this to define your own usage string
sywac.usage('Usage: program # anything you want here')

Note that each part of the generated usage string also has its own style hook which you can use to customize colors or content in any way. See Style Hooks for more info.

Commands, Arguments, and Options

Needs content

Sorry! This site is still under construction. Please bear with us until we can fill out more documentation. Thank you!

Examples

Needs content

Sorry! This site is still under construction. Please bear with us until we can fill out more documentation. Thank you!

Epilogue

Needs content

Sorry! This site is still under construction. Please bear with us until we can fill out more documentation. Thank you!

Validation error messages

Needs content

Sorry! This site is still under construction. Please bear with us until we can fill out more documentation. Thank you!

Customization

Needs content

Sorry! This site is still under construction. Please bear with us until we can fill out more documentation. Thank you!