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:

usage: todo command [options]

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

Commands:
    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

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 Etc.getpwuid.dir.

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

Note that since there is no way to switch off switches, setting them to default to true in the configuration file cannot be "undone" on the command line. A future version may allow this.

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

Application Design

The way the config file works implies a particular design for your application. Namely, it allows 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.