www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.announce - D Configuration Framework (alias Program Options)

reply Marcin Kuszczak <aarti_nospam please_interia.pl> writes:
Hello all D fans!

I would like to announce completely rewritten and reworked program options
library. This is beta release, but should be rather stable for everyday
use. You can find source code and download package on project page:
http://www.dsource.org/projects/doost/wiki

----

Program options library is intended to make managing of configuration in D
programs easy. Instead of reinventing the wheel and implementing same parts
of program to manage configuration over and over again, it is possible now
to use library with simple API for common tasks. Common tasks with managing
program configuration include: reading configuration options from physicall
media, saving them back, presenting description of available options to
user, checking for incorrect usage, working with different sources of
options, checking option values for validity, synchronizing with physicall
media etc.

Main goal for this release was to make library usage very easy for common
use cases. Other goal was to make it easy to implement new physicall
backends for storing options and also to make source code and usage of
library more D-like.

To achieve above goals I changed architecture of previous version, so it is
currently based on concept of root access class to options (ProgramOptions
class) and different classes which define specific backends (e.g.
CommandLineStorage, ConfigFileStorage). Standard way to access options is
through root class (ProgramOptions), which is searching then for concrete
options in stacked physicall storages. From library user point of view
interface to options is similar to interface of associative arrays.

New library has gain several abilities which were not available in original:
        * possibility to store options in backends
        * available storages: CommandLineStorage, ConfigFileStorage, 
          EnvironmentStorage, DbStorage (using ddbi)
        * interfacing to whole stack (ProgramOptions) and every concrete storage
        * easy method to add new backends using [read|save]Physically[One|All] 
          methods
        * stacking of options backends
        * removed possibility to store values into concrete variables (it was 
          insecure)
        * notification about option changes (it is possible to register for 
          specific events)
        * easy synchronization of options with backends using synchronize()
method
        * different synchronization methods: direct or cached
        * interface to stack of options similar to associative arrays
        * possibility to have many stacks of options in program (ProgramOptions
is 
          not singleton)
        * custom file loaders and savers with simple ones set by default
        * possibility to compose one option which is defined in different
storages 
          into one value
        * generalization of short option, which now is just alias for normal
option
        * reading/storing lists in  backends (with user defined separators)
        * support for escape sequences
        * easy initialization of options stack, with no temporary variables
        * checking for options integrity (not possible to define same option
twice 
          in storage, option type must be same in whole stack)
        * Tango-like structure of directories + naming convention similar to
other 
          D programs
        * built-in regular expressions for option values
        * user defined formatters for options
        * special types of options: SelfName, SelfDir, SelfPath, RegExpOptions
and 
          possibility to create user defined options
        * reworked positional options in CommandLineStorage (currently it is 
          special type option)
        * built-in response files support for CommandLineStorage
        * functions for checking for obligatory options, conflicting options
and 
          dependant options
        * comments for DDoc
        * unit tests
        * many smaller improvements and bugfixes

Below you can find simplest usage example for command line:

----------8<----------

import doost.util.config.ProgramOptions;
import doost.util.config.CommandLineStorage;

void main(char[][] args) {
  //Definition of simplest options stack
  auto po = (new ProgramOptions)
                .next(
            (new CommandLineStorage(args))
                .caption("Command line options")
                .options()
                  ("help,h", "produce help message")
                  ("compression", define!(int), "set compression level")
                  ("sync", "stores cmdline options in persistent backend")
                  ()
            );

  //Conecting to storages
  po.connect();

  //Reading options
  if ("help" in po) writefln(po);
  if ("compression" in po)      
        writefln("Compresson level set to: ", po["compression"].as!(uint));

  //Disconnecting storages
  po.disconnect;
}
 
---------->8----------
 
*A lot of different examples for different storages you can find in file:
examples/util/config/FunctionTest.d.*

Currently there are following backends defined for program options:
CommandLineStorage      -       handles command line options
ConfigFileStorage       -       handles options from ini-like files
EnvironmentStorage      -       handles options from environment variables
DbStorage               -       handles options from database through ddbi
interface

-------

Although it is beta release (so architecture of library is considered to be
finished) I am open to discuss and eventually change parts of program in
case there are good arguments supporting changes. 

I will be happy to get feedback from you. You can find few things to
consider in file doc/todo.txt. You can also write other physicall backends
to library. If you want I can host them in doost svn.

Also as I am not native English-speaker, I would appreciate help with
improving documentation and corrections for misspelled words. You can send
patches or just send me an e-mail.

I hope anyway you will like what you get :-) Have a fun!

