gli 1.0.0 → 1.1.0

data/README.rdoc

@@ -47,6 +47,14 @@ This sets a description of your program.  This can be as long as you want.
 
     program_description 'Support program for bootstrapping GLI-based programs'
 
+This sets a config file for your program.  The config file can be used to store default values for command
+line options and command-specific options on a per-user (or per-site) basis.  The format is YAML-based.  
+Using an absolute path will result in the configuraiton file being located there.  Without an absolute path,
+the file will be located relative to the current user's home directory (which is what is being done here).
+
+    config_file '.glirc'
+
+the configuration file 
 This describes a command line switch "-n" that is global to all commands and specified before
 the command name on the command line.
 
@@ -128,11 +136,50 @@ What this doesn't give you:
 * A way to indicate a required argument or required number of arguments
 * A way to do default switches to 'true' and therefore accept things like <tt>--no-force</tt>
 
+== Configuration File
+
+The configuration file format is a very simple means of customizing the execution of your command on a per-user
+or per-site basis.  The idea is that commonly used values that aren't the commands' default can be stored in the configuration
+file so that users do not need to specify them on the command line.  The search order for the value of a particular
+flag then becomes:
+
+1. Command line invocation
+2. Configuration File value
+3. Default value in the application
+
+Note that since there is no way to switch _off_ switches, setting them to default to true in the configuration file
+cannot be "undone" on the command line.  A future version may allow this.
+
+The configuration file format is YAML based and can be bootstrapped via the +initconfig+ command to your application.  
+This command is automatically created and added to your application's commands when you declare that there is a 
+config file.  When invoked, all global options set on the command line are configured 
+inside the configuration file.  Further, a blank area for each
+command of your application is created, to allow the user edit the config file  ith command-specific default values.
+
+    --- 
+    # Global options are here
+    :f: foo
+    :g: blah
+    # Command-specific options are under 'commands'
+    commands: 
+      # defaults for the "doit" command
+      :doit: 
+        :g: bar
+        :s: true
+      # defaults for the "gonow" command
+      :gonow: 
+        :g: foobar
+        :f: barfoo
+
+This allows you to design your application to have it's behavior _entirely_ affected by command line options, with sensible
+defaults stored in a configuration file.
+
 == Reference
 
 
 [+action+] Specify the action to take when a command is executed from the command line.  This is only usable in a command block on the command object (e.g. <tt>c.action</tt>).  This takes a block that yields three parameters: a hash of global options specified on the commandline, a hash of command-specific options specified on the command line, and an array of arguments parsed after the options were set on the command line.  So, a command like <tt>git --git-dir=/tmp commit -a -m 'Foo bar' foo.c bar.c</tt> would result in the global hash containing <tt>:'git-dir' => '/tmp'</tt>, the options hash containing <tt>:a => true, :m => 'Foo bar'</tt> and the arguments array being <tt>['foo.c', 'bar.c']</tt>
 [+arg_name+] Describe the name of the argument to the next flag or command.  This can be used at the global level or inside a command block on the command object (e.g. <tt>c.arg_name</tt>)
+[+config_file+] Name the configuration file for your applicaiton.  This can either be an absolute path to where the applicaiton will find the configuration file, or a relative path, that will be interpretted as relative to the user's home directory.  Default is +nil+, which means no configuration file will be used.  Declaring this creates a special +initconfig+ command that can bootstrap this configuration file for your users.
 [+command+] Declare a command.  This takes a symbol or array of symbols and a block.  The block yields one argument, the command itself.  
 [+default_value+] Indicate the default value of the next flag.  This can be used at the global level or inside a command block on the command object (e.g. <tt>c.default_value</tt>)
 [+desc+] Describe the next flag, switch, or command you will declare.  This can be used at the global level or inside a command block on the command object (e.g. <tt>c.desc</tt>)

data/lib/gli.rb

@@ -5,6 +5,8 @@ require 'gli/flag.rb'
 require 'gli/options.rb'
 require 'support/help.rb'
 require 'support/rdoc.rb'
+require 'support/initconfig.rb'
+require 'etc'
 
 # A means to define and parse a command line interface that works as
 # Git's does, in that you specify global options, a command name, command
@@ -12,18 +14,20 @@ require 'support/rdoc.rb'
 module GLI
   extend self
 
