optiflag 0.6

data/ReleaseNotes.txt

@@ -0,0 +1,110 @@
+---------------------------------------------------------------------------------
+RELEASE 0.6  (Character Flags FINALLY)
+---------------------------------------------------------------------------------
+   * added top-level flag declaration 'character_flag'
+   * made 'keyword' an optional by default
+
+---------------------------------------------------------------------------------
+RELEASE 0.5  (Features getting close to done)
+---------------------------------------------------------------------------------
+   * added top-level flag declaration 'keyword'
+   * added unit test for this new functionality
+   * added automatically generated ?methods? for
+     alternate forms of flags 
+   * made sure not to try generating methods
+     from non alphabetic flag names 
+   * Added ability to acces values via hash lookup
+     (see Example 4)
+
+---------------------------------------------------------------------------------
+RELEASE 0.4  (Internal Maintenance Mainly)
+---------------------------------------------------------------------------------
+   * Added internal version number
+   * Addded experimental ability to define flags off of the fields of a
+     pre-existing object.  Some problems with visibility will keep this 
+     experimental for now. See the method using_object 
+   * Spelling fix ups
+   * Aliased flag_properties to properties.  For ease of use.
+   * Added some large section-defining comments
+   * Renamed internal EachFlag variables from 'foo_val' to 'the_foo'
+   * Coined terminology for Application Programmer's Syntax
+       -- Top-Level Flag Declarers
+       -- Clause-Level Flag Modifier
+
+---------------------------------------------------------------------------------
+RELEASE 0.3
+---------------------------------------------------------------------------------
+   * Fixed a bug that globally changed the state of all modules
+     when a user chose to use the 
+     'module SomeThing extend OptiFlag::Flagset(:flag_symbol => "/")'
+     syntax.  Required some singleton class trickeration and module cloning.
+   * Changed all references from OptiFlag::FlagestDefinitions to 
+     OptiFlag::Flagset which is shorter and therefore easier to use 
+     (not everyone has dynamic-abbrev in emacs enabled to make typing easy)
+   * Started changing the design of printing help so that users can 
+     register help-formatting bundles to do their own rendering of usage 
+     and error messages
+   * Changed the functionality of the 'usage_flag' option to be of 
+     either zero or one arity.  With standard zero arity, the help will
+     print out the standard help/usage message.  With an arity of one,
+     the help/usage flag will assume that the argument is another flag
+     for which we will print extended usage  (example: '-h dir' will print 
+     the help message just for the '-dir' flag)
+   * Fixed another nasty global-state bug (the perils of using '@' syntax 
+     with modules)... This one wasn't needed -- it would only affect those
+     people who chose to parse an array of strings a 2nd and 3rd time, and
+     I was considering mandating that the parse method could only be called
+     once... but since my tests relied on multiple parses, I decided to fix
+     it just to make the test suites continually easy to write.
+   * Added a new top-level declarative form: 'optional_switch_flag' which
+     is an optional flag with zero arity. (I needed this one for myself)
+   * A few more tests were added: 
+        -- tc_basic_optional_flag.rb
+        -- tc_bug_two.rb
+   * Wrote some XSLT and a ruby-script to autogenerate the site at 
+     http://optiflag.rubyforge.org
+   * Added a warning generation system for things that are not errors
+        -- extra parameters left over (implemented)
+        -- potential consumption of an optional flag as value 
+           to a flag with >0 arity. (example: '-dir -verbose' where
+           '-dir' takes on argument and '-verbose' is optional. In this
+           case the '-verbose' would be consumed as the value unless
+           warning mode was on)       
+
+
+---------------------------------------------------------------------------------
+RELEASE 0.2            (5/23/2006)
+---------------------------------------------------------------------------------
+   * The following features are implemented:
+       * required and optional flags
+       * ability to change flag arity from 0 to N
+       * flag value validation
+           -- by set membership
+           -- by regular expression
+       * flag value translation (pre and post validation)
+       * auto help
+       * auto error checking
+       * usage and extended usage flags
+       * universal flag symbol change
+       * case by case flag symbol change (both normal and long form)
+       * alternate forms for normal flag
+       * alternate form for long form flag
+       * auto-generated property-type methods added to ARGV for 
+         flag values post-parsing
+       * sub-clause verbs
+           -- 'description'
+           -- 'arity'
+           -- 'no_args'
+           -- 'one_arg'
+           -- 'two_args'
+           -- 'long_form'
+           -- 'translate'
+           -- 'value_matches'
+           -- 'value_in_set'
+           -- 'required'
+           -- 'optional'
+           -- 'alternate_forms'
+           -- 'long_form'
+           -- 'dash_symbol'
+           -- 'long_dash_symbol'
+   * Added a series of Example Files   

