-*- mode: org -*-

Guile Config is a library providing a declarative approach to application
configuration specification.  The library provides clean configuration
declaration forms, and processors that take care of:

- Configuration file creation
- Configuration file parsing
- Command-line parameter parsing using getopt-long
- Basic GNU command-line parameter generation (--help, --usage, --version)
- Output generation for (compiled from the configuration declaration):
  + --help and --usage
  + --version
- Automatic deduction of short-versions of argument names
- Support for arbitrarily nested subcommands
- Support for keyword parameters as well as positional parameters

* Specification

  Guile Config expects a <configuration> as an input.  <configuration>s are a
  recursive data type that contains configuration specifications for your
  application.  The library will parse the specification, create configuration
  files as needed, parse them, and finally generate a <codex>.

  <codex>es are record types that can be interacted with in a very similar way
  as the interface provided by `getopt-long` (i.e. option-ref).

* Flow of Control

      +---------------------------------------+                                                                      
      |                                       |                                                                      
      |    +-----------------------------+    |                                                                      
      |    | Configuration Specification |    | Developer Time                                                       
      |    +-----------------------------+    |                                                                      
      |                   |                   |                                                                      
      +---------------------------------------+                                                                      
                          |                                                                                          
  +----------------------------------------------------------------------------------------------------+             
  |                       |                                                                            |             
  |            +--------------------+                                                                  |             
  |            | Generate Codex for |                                                                  |             
  |            | invoked subcommand |                                                                  |
  |            +--------------------+                                                                  |             
  |                       |                                                                            |             
  |                       |                                                                            |             
  |          +---------------------------+                                                             |             
  |          | Write eager configuration |                                                             |             
  |          |          files            |                                                             |             
  |          +---------------------------+                                                             |             
  |                       |                                                                            |             
  |                       |                                                                            |             
  |             +---------------------+     Error in options                            auto-help?     |             
  |             | Parse all existing  |                         +-------------------+                  |             
  |             | configuration files |-------------------------| Emit error message| ------|          |             
  |             +---------------------+                         +-------------------+       |          |             
  |                       |                                                |          +-----------+    |             
  |                       |                                                |          | Emit Help |    | Run Time    
  |              +-------------------+                                     |          +-----------+    |             
  |              |  Generate final   |                            +----------------+        |          |             
  |              |      codex        |                            | Exit with error|--------|          |             
  |              | (resolve options) |                            +----------------+                   |             
  |              +-------------------+                                                                 |             
  |                       |                                                                            |             
  |                       |                                                                            |             
  |           |-----------|-----------|                                                                |             
  |           |  Help? & auto-help?   |                                                                |             
  |           |                       |                                                                |             
  |    +-----------------+      +-----------+                                                          |             
  |    | Pass control to |      | Emit Help |                                                          |             
  |    |      program    |      +-----------+                                                          |             
  |    +-----------------+            |                                                                |             
  |                                   |                                                                |             
  |                                +------+                                                            |             
  |                                | Exit |                                                            |             
  |                                +------+                                                            |             
  |                                                                                                    |             
  +----------------------------------------------------------------------------------------------------+             
 
* Objects Overview

  - User Interface (high level):
    + configuration
    + secret
    + switch
    + setting
    + argument
    + license
    + parser
    + path

  - Internal
    + codex
      * metadata
      * features
      * values

* User Interface Objects

** <configuration>                  | (guix records)
   - name                           | symbol
   - synopsis                       | string
   - description                    | string
   - keyword-parameters             | list[<secret> <switch> <setting>]
   - positional-parameters          | list[<argument>]
   - subcommands                    | list[<configuration>]
   - directory                      | list[<path>] || <path>
   - generate-help?                 | boolean[#t]
   - generate-usage?                | boolean[#t]
   - generate-version?              | boolean[#t]
   - version                        | string
   - license                        | <license>
   - copyright                      | list[number]
   - author                         | string
   - parser                         | <parser>
   - alias                          | symbol

** <secret>                         | (guix records)
   - name                           | symbol
   - value                          | mixed
   - synopsis                       | string

** <setting>                        | (guix records)
   - name                           | symbol
   - value                          | mixed
   - test                           | predicate
   - handler                        | proc(string -> mixed)
   - character                      | char
   - synopsis                       | string
   - description                    | string
   - example                        | string
   - optional                       | boolean[#t]

** <switch>                         | (guix records)
   - name                           | symbol
   - value                          | mixed
   - test                           | predicate
   - handler                        | proc(string -> mixed)
   - character                      | char
   - synopsis                       | string
   - description                    | string
   - example                        | string
   - optional                       | boolean[#t]

** <argument>                       | (guix records)
   - name                           | symbol
   - value                          | mixed
   - test                           | predicate
   - handler                        | proc(string -> mixed)
   - synopsis                       | string
   - description                    | string
   - example                        | string
   - optional                       | boolean[#f]

** <license>                        | (srfi srfi-9)
   - id                             | symbol
   - name                           | string
   - url                            | uri

** <parser>                         | (srfi srfi-9)
   - id                             | symbol
   - reader                         | proc(IO[in] -> <fileconfig>)
   - writer                         | proc(<flatconfig> -> IO[out])

** <path>                           | (guix records)
   - given                          | string
   - eager?                         | boolean[#t]

* Internal Objects

** <codex>                          | (srfi srfi-9)
   - <features>
     + name
     + synopsis
     + description
     + alias
     + subcommands
   - <metadata>
     + directory
     + version
     + license
     + copyright
     + author
     + parser
     + generate-help?
     + generate-usage?
     + generate-version?
     + generate-cmdtree?
   - <valus>
     + keyword-parameters
     + arguments
   - <reagents>
     + inverted
     + commandline
     + raw
     + configuration