-  VERSION = '0.3.0'
+  VERSION = '1.0.0'
 
   @@program_name = $0.split(/\//)[-1]
   @@post_block = nil
   @@pre_block = nil
   @@error_block = nil
+  @@config_file = nil
 
   # Reset the GLI module internal data structures; mostly for testing
   def reset
     switches.clear
     flags.clear
     commands.clear
+    @@config_file = nil
     clear_nexts
   end
 
@@ -54,6 +58,18 @@ module GLI
     clear_nexts
   end
 
+  # Sets the config file.  If not an absolute path
+  # sets the path to the user's home directory
+  def config_file(filename)
+    if filename =~ /^\//
+      @@config_file = filename
+    else
+      @@config_file = Etc.getpwuid.dir + '/' + filename
+    end
+    commands[:initconfig] = InitConfig.new(@@config_file)
+    @@config_file
+  end
+
   # Define a command.
   def command(*names)
     command = Command.new([names].flatten,@@next_desc,@@next_arg_name,@@next_long_desc)
@@ -93,7 +109,8 @@ module GLI
     commands[:rdoc] = rdoc if !commands[:rdoc]
     commands[:help] = DefaultHelpCommand.new(rdoc) if !commands[:help]
     begin
-      global_options,command,options,arguments = parse_options(args)
+      config = parse_config
+      global_options,command,options,arguments = parse_options(args,config)
       proceed = true
       proceed = @@pre_block.call(global_options,command,options,arguments) if @@pre_block 
       if proceed
@@ -111,6 +128,16 @@ module GLI
     end
   end
 
+  def parse_config
+    return nil if @@config_file.nil?
+    require 'yaml'
+    if File.exist?(@@config_file)
+      File.open(@@config_file) { |f| YAML::load(f) }
+    else
+      {}
+    end
+  end
+
   def program_name(override=nil)
     if override
       @@program_name = override
@@ -123,8 +150,14 @@ module GLI
   #  * Command 
   #  * command options (as a Hash)
   #  * arguments (as an Array)
-  def parse_options(args)
-    global_options,command,options,arguments = parse_options_helper(args.clone,Options.new,nil,Options.new,Array.new)
+  def parse_options(args,config=nil)
+    command_configs = {}
+    if config.nil?
+      config = {}
+    else
+      command_configs = config.delete(GLI::InitConfig::COMMANDS_KEY) if !config.nil?
+    end
+    global_options,command,options,arguments = parse_options_helper(args.clone,config,nil,Options.new,Array.new,command_configs)
     flags.each { |name,flag| global_options[name] = flag.default_value if !global_options[name] }
     command.flags.each { |name,flag| options[name] = flag.default_value if !options[name] }
     return [global_options,command,options,arguments]
@@ -164,6 +197,7 @@ module GLI
   # [command] the Command that has been identified (or nil if not identified yet)
   # [command_options] options for Command
   # [arguments] the arguments for Command
+  # [command_configs] the configuration file for all commands, used as defaults
   #
   # This works by finding the first non-switch/flag argument, and taking that sublist and trying to pick out
   # flags and switches.  After this is done, one of the following is true:
@@ -176,7 +210,7 @@ module GLI
   #
   # Once the command has been found, we start looking for command-specific flags and switches.
   # When those have been found, we know the rest of the argument list is arguments for the command
-  def parse_options_helper(args,global_options,command,command_options,arguments)
+  def parse_options_helper(args,global_options,command,command_options,arguments,command_configs)
     non_flag_i = find_non_flag_index(args)
     all_flags = false
     if non_flag_i == 0
@@ -185,7 +219,12 @@ module GLI
         command_name = args.shift
         command = find_command(command_name)
         raise "Unknown command '#{command_name}'" if !command
-        return parse_options_helper(args,global_options,command,command_options,arguments)
+        return parse_options_helper(args,
+                                    global_options,
+                                    command,
+                                    default_command_options(command,command_configs),
+                                    arguments,
+                                    command_configs)
       else
         return global_options,command,command_options,arguments + args
       end
@@ -224,7 +263,7 @@ module GLI
       return [global_options,command,command_options,arguments] if rest.empty?
       # If we have no more options we've parsed them all
       # and rest may have more
-      return parse_options_helper(rest,global_options,command,command_options,arguments)
+      return parse_options_helper(rest,global_options,command,command_options,arguments,command_configs)
     else
       if command
         check = rest
@@ -245,12 +284,21 @@ module GLI
         command = find_command(command_name)
         raise "Unknown command '#{command_name}'" if !command
 
-        return parse_options_helper(rest,global_options,command,command_options,arguments)
+        return parse_options_helper(rest,
+                                    global_options,
+                                    command,
+                                    default_command_options(command,command_configs),
+                                    arguments,
+                                    command_configs)
       end
     end
 
   end
 
+  def default_command_options(command,command_configs)
+    options = (command_configs && command_configs[command.name.to_sym]) || {}
+  end
+
   def find_command(name)
     sym = name.to_sym
     return commands[name.to_sym] if commands[sym]

data/lib/support/initconfig.rb

@@ -0,0 +1,35 @@
+require 'gli'
+require 'gli/command'
+require 'yaml'
+
+module GLI
+  class InitConfig < Command
+    COMMANDS_KEY = 'commands'
+
+    def initialize(config_file_name)
+      @filename = config_file_name
+      super(:initconfig,"Initialize the config file using current global options",nil,'Initializes a configuration file where you can set default options for command line flags, but globally and on a per-command basis.  These defaults override the built-in defaults and allow you to omit commonly-used command line flags when invoking this program')
+
+      self.desc 'force overwrite of existing config file'
+      self.switch :force
+    end
+
+    def execute(global_options,options,arguments)
+      if options[:force] || !File.exist?(@filename)
+        config = global_options
+        config[COMMANDS_KEY] = {}
+        GLI.commands.each do |name,command|
+          if (command != self) && (name != :rdoc) && (name != :help)
+            config[COMMANDS_KEY][name.to_sym] = {} if command != self
+          end
+        end
+        File.open(@filename,'w') do |file|
+          YAML.dump(config,file)
+        end
+      else
+        puts "Not overwriting existing config file #{@filename}"
+        puts 'Use --force to override'
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: gli
 version: !ruby/object:Gem::Version 
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors: 
 - David Copeland
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-19 00:00:00 -05:00
+date: 2009-12-24 00:00:00 -05:00
 default_executable: 
 dependencies: []
 
@@ -32,6 +32,7 @@ files:
 - lib/support/help.rb
 - lib/support/rdoc.rb
 - lib/support/scaffold.rb
+- lib/support/initconfig.rb
 - bin/gli
 - README.rdoc
 - gli.rdoc