data/doc/example/example_1.rb

@@ -0,0 +1,30 @@
+require 'optiflag'
+
+# Example 1:  Four required flags
+module Example extend OptiFlag::Flagset
+  flag "dir"
+  flag "log"
+  flag "username"
+  flag "password"
+end 
+
+result = Example::parse(ARGV)
+if result.errors?
+  result.errors.divulge_problems
+  exit
+end
+
+# Some code to _use_ the values
+puts "User has input:#{ result.flag_value.dir  } for dir"
+puts "User has input:#{ result.flag_value.log  } for log"
+puts "User has input:#{ result.flag_value.username  } for username"
+puts "User has input:#{ result.flag_value.password  } for password"
+
+puts "The variable 'result' is actually just a copy of ARGV"
+puts "that has been extend to hold the return variables:"
+puts "See:  #{ result.join(', ') }"
+
+
+# Try the following inputs
+#   ruby example_1.rb
+#h#   ruby example_1.rb -log logdirectory -dir directory -username me -password fluffy

data/doc/example/example_1_1.rb

@@ -0,0 +1,27 @@
+require 'optiflag'
+
+# Example 1.1:  
+#   Variation 1:  add a method 'handle_errors_and_help' to autoparse, check, and augment ARGV
+module Example extend OptiFlag::Flagset
+  flag "dir"
+  flag "log"
+  flag "username"
+  flag "password"
+
+  handle_errors_and_help
+end 
+
+# Some code to _use_ the values
+puts "User has input:#{ ARGV.flag_value.dir  } for dir"
+puts "User has input:#{ ARGV.flag_value.log  } for log"
+puts "User has input:#{ ARGV.flag_value.username  } for username"
+puts "User has input:#{ ARGV.flag_value.password  } for password"
+
+puts " The variable ARGV has been extend to hold the return variables."
+
+# Try the following inputs
+## Breaks:
+#h#   ruby example_1_1.rb
+## Works:
+#h#   ruby example_1_1.rb -log logdirectory -dir directory -username me -password fluffy
+#   ruby example_1_1.rb --log logdirectory --dir directory --username me --password fluffy

data/doc/example/example_1_2.rb

@@ -0,0 +1,28 @@
+require 'optiflag'
+
+# Example 1.2:  
+#   Variation 2: Changing the universal short-form default symbol from '-' to '/'
+module Example extend OptiFlag::Flagset(:flag_symbol => "/")
+  flag "dir"
+  flag "log"
+  flag "username"
+  flag "password"
+
+  handle_errors_and_help
+end 
+
+# Some code to _use_ the values
+puts "User has input:#{ ARGV.flag_value.dir  } for dir"
+puts "User has input:#{ ARGV.flag_value.log  } for log"
+puts "User has input:#{ ARGV.flag_value.username  } for username"
+puts "User has input:#{ ARGV.flag_value.password  } for password"
+
+
+# Try the following inputs
+## Breaks:
+#   ruby example_1_2.rb
+#h#   ruby example_1_2.rb -log logdirectory -dir directory -username me -password fluffy  
+## Works:
+#h#   ruby example_1_2.rb /log logdirectory /dir directory /username me /password fluffy
+#   ruby example_1_2.rb --log logdirectory --dir directory --username me --password fluffy
+#h#   ruby example_1_2.rb --log logdirectory /dir directory --username me /password fluffy

data/doc/example/example_2.rb

@@ -0,0 +1,28 @@
+require 'optiflag'
+$log = "c:/log"
+
+# Example 2:  Adding an optional flag and a usage flag
+module Example extend OptiFlag::Flagset
+  flag "dir"
+  optional_flag "log"
+  flag "username"
+  flag "password"
+  usage_flag "h","help","?"
+
+  handle_errors_and_help
+end 
+
+if ARGV.flag_value.log?  # note the question mark '?'
+  $log = ARGV.flag_value.log
+  puts "User input: #{ $log } for log via the command-line"
+else
+  puts "User did NOT input log via the command-line"
+end
+
+#h#   ruby example_2.rb --dir directory --username me --password fluffy
+#h#   ruby example_2.rb --dir directory --username me --password fluffy --log c:/tmp/log
+#   ruby example_2.rb -dir directory -username me -password fluffy -log c:/tmp/log
+#h#   ruby example_2.rb -h 
+#h#   ruby example_2.rb -?
+#   ruby example_2.rb -help
+