-- 
Regards
Marcin Kuszczak (Aarti_pl)
-------------------------------------
Ask me why... I believe in Jesus - http://www.zapytajmnie.com (en/pl)
Doost (port of few Boost libraries) - http://www.dsource.org/projects/doost/
-------------------------------------
Oct 08 2007
next sibling parent Robert Fraser <fraserofhenight gmail.com> writes:
Marcin Kuszczak Wrote:

 Hello all D fans!
 
 I would like to announce completely rewritten and reworked program options
 library. This is beta release, but should be rather stable for everyday
 use. You can find source code and download package on project page:
 http://www.dsource.org/projects/doost/wiki
 
 ----
 
 Program options library is intended to make managing of configuration in D
 programs easy. Instead of reinventing the wheel and implementing same parts
 of program to manage configuration over and over again, it is possible now
 to use library with simple API for common tasks. Common tasks with managing
 program configuration include: reading configuration options from physicall
 media, saving them back, presenting description of available options to
 user, checking for incorrect usage, working with different sources of
 options, checking option values for validity, synchronizing with physicall
 media etc.
 
 Main goal for this release was to make library usage very easy for common
 use cases. Other goal was to make it easy to implement new physicall
 backends for storing options and also to make source code and usage of
 library more D-like.
 
 To achieve above goals I changed architecture of previous version, so it is
 currently based on concept of root access class to options (ProgramOptions
 class) and different classes which define specific backends (e.g.
 CommandLineStorage, ConfigFileStorage). Standard way to access options is
 through root class (ProgramOptions), which is searching then for concrete
 options in stacked physicall storages. From library user point of view
 interface to options is similar to interface of associative arrays.
 
 New library has gain several abilities which were not available in original:
         * possibility to store options in backends
         * available storages: CommandLineStorage, ConfigFileStorage, 
           EnvironmentStorage, DbStorage (using ddbi)
         * interfacing to whole stack (ProgramOptions) and every concrete
storage
         * easy method to add new backends using [read|save]Physically[One|All] 
           methods
         * stacking of options backends
         * removed possibility to store values into concrete variables (it was 
           insecure)
         * notification about option changes (it is possible to register for 
           specific events)
         * easy synchronization of options with backends using synchronize()
method
         * different synchronization methods: direct or cached
         * interface to stack of options similar to associative arrays
         * possibility to have many stacks of options in program
(ProgramOptions is 
           not singleton)
         * custom file loaders and savers with simple ones set by default
         * possibility to compose one option which is defined in different
storages 
           into one value
         * generalization of short option, which now is just alias for normal
option
         * reading/storing lists in  backends (with user defined separators)
         * support for escape sequences
         * easy initialization of options stack, with no temporary variables
         * checking for options integrity (not possible to define same option
twice 
           in storage, option type must be same in whole stack)
         * Tango-like structure of directories + naming convention similar to
other 
           D programs
         * built-in regular expressions for option values
         * user defined formatters for options
         * special types of options: SelfName, SelfDir, SelfPath, RegExpOptions
and 
           possibility to create user defined options
         * reworked positional options in CommandLineStorage (currently it is 
           special type option)
         * built-in response files support for CommandLineStorage
         * functions for checking for obligatory options, conflicting options
and 
           dependant options
         * comments for DDoc
         * unit tests
         * many smaller improvements and bugfixes
 
 Below you can find simplest usage example for command line:
 
 ----------8<----------
 
 import doost.util.config.ProgramOptions;
 import doost.util.config.CommandLineStorage;
 
 void main(char[][] args) {
   //Definition of simplest options stack
   auto po = (new ProgramOptions)
                 .next(
             (new CommandLineStorage(args))
                 .caption("Command line options")
                 .options()
                   ("help,h", "produce help message")
                   ("compression", define!(int), "set compression level")
                   ("sync", "stores cmdline options in persistent backend")
                   ()
             );
 
   //Conecting to storages
   po.connect();
 
   //Reading options
   if ("help" in po) writefln(po);
   if ("compression" in po)      
         writefln("Compresson level set to: ", po["compression"].as!(uint));
 
   //Disconnecting storages
   po.disconnect;
 }
  
 ---------->8----------
  
 *A lot of different examples for different storages you can find in file:
 examples/util/config/FunctionTest.d.*
 
 Currently there are following backends defined for program options:
 CommandLineStorage      -       handles command line options
 ConfigFileStorage       -       handles options from ini-like files
 EnvironmentStorage      -       handles options from environment variables
 DbStorage               -       handles options from database through ddbi
