-*- 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