Config

Configuration Files

GLI has built-in support for configuration files for your application. The configuration file essentially stores command line option values to use as defaults when not specified by the user.

Example

In your main bin file, add:

config_file '.yourapp.rc'

This will create a new command called initconfig that will create an initial version of the configuration file. Suppose your application's UI looks like this:

NAME
    todo - manage a todo list

SYNOPSIS
    todo command [options]

GLOBAL OPTIONS 
    -f, --filename=full path to file - Specify the location of the todo txt file
                                       (default: /Users/davec/.todo.txt)
    --password=password              - Password for ticketing system
    -u, --url=url                    - URL to ticketing system XML-RPC endpoint
    --username=username              - Username for ticketing system

SCOMMANDS
    done       - Complete one or more todo items, removing them from the list
    help       - Shows list of commands or help for one command
    initconfig - Initialize the config file using current global options
    list       - List todo items
    new        - Create a new todo item

When you run

> todo -u http://jira.mycompany.org --password=supersecret --username=davec initconfig

GLI will create the configuration file such that the next time you run todo, the values for -u, --password, and --username will be defaulted to the values you specified when you ran initconfig. Of course, you can edit this file to make changes; it's just a simple YAML file.

The location of the file depends on the value you give it. If it starts with a /, that will be treated as the absolute path to the configuration file. If not, the file will be located in the user's home directory based on the value of the HOME environment variable.

Option Value Precedence

The search order for the value of a particular flag then becomes:

1. Command line invocation
2. Configuration File value
3. Default value in the application

In GLI 1.x, there was no way to switch off a switch, so if your app has a switch, say --verbose, you could turn it on in the config file, but not off. In GLI 2, switches are negetable, so you can specify true or false in the config file, and that value will be used at runtime.

In other words:

:verbose: false

Has the same effect as --no-verbose on the command-line.

File Format

The configuration file format is YAML-based and can be edited easily in a text editor. Note that initconfig creates a blank area for each command to your application, and you can customize defaults for those commands as well.

    --- 
    # Global options are here
    :f: foo
    :g: blah
    # Command-specific options are under 'commands'
    commands: 
      # defaults for the "doit" command
      :doit: 
        :g: bar
        :s: true
      # defaults for the "gonow" command
      :gonow: 
        :g: foobar
        :f: barfoo

Note that you can nest these to match your commands' subcommands, just as you'd expect.

Effect on Application Design

The way the config file works implies a particular design for your application. Namely, it encourages you to make every bit of user-controllable behavior into a command line switch or flag. The config file can then be tweaked by users to contain the defaults they want, if those don't mesh with the ones you provide.