interface
 
 -------
 
 Although it is beta release (so architecture of library is considered to be
 finished) I am open to discuss and eventually change parts of program in
 case there are good arguments supporting changes. 
 
 I will be happy to get feedback from you. You can find few things to
 consider in file doc/todo.txt. You can also write other physicall backends
 to library. If you want I can host them in doost svn.
 
 Also as I am not native English-speaker, I would appreciate help with
 improving documentation and corrections for misspelled words. You can send
 patches or just send me an e-mail.
 
 I hope anyway you will like what you get :-) Have a fun!
 
 -- 
 Regards
 Marcin Kuszczak (Aarti_pl)
 -------------------------------------
 Ask me why... I believe in Jesus - http://www.zapytajmnie.com (en/pl)
 Doost (port of few Boost libraries) - http://www.dsource.org/projects/doost/
 -------------------------------------
 

Wow, I was thinking about how useful this would be. Very, very awesome! Any chance of a Tango port?
Oct 08 2007
prev sibling next sibling parent reply Robert Fraser <fraserofhenight gmail.com> writes:
Marcin Kuszczak Wrote:

 Hello all D fans!
 
 I would like to announce completely rewritten and reworked program options
 library. This is beta release, but should be rather stable for everyday
 use. You can find source code and download package on project page:
 http://www.dsource.org/projects/doost/wiki
 
 ----
 
 Program options library is intended to make managing of configuration in D
 programs easy. Instead of reinventing the wheel and implementing same parts
 of program to manage configuration over and over again, it is possible now
 to use library with simple API for common tasks. Common tasks with managing
 program configuration include: reading configuration options from physicall
 media, saving them back, presenting description of available options to
 user, checking for incorrect usage, working with different sources of
 options, checking option values for validity, synchronizing with physicall
 media etc.
 
 Main goal for this release was to make library usage very easy for common
 use cases. Other goal was to make it easy to implement new physicall
 backends for storing options and also to make source code and usage of
 library more D-like.
 
 To achieve above goals I changed architecture of previous version, so it is
 currently based on concept of root access class to options (ProgramOptions
 class) and different classes which define specific backends (e.g.
 CommandLineStorage, ConfigFileStorage). Standard way to access options is
 through root class (ProgramOptions), which is searching then for concrete
 options in stacked physicall storages. From library user point of view
 interface to options is similar to interface of associative arrays.
 
 New library has gain several abilities which were not available in original:
         * possibility to store options in backends
         * available storages: CommandLineStorage, ConfigFileStorage, 
           EnvironmentStorage, DbStorage (using ddbi)
         * interfacing to whole stack (ProgramOptions) and every concrete
storage
         * easy method to add new backends using [read|save]Physically[One|All] 
           methods
         * stacking of options backends
         * removed possibility to store values into concrete variables (it was 
           insecure)
         * notification about option changes (it is possible to register for 
           specific events)
         * easy synchronization of options with backends using synchronize()
method
         * different synchronization methods: direct or cached
         * interface to stack of options similar to associative arrays
         * possibility to have many stacks of options in program
(ProgramOptions is 
           not singleton)
         * custom file loaders and savers with simple ones set by default
         * possibility to compose one option which is defined in different
storages 
           into one value
         * generalization of short option, which now is just alias for normal
option
         * reading/storing lists in  backends (with user defined separators)
         * support for escape sequences
         * easy initialization of options stack, with no temporary variables
         * checking for options integrity (not possible to define same option
twice 
           in storage, option type must be same in whole stack)
         * Tango-like structure of directories + naming convention similar to
other 
           D programs
         * built-in regular expressions for option values
         * user defined formatters for options
         * special types of options: SelfName, SelfDir, SelfPath, RegExpOptions
and 
           possibility to create user defined options
         * reworked positional options in CommandLineStorage (currently it is 
           special type option)
         * built-in response files support for CommandLineStorage
         * functions for checking for obligatory options, conflicting options
and 
           dependant options
         * comments for DDoc
         * unit tests
         * many smaller improvements and bugfixes
 
 Below you can find simplest usage example for command line:
 
 ----------8<----------
 
 import doost.util.config.ProgramOptions;
 import doost.util.config.CommandLineStorage;
 
 void main(char[][] args) {
   //Definition of simplest options stack
   auto po = (new ProgramOptions)
                 .next(
             (new CommandLineStorage(args))
                 .caption("Command line options")
                 .options()
                   ("help,h", "produce help message")
                   ("compression", define!(int), "set compression level")
                   ("sync", "stores cmdline options in persistent backend")
                   ()
             );
 
   //Conecting to storages
   po.connect();
 
   //Reading options
   if ("help" in po) writefln(po);
   if ("compression" in po)      
         writefln("Compresson level set to: ", po["compression"].as!(uint));
 
   //Disconnecting storages
   po.disconnect;
 }
  
 ---------->8----------
  
 *A lot of different examples for different storages you can find in file:
 examples/util/config/FunctionTest.d.*
 
 Currently there are following backends defined for program options:
 CommandLineStorage      -       handles command line options
 ConfigFileStorage       -       handles options from ini-like files
 EnvironmentStorage      -       handles options from environment variables
 DbStorage               -       handles options from database through ddbi