data/doc/example/example_2_1.rb

@@ -0,0 +1,23 @@
+require 'optiflag'
+
+# Example 2.1:  
+#  Variation 1:  Using an extended usage flag
+module Example extend OptiFlag::Flagset
+  flag "dir"
+  optional_flag "log"
+  flag "username"
+  flag "password"
+  usage_flag "h","help","?"
+  extended_help_flag "superhelp"
+
+  handle_errors_and_help
+end 
+
+#h#   ruby example_2_1.rb -superhelp --dir directory --username me --password fluffy
+#   ruby example_2_1.rb -superhelp --dir directory --username me --password fluffy
+#   ruby example_2_1.rb -superhelp --dir directory --username me --password fluffy
+#   ruby example_2_1.rb -superhelp --dir directory --username me
+#   ruby example_2_1.rb -superhelp --dir directory
+#   ruby example_2_1.rb -superhelp 
+#h#   ruby example_2_1.rb --superhelp
+

data/doc/example/example_2_2.rb

@@ -0,0 +1,31 @@
+require 'optiflag'
+
+# Example 2.2:  
+#  Variation 2:  Adding descriptions to the flags (will appear in extended help)
+### NOTE how 'description' can be nested in a block or used as a symbol key
+module Example extend OptiFlag::Flagset
+  flag "dir" do 
+    description "The Appliction Directory"
+  end
+  optional_flag "log" do
+    description "The directory in which to find the log files"
+  end
+  flag "username", :description => "Database username."  # alternate form
+  flag "password" do
+    description "Database password."
+  end
+  usage_flag "h","help","?"
+  extended_help_flag "superhelp"
+
+  handle_errors_and_help
+end 
+
+## Works (triggers extended help):
+#   ruby example_2_2.rb -superhelp --dir directory --username me --password fluffy
+#   ruby example_2_2.rb -superhelp --dir directory --username me --password fluffy
+#   ruby example_2_2.rb -superhelp --dir directory --username me --password fluffy
+#   ruby example_2_2.rb -superhelp --dir directory --username me
+#   ruby example_2_2.rb -superhelp --dir directory
+#   ruby example_2_2.rb -superhelp 
+#h#   ruby example_2_2.rb --superhelp
+

data/doc/example/example_2_3.rb

@@ -0,0 +1,37 @@
+require 'optiflag'
+
+# Example 2.3: 
+#  Variation 3:  Adding alternate forms and long forms
+module Example extend OptiFlag::Flagset
+  flag "dir" do 
+    alternate_forms "directory","D","d"
+    description "The Appliction Directory"
+  end
+  optional_flag "log" do
+    description "The directory in which to find the log files"
+    long_form "logging-directory" # long form is keyed after the '--' symbol
+  end
+  flag "username", :description => "Database username."  # alternate form
+  flag "password" do
+    description "Database password."
+  end
+  usage_flag "h","help","?"
+  extended_help_flag "superhelp"
+
+  handle_errors_and_help
+end 
+
+# Some code to _use_ the values
+puts "User has input: #{ ARGV.flag_value.dir  } for dir"
+puts "User has input: #{ ARGV.flag_value.username  } for username"
+puts "User has input: #{ ARGV.flag_value.password  } for password"
+if ARGV.flag_value.log?
+  puts "User has input: #{ARGV.flag_value.log  } for log"
+end
+
+# Try the following inputs
+#h#   ruby example_2_3.rb -dir directory -username me -password fluffy
+#   ruby example_2_3.rb -D directory -username me -password fluffy
+#h#   ruby example_2_3.rb -d directory -username me -password fluffy
+## Works (uses different long form for log):
+#h#  ruby example_2_3.rb -d directory -username me -password fluffy --logging-directory c:/tmp/log

data/doc/example/example_2_4.rb

