                                                              -*- org -*-
#+TITLE: Guile Config NEWS – history of user-visible changes
#+STARTUP: content hidestars

Copyright © 2018,2020,2021 Alex Sassmannshausen <alex@komputilo.eu>

  Copying and distribution of this file, with or without modification,
  are permitted in any medium without royalty provided the copyright
  notice and this notice are preserved.

Please send Guile Config bug reports to alex@komputilo.eu.

* Changes in 0.5.0 (since 0.4.2)

** API BREAKAGE: The semantics of keywords and arguments

   The semantics of keywords and arguments have changed somewhat in relation
   to how to declare them mandatory or optional. This may well cause issues
   with programs that currently use a version of guile config < 0.5.0. The
   programs will error out with a config error message.

   Fixes will generally be very easy — feature parity exists, and if anything,
   the config DSL has become more expressive.

   Breaking backward compatibility is always horrible, and I do it with heavy
   heart, but I believe this breakage is part of config's road to 1.0.

   You can read updated documentation in the manual (consult sections on
   switches, settings and arguments. You can also consult the issue 16 at
   https://gitlab.com/a-sassmannshausen/guile-config/-/issues/16

   Specifically the changes relate to the use of the default, test and
   optional? fields. The latter in particular has been removed from
   arguments.

   Please contact me if you run into problems and need help!

** Handling invocation of the same keyword multiple times

   Thanks to Rekado's suggestions we now have an additional field for switches
   and settings: merge-strategy. This field allows you to specify the
   behaviour that should occur when the same keyword is used multiple times
   when invoking your program.

   Using this you might be able to implement, for instance
   $ frobnigator -v -v -v
   to set verbosity to level 3.

** Complex option dependencies

   Traditionally, the test field is populated with a simple predicate that
   accepts one argument, the value as supplied on the command line, after it
   was processed by the handler.

   I have now re-written the tests functionality. You can, in addition to
   old-school predicates, now populate the field with procedures that two
   arguments. The second argument will be the entire codex, with all value
   populated from configuration files and the commandline, after the handler
   has processed them, but before they were tested.

   In this way you can inspect this codex, and keywords / arguments to create
   complex dependency graphs between the individual options.

   For instance, you might have an argument, filename, that only makes sense
   when a category is also provided, or when neither is provided. You can now,
   in the test for filename, inspect the codex to ensure that category was
   also provided.

** Custom error messages

   A new keyword / argument field, error, allows you to specify custom error
   handlers for your keywords or arguments. If you do not provide a custom
   error handler, then the new and improved default handler will be used.

   Of course you can use custom error handlers for nicer error messages to
   your end-user. But you might also use them to run arbitrary custom logic.

   Please consult the manual for details of how to use these!

* Changes in 0.4.2 (since 0.4.1)

** Use a locale independent regex range in `getopt-config-auto'

   Aleix first reported an issue whereby getopt-config-auto would fail due to
   a locale dependent regex that specified [a-Z].  Aleix also provided a fix,
   which changed this to [a-zA-Z].

* Changes in 0.4 (since 0.3.1)

** Improve documentation: explain `full-command'

   Rekado pointed out that `full-command' was currently not documented.  This
   is now fixed.

** Provide better error messages for end user

   This affects both validation error messages when someone runs a program
   using guile-config and handling of the --help message in the face of
   validation errors or missing mandatory fields.

* Changes in 0.3 (since 0.2 [undocumented here])

** Use Guile Hall to manage project infrastructure.
** Settings are now no longer run through handlers.
   It is expected the parser ensures settings from commandlines have the
   correct type.  They are still run against tests.
** Configuration Files are assumed to provide mandatory arguments.
   If they are not provided they will resolve to <empty> when they are first
   accessed.
** Ensure we run handlers over arguments on command-line.
** We support single-configuration files for an entire program space.
** The sexp-parser now provides a single-configuration file variant.