interface
 
 -------
 
 Although it is beta release (so architecture of library is considered to be
 finished) I am open to discuss and eventually change parts of program in
 case there are good arguments supporting changes. 
 
 I will be happy to get feedback from you. You can find few things to
 consider in file doc/todo.txt. You can also write other physicall backends
 to library. If you want I can host them in doost svn.
 
 Also as I am not native English-speaker, I would appreciate help with
 improving documentation and corrections for misspelled words. You can send
 patches or just send me an e-mail.
 
 I hope anyway you will like what you get :-) Have a fun!
 
 -- 
 Regards
 Marcin Kuszczak (Aarti_pl)
 -------------------------------------
 Ask me why... I believe in Jesus - http://www.zapytajmnie.com (en/pl)
 Doost (port of few Boost libraries) - http://www.dsource.org/projects/doost/
 -------------------------------------
 

Wow, I was thinking about how useful this would be. Very, very awesome! Any chance of a Tango port?
Oct 08 2007
parent Aarti_pl <aarti interia.pl> writes:
Robert Fraser pisze:
  > Wow, I was thinking about how useful this would be. Very, very 
awesome! Any chance of a Tango port?

Thanks!

Porting to Tango is on my TODO list, but unfortunately my spare time is 
very limited, so I can't tell any specific date.

Anyway I think (not tested) that using Tangobos should be enough to work 
with program options library in Tango.

BR
Marcin Kuszczak
(aarti_pl)
Oct 09 2007
prev sibling parent reply Bill Baxter <dnewsgroup billbaxter.com> writes:
Marcin Kuszczak wrote:
 import doost.util.config.ProgramOptions;
 import doost.util.config.CommandLineStorage;
 
 void main(char[][] args) {
   //Definition of simplest options stack
   auto po = (new ProgramOptions)
                 .next(
             (new CommandLineStorage(args))
                 .caption("Command line options")
                 .options()
                   ("help,h", "produce help message")
                   ("compression", define!(int), "set compression level")
                   ("sync", "stores cmdline options in persistent backend")
                   ()
             );
 
   //Conecting to storages
   po.connect();
 
   //Reading options
   if ("help" in po) writefln(po);
   if ("compression" in po)      
         writefln("Compresson level set to: ", po["compression"].as!(uint));
 
   //Disconnecting storages
   po.disconnect;
 }

Nice updates. The example above doesn't work for me. I get a runtime error to the tune of """ Error: AssertError Failure f:/usr/pkg/d/dsss/bin\..\include\d\doost\core\Any.d(121) Error: type of value (int) is different than requested (uint). """ But it does seem to work if I change the define!(int) to define!(uint). Also on the web page it said po[["compression"]]. But I went ahead and fixed that since it's a wiki. :-) [http://www.dsource.org/projects/doost/wiki/ProgramOptions] I didn't fix the int/uint thing on the wiki page because it seems that's maybe something you think should work? --bb
Oct 09 2007
parent Aarti_pl <aarti interia.pl> writes:
Bill Baxter pisze:
 Nice updates.  The example above doesn't work for me.  I get a runtime 
 error to the tune of
 """
 Error: AssertError Failure 
 f:/usr/pkg/d/dsss/bin\..\include\d\doost\core\Any.d(121) Error: type of 
 value (int) is different than requested (uint).
 """
 
 
 But it does seem to work if I change the define!(int) to define!(uint).
 
 Also on the web page it said po[["compression"]].  But I went ahead and 
 fixed that since it's a wiki. :-) 
 [http://www.dsource.org/projects/doost/wiki/ProgramOptions]
 
 I didn't fix the int/uint thing on the wiki page because it seems that's 
 maybe something you think should work?
 
 --bb

Different types in definition and when getting value of option is a mistake - Any doesn't implement implicit conversions. But in fact when printing value of variable it is not necessary to use as!() template function. Any container has it's toString() method, so it is just enough to print value using: writefln(po["compression"]); It's a good lesson that every example should be compiled before posting :D PS. Thanks to all for help with docs! BR Marcin Kuszczak (aarti_pl)
Oct 10 2007