@@ -0,0 +1,37 @@
+require 'optiflag'
+
+# Example 2_4:  
+#  Variation 4:  Selectively changing the symbol for a flag, and change the arity to be no-args
+module Example extend OptiFlag::Flagset
+  flag "dir" do 
+    alternate_forms "directory","D","d"
+    description "The Appliction Directory"
+  end
+  optional_flag "log" do
+    description "The directory in which to find the log files"
+    long_form "logging-directory" 
+  end
+  flag "username", :description => "Database username."  
+  flag "password" do
+    description "Database password."
+  end
+  optional_flag "delete" do
+    no_args # stating that this flag accepts no arguments
+    description "Delete database when done. Use carefully!!"
+    dash_symbol "!" # changing the symbol here
+    long_dash_symbol "!!" # changing its long form here
+  end
+  usage_flag "h","help","?"
+  extended_help_flag "superhelp"
+
+  handle_errors_and_help
+end 
+
+if ARGV.flag_value.delete? 
+  # super dangerous code to delete the database....
+  puts "Special DELETE flag invoked with special flag-symbol"
+end
+
+## Works (uses delete flag with different switch symbol):
+#h# ruby example_2_4.rb -d directory -username me -password fluffy !!delete --logging-directory c:/tmp/log
+# ruby example_2_4.rb -d directory -username me -password fluffy !delete --logging-directory c:/tmp/log

data/doc/example/example_2_5.rb

@@ -0,0 +1,28 @@
+require 'optiflag'
+
+# Example 2.5:  
+#  Variation 5:  User can get help on a specific flag.
+module Example extend OptiFlag::Flagset
+  flag "dir"
+  optional_flag "log" do
+    description "The directory into which log files will be written"
+  end
+  flag "username" do 
+    description "A Zeta-Blub Appliction Username."
+  end
+  flag "password" do
+    description "Your IT issued password. Don't forget it!"
+  end
+  usage_flag "h","help","?"
+
+  handle_errors_and_help
+end 
+
+## Normal mode:
+#   ruby example_2_5.rb -help 
+#   ruby example_2_5.rb -?
+#   ruby example_2_5.rb -h
+## Help on something specific:
+#h#   ruby example_2_5.rb -help username
+#h#   ruby example_2_5.rb -? log
+#h#   ruby example_2_5.rb -h password

data/doc/example/example_2_6.rb

@@ -0,0 +1,22 @@
+require 'optiflag'
+
+# Example 2.6: 
+# Variation 6:  Using the optional switch flag, a zero argument optional flag
+module Example extend OptiFlag::Flagset
+  flag "dir"
+  optional_switch_flag "clear"
+
+  handle_errors_and_help
+end 
+
+
+
+flag = ARGV.flag_value
+if flag.clear?
+  puts "The optional switch flag -clear has been invoked"
+else
+  puts "The optional switch flag -clear was NOT invoked"
+end
+
+#h#   ruby example_2_6.rb -dir c:/dir 
+#h#   ruby example_2_6.rb -clear -dir c:/dir 

data/doc/example/example_3.rb

@@ -0,0 +1,33 @@
+require 'optiflag'
+
+# Example 3:  Adding validation rules to the value of an input flag
+##  See the flags : "mode", "run_date", and "connection"
+module Example extend OptiFlag::Flagset
+  flag "dir" 
+  flag "connection" do
+    value_matches ["Connection string must be of the form username/password@servicename", /^\b.+\b\/\b.+@.+$/ ]
+  end
+  optional_flag "mode" do
+    value_in_set ["read","write","execute"]
+  end
+  optional_flag "run_date" do
+    value_matches ["run_date must be of the form mm/DD/YY",/^[0-9]{2}\/[0-9]{2}\/[0-9]{2,4}$/]
+  end
+  usage_flag "h","help","?"
+
+  handle_errors_and_help 
+end 
+
+flag = ARGV.flag_value
+
+puts "Mode flag is #{ flag.mode }" if flag.mode?
+puts "Run Date flag is #{ flag.run_date }" if flag.run_date?
+puts "Connection flag is #{ flag.connection }" if flag.connection?
+
+
+# Try the following inputs
+#h# ruby example_3.rb -dir directory -connection deklund/password@HAL.FBI.GOV -mode read -run_date 12/23/2005
+## Breaks (breaks a validation rule)
+#h# ruby example_3.rb -dir directory -connection 78GCTHR.com
+#h# ruby example_3.rb -dir directory -connection deklund/password@HAL.FBI.GOV -mode CRACK! -run_date 12/23/2005
+