configurable 0.7.0 → 1.0.0

data/Help/Command Line.rdoc

@@ -0,0 +1,141 @@
+= Command Line Usage
+
+Configurable guesses a command-line option for each config, based on the
+config name (ex: --name for :name, -n for :n) and the default value. Flags,
+switches, list configs, and nested configs are all supported.
+
+  class ConfigClass
+    include Configurable
+    config :flag, false    # a flag
+    config :switch, true   # an on/off switch
+    config :num, 3.14      # a number
+    config :lst, [1,2,3]   # a list of integers
+    config :nest do
+      config :str, 'one'   # a string
+    end
+  end
+
+Options can be parsed at the class level:
+
+  parser  = ConfigClass.configs.to_parser
+  parser.parse("a --flag --no-switch --num 6.02 b c") do |args, config|
+    args      
+    # => ['a', 'b', 'c']
+    
+    config 
+    # => {
+    # :flag   => true, 
+    # :switch => false,
+    # :num    => 6.02,
+    # :lst    => [1, 2, 3], 
+    # :nest   => {:str => 'one'}
+    # }
+  end
+
+Or at the instance level:
+
+  c = ConfigClass.new
+  c.config.parse('a --lst 7 --lst 8,9 --nest:str=two b c')
+  # => ['a', 'b', 'c']
+  
+  c.config.to_hash
+  # => {
+  # :flag   => false, 
+  # :switch => true,
+  # :num    => 3.14,
+  # :lst    => [7, 8, 9], 
+  # :nest   => {:str => 'two'}
+  # }
+
+A description string is extracted from the comment trailing a config
+declaration, such that a help is readily available.
+
+  stdout = []
+  c.config.parse('--help') do |psr|
+    psr.on('--help', 'print this help') do 
+      stdout << "options:"
+      stdout << psr
+    end
+  end
+  
+  "\n" + stdout.join("\n")
+  # => %q{
+  # options:
+  #         --flag                       a flag
+  #         --help                       print this help
+  #         --lst LST...                 a list of integers (1,2,3)
+  #         --nest:str STR               a string (one)
+  #         --num NUM                    a number (3.14)
+  #         --[no-]switch                an on/off switch
+  # }
+  
+To specify alternative long/short options, or a different argument name, use a
+prefix section in the description.
+
+  class AltClass
+    include Configurable
+    config :a, nil   # -a, --aaa ARGNAME  : cmdline options may be
+    config :b, nil   # -b                 : declared in the docs
+    config :c, nil   #     --ccc          : using a prefix
+    config :d, nil   #                    : an empty prefix implies 'hidden'
+    config :e, nil   # no prefix uses the defaults
+    config :f, nil   # -f [OPTIONAL]      : bracket argname means 'optional'
+    
+    config :g, []    # -g, --ggg LIST     : same rules for list opts
+    config :nest do
+      config :i, nil # -i, --iii NEST     : and same for nested opts
+    end
+  end
+
+  stdout = []
+  AltClass.configs.to_parser do |psr|
+    psr.on('-h', '--help', 'print this help') do 
+      stdout << "options:"
+      stdout << psr
+    end
+  end.parse('--help')
+
+  "\n" + stdout.join("\n")
+  # => %q{
+  # options:
+  #     -a, --aaa ARGNAME                cmdline options may be
+  #     -b B                             declared in the docs
+  #         --ccc C                      using a prefix
+  #     -e E                             no prefix uses the defaults
+  #     -f [OPTIONAL]                    bracket argname means 'optional'
+  #     -g, --ggg LIST...                same rules for list opts
+  #     -h, --help                       print this help
+  #     -i, --iii NEST                   and same for nested opts
+  # }
+
+If necessary you can specify all aspects of an option manually:
+
+  class ManualClass
+    include Configurable
+    config :key, nil, {
+      :long     => 'long',
+      :short    => 's',
+      :arg_name => 'ARGNAME',
+      :desc     => 'summary',
+      :hint     => 'hint',
+      :optional => false,
+      :hidden   => false
+    }
+  end
+  
+  stdout = []
+  ManualClass.configs.to_parser do |psr|
+    psr.on('-h', '--help', 'print this help') do 
+      stdout << "options:"
+      stdout << psr
+    end
+  end.parse('--help')
+
+  "\n" + stdout.join("\n")
+  # => %q{
+  # options:
+  #     -h, --help                       print this help
+  #     -s, --long ARGNAME               summary (hint)
+  # }
+
+See the {ConfigParser}[http://rubygems.org/gems/config_parser] documentation for more details.

data/Help/Config Syntax.rdoc

@@ -0,0 +1,229 @@
+= Config Syntax
+
+Declare configurations by key, and provide a default value. Declaring a config
+generates accessors with the same name and sets up access through config.
+
+  class ConfigClass
+    include Configurable
+    config :str, 'one'
+  end
+
+  c = ConfigClass.new
+  c.str                      # => 'one'
+  c.str = 'two'
+  c.config[:str]             # => 'two'
+  c.config[:str] = 'three'
+  c.str                      # => 'three'
+  c.config.to_hash           # => {:str => 'three'}
+
+== Initialization
+
+Call initialize_config during initialization to setup config with non-default
+values.
+
+  class InitClass
+    include Configurable
+    config :str, 'one'
+    
+    def initialize(configs={})
+      initialize_config(configs)
+    end
+  end
+  
+  c = InitClass.new(:str => 'two')
+  c.str                      # => 'two'
+
+== Key/Name
+
+Configs have both a key and a name. The key may be any object and provides
+access to a configuration in config. The name must be a string and an ordinary
+word. Name used gets used wherever a word-based-identifier is needed, for
+instance when creating accessors.
+
+By default name is key.to_s. When key converts into an illegal name, or when
+you want a different name, specify it manually.
+
+  class KeyNameClass
+    include Configurable
+    config :key, 'val', :name => 'name'
+  end
+
+  c = KeyNameClass.new
+  c.name                     # => 'val'
+  c.config[:key]             # => 'val'
+
+== Reader/Writer
+
+Specify a reader and/or writer to map configs to alternative accessors. When
+you specify a reader or writer you must define the corresponding method
+yourself, even if you specify default accessors (ie 'name' and 'name='). The
+reader takes no arguments and the writer takes the input value.
+
+  class ReaderWriterClass
+    include Configurable
+    config :str, 'one', :reader => :get, :writer => :set
+    
+    def get
+      @ivar
+    end
+    
+    def set(value)
+      @ivar = value
+    end
+  end
+
+  c = ReaderWriterClass.new
+  c.get                      # => 'one'
+  c.set 'two'
+  c.config[:str]             # => 'two'
+  c.config[:str] = 'three'
+  c.get                      # => 'three'
+  c.config.to_hash           # => {:str => 'three'}
+
+Note that Configurable doesn't care how the data is stored on an instance.
+
+== Import/Export
+
+Configs may be imported/exported between the active objects used by an
+instance and the static data used by textual interfaces like config files, the
+command-line, and web forms.
+
+After import, configs are composed of key-value pairs of arbitrary class (ex a
+symbol key and a string value). After export, configs are composed of
+name-input pairs which must be directly serializable as JSON (ex a string name
+and a string input).
+
+Import/export can occur at the class level:
+
+  configs = KeyNameClass.configs
+  defaults = configs.to_default
+  defaults                   # => {:key => 'val'}
+
+  static_data = configs.export(defaults)
+  static_data                # => {'name' => 'val'}
+
+  active_hash = configs.import({'name' => 'VAL'})
+  active_hash                # => {:key => 'VAL'}
+
+Or the instance level:
+
+  c = KeyNameClass.new
+  c.config.to_hash           # => {:key => 'val'}
+  c.config.export            # => {'name' => 'val'}
+
+  c.config.import({'name' => 'VAL'})
+  c.config.to_hash           # => {:key => 'VAL'}
+
+Configurable supports import/export of basic types (boolean, integer, float,
+string, array, and hash). See later documentation to set up custom config
+types.
+
+== Lists
+
+When an array of values is given as the default value, config will construct a
+list-style configuration. The syntax and usage is no different than any other
+config, except that type information is expected to be preserved across all
+members of the array (ie an array-of-strings, array-of-integers, etc).
+
+  class ListClass
+    include Configurable
+    config :integers, [1, 2, 3]
+  end
+  
+  c = ListClass.new
+  c.integers                 # => [1, 2, 3]
+  c.config.import('integers' => ['7', '8'])
+  c.config[:integers]        # => [7, 8]
+
+== Nesting
+
+Configurable classes may be nested to represent a hash within a hash. To
+construct a nested class, provide a hash default of key-value pairs, a block
+defining the nested class, or an instance of the nested class.
+
+  class Parent
+    include Configurable
+    
+    config :a, {:key => 'hash'}
+    
+    config :b do
+      config :key, 'block'
+    end
+    
+    class Child
+      include Configurable
+      config :key, 'instance'
+    end
+    config :c, Child.new
+  end
+
+  c = Parent.new
+  c.config.to_hash
+  # => {
+  #  :a => {:key => 'hash'},
+  #  :b => {:key => 'block'},
+  #  :c => {:key => 'instance'}
+  # }
+
+Nest configs are structured to provide clean access to the nested configurable
+through the accessors and config:
+
+  c.a.key                    # => 'hash'
+  c.config[:a][:key]         # => 'hash'
+  c.config[:a][:key] = 'HASH'
+  c.a.key                    # => 'HASH'
+  c.a.config.to_hash         # => {:key => 'HASH'}
+
+Instances of the nested class can be directly assigned, or they can be
+initialized via config. Nested classes generated by the config method are
+assigned to a constant based on the config name.
+
+  c.a = Parent::A.new
+  c.config[:a]               # => {:key => 'hash'}
+  c.config[:a] = {:key => 'HASH'}
+  c.a.config.to_hash         # => {:key => 'HASH'}
+
+Import/export of nested classes occurs seamlessly:
+
+  c.config.import('b' => {'key' => 'BLOCK'})
+  c.config.export
+  # => {
+  #  'a' => {'key' => 'HASH'},
+  #  'b' => {'key' => 'BLOCK'},
+  #  'c' => {'key' => 'instance'}
+  # }
+  
+== Inheritance
+
+Configurations can be inherited, overridden, declared in modules, and
+generally treated like methods.
+
+  class A
+    include Configurable
+    config :a, 'one'
+  end
+  
+  module B
+    include Configurable
+    config :b, 'two'
+  end
+  
+  class C < A
+    include B
+    config :c, 'three'
+  end
+  
+  c = C.new
+  c.a                   # => 'one'
+  c.b                   # => 'two'
+  c.c                   # => 'three'
+  c.config.to_hash      # => {:a => 'one', :b => 'two', :c => 'three'}
+  
+  class D < C
+    config :a, 'ONE'
+    undef_config :c
+  end
+  
+  d = D.new
+  d.respond_to?(:c)     # => false
+  d.config.to_hash      # => {:a => 'ONE', :b => 'two'}

data/Help/Config Types.rdoc

@@ -0,0 +1,143 @@
+== Config Types
+
+Configs have two conceptual parts; a config class that determines how to map
+config values between various contexts, and a config type that determines how
+to cast config values. Configurable provides support for basic types (ex
+booleans, numbers, strings) and a syntax to declare custom types.
+
+Custom types are declared using the config_type method. The config method then
+matches the default against all available config types to guess the type for
+the new configuration.
+
+  require 'time'
+  
+  now = Time.now
+  class TimeExample
+    include Configurable
+    
+    config_type :time, Time do |input|
+      Time.parse(input)
+    end.uncast do |value|
+      time.strftime('%Y-%m-%d %H:%M:%S')
+    end
+    
+    config :obj, now
+  end
+  
+  c = TimeExample.new
+  c.obj                             # => now
+  
+  c.config.import('obj' => 'Sun Dec 05 16:52:19 -0700 2010')
+  c.obj.strftime('%Y-%m-%d')        # => '2010-12-05'
+  
+  c.config.export
+  # => {'obj' => '2010-12-05 16:52:19'}
+
+Config types define how to cast/uncast values during import/export. The type
+is free to determine how to do so, so long as the uncast value can be cleanly
+serialized as JSON. This is also possible:
+
+  class RangeExample
+    include Configurable
+  
+    config_type(:range, Range) do |input|
+      Range.new(
+        input['begin'], 
+        input['end'],
+        input['exclusive']
+      )
+    end.uncast do |value|
+      { 
+        'begin'     => value.begin,
+        'end'       => value.end,
+        'exclusive' => value.exclude_end?
+      }
+    end
+  
+    config :obj, 1..10
+  end
+  
+  c = RangeExample.new
+  c.obj                             # => 1..10
+  
+  c.config.import('obj' => {'begin' => 2, 'end' => 20, 'exclusive' => false})
+  c.obj                             # => 2..20
+  
+  c.obj = 3...30
+  c.config.export
+  # => {'obj' => {'begin' => 3, 'end' => 30, 'exclusive' => true}}
+
+The config_type method defines a type class, which is set to a constant
+according to the type name.
+
+  config = RangeExample.configs[:obj]
+  config.type.class                 # => RangeExample::RangeType
+
+== Matching/Inheritance
+
+Upon declaration the config type for a config is guessed by matching the
+default against all available types. Matching walks up the inheritance
+hierarchy to find a match if necessary, and stops when a match is found. An
+error is raised if more than one type matches for a given ancestor; in that
+case the type must be specified manually.
+
+  class A
+    include Configurable
+    config_type :datetime, Date, Time, DateTime
+    config :a, Time.now     # matches :datetime type
+  end
+  
+  class B < A
+    config_type :time, Time
+    
+    config :b, Time.now     # matches :time type
+    config :c, Date.today   # skips :time, walks up to match :datetime
+  end
+  
+  class C < B
+    config_type :date1, Date
+    config_type :date2, Date
+    
+    config :d, Date.today, :type => :date1  # manually specify which to match;
+    config :e, Date.today, :type => :date2  # ambiguous type will raise error
+  end
+  
+  configs = C.configs
+  configs[:a].type.class          # => A::DatetimeType
+  configs[:b].type.class          # => B::TimeType
+  configs[:c].type.class          # => A::DatetimeType
+  configs[:d].type.class          # => C::Date1Type
+  configs[:e].type.class          # => C::Date2Type
+
+For nest configs defined from a block or hash, config types are guessed in the
+context of the parent (although config_types defined in a nested child do not
+bleed back up).
+
+  class Parent
+    include Configurable
+    config_type :datetime, Time, Date
+    
+    config :a, {:b => Time.now}
+    config :c do
+      config_type :time, Time
+      
+      config :d, Time.now
+      config :e, Date.today
+    end
+    config :f, Date.today
+  end
+  
+  configs = Parent.configs
+  configs[:a].type.class          # => Configurable::ConfigTypes::NestType
+  configs[:c].type.class          # => Configurable::ConfigTypes::NestType
+  configs[:f].type.class          # => Parent::DatetimeType
+  
+  a_configs = configs[:a].type.configurable.class.configs
+  a_configs[:b].type.class        # => Parent::DatetimeType
+  
+  c_configs = configs[:c].type.configurable.class.configs
+  c_configs[:d].type.class        # => Parent::C::TimeType
+  c_configs[:e].type.class        # => Parent::DatetimeType
+
+Aside from direct inheritance, config_types may be overridden, declared in
+modules, and handled as if they were methods.