optiflag 0.6 → 0.6.5

data/doc/rdoc-style.css

@@ -0,0 +1,208 @@
+
+body {
+    font-family: Verdana,Arial,Helvetica,sans-serif;
+    font-size:   90%;
+    margin: 0;
+    margin-left: 40px;
+    padding: 0;
+    background: white;
+}
+
+h1,h2,h3,h4 { margin: 0; color: #efefef; background: transparent; }
+h1 { font-size: 150%; }
+h2,h3,h4 { margin-top: 1em; }
+
+a { background: #eef; color: #039; text-decoration: none; }
+a:hover { background: #039; color: #eef; }
+
+/* Override the base stylesheet's Anchor inside a table cell */
+td > a {
+  background: transparent;
+  color: #039;
+  text-decoration: none;
+}
+
+/* and inside a section title */
+.section-title > a {
+  background: transparent;
+  color: #eee;
+  text-decoration: none;
+}
+
+/* === Structural elements =================================== */
+
+div#index {
+    margin: 0;
+    margin-left: -40px;
+    padding: 0;
+    font-size: 90%;
+}
+
+
+div#index a {
+    margin-left: 0.7em;
+}
+
+div#index .section-bar {
+   margin-left: 0px;
+   padding-left: 0.7em;
+   background: #ccc;
+   font-size: small;
+}
+
+
+div#classHeader, div#fileHeader {
+    width: auto;
+    color: white;
+    padding: 0.5em 1.5em 0.5em 1.5em;
+    margin: 0;
+    margin-left: -40px;
+    border-bottom: 3px solid #006;
+}
+
+div#classHeader a, div#fileHeader a {
+    background: inherit;
+    color: white;
+}
+
+div#classHeader td, div#fileHeader td {
+    background: inherit;
+    color: white;
+}
+
+
+div#fileHeader {
+    background: #057;
+}
+
+div#classHeader {
+    background: #048;
+}
+
+
+.class-name-in-header {
+  font-size:  180%;
+  font-weight: bold;
+}
+
+
+div#bodyContent {
+    padding: 0 1.5em 0 1.5em;
+}
+
+div#description {
+    padding: 0.5em 1.5em;
+    background: #efefef;
+    border: 1px dotted #999;
+}
+
+div#description h1,h2,h3,h4,h5,h6 {
+    color: #125;;
+    background: transparent;
+}
+
+div#validator-badges {
+    text-align: center;
+}
+div#validator-badges img { border: 0; }
+
+div#copyright {
+    color: #333;
+    background: #efefef;
+    font: 0.75em sans-serif;
+    margin-top: 5em;
+    margin-bottom: 0;
+    padding: 0.5em 2em;
+}
+
+
+/* === Classes =================================== */
+
+table.header-table {
+    color: white;
+    font-size: small;
+}
+
+.type-note {
+    font-size: small;
+    color: #DEDEDE;
+}
+
+.xxsection-bar {
+    background: #eee;
+    color: #333;
+    padding: 3px;
+}
+
+.section-bar {
+   color: #333;
+   border-bottom: 1px solid #999;
+    margin-left: -20px;
+}
+
+
+.section-title {
+    background: #79a;
+    color: #eee;
+    padding: 3px;
+    margin-top: 2em;
+    margin-left: -30px;
+    border: 1px solid #999;
+}
+
+.top-aligned-row {  vertical-align: top }
+.bottom-aligned-row { vertical-align: bottom }
+
+/* --- Context section classes ----------------------- */
+
+.context-row { }
+.context-item-name { font-family: monospace; font-weight: bold; color: black; }
+.context-item-value { font-size: small; color: #448; }
+.context-item-desc { color: #333; padding-left: 2em; }
+
+/* --- Method classes -------------------------- */
+.method-detail {
+    background: #efefef;
+    padding: 0;
+    margin-top: 0.5em;
+    margin-bottom: 1em;
+    border: 1px dotted #ccc;
+}
+.method-heading {
+  color: black;
+  background: #ccc;
+  border-bottom: 1px solid #666;
+  padding: 0.2em 0.5em 0 0.5em;
+}
+.method-signature { color: black; background: inherit; }
+.method-name { font-weight: bold; }
+.method-args { font-style: italic; }
+.method-description { padding: 0 0.5em 0 0.5em; }
+
+/* --- Source code sections -------------------- */
+
+a.source-toggle { font-size: 90%; }
+div.method-source-code {
+    background: #262626;
+    color: #ffdead;
+    margin: 1em;
+    padding: 0.5em;
+    border: 1px dashed #999;
+    overflow: hidden;
+}
+
+div.method-source-code pre { color: #ffdead; overflow: hidden; }
+
+/* --- Ruby keyword styles --------------------- */
+
+.standalone-code { background: #221111; color: #ffdead; overflow: hidden; }
+
+.ruby-constant  { color: #7fffd4; background: transparent; }
+.ruby-keyword { color: #00ffff; background: transparent; }
+.ruby-ivar    { color: #eedd82; background: transparent; }
+.ruby-operator  { color: #00ffee; background: transparent; }
+.ruby-identifier { color: #ffdead; background: transparent; }
+.ruby-node    { color: #ffa07a; background: transparent; }
+.ruby-comment { color: #b22222; font-weight: bold; background: transparent; }
+.ruby-regexp  { color: #ffa07a; background: transparent; }
+.ruby-value   { color: #7fffd4; background: transparent; }

data/examples/example_1.rb

@@ -0,0 +1,21 @@
+require 'optiflag'
+# Title: Four required flags (no ordering)
+# Description:  The simplest example, where we add four required flags, which have no ordering.
+module Example extend OptiFlagSet
+  flag "dir"
+  flag "log"
+  flag "username"
+  flag "password"
+ 
+  and_process!
+end 
+
+# Some code to _use_ the values
+puts "User has input:#{ ARGV.flags.dir  } for dir"
+puts "User has input:#{ ARGV.flags.log  } for log"
+puts "User has input:#{ ARGV.flags.username  } for username"
+puts "User has input:#{ ARGV.flags.password  } for password"
+
+# Try the following inputs
+#   ruby example_1.rb
+#h#   ruby example_1.rb -log logdirectory -dir directory -username me -password fluffy

data/examples/example_1_1.rb

@@ -0,0 +1,21 @@
+require 'optiflag'
+# Title: Four required flags (no ordering), accessing via the module name.
+# Description:  Exact same as the previous, except we show that the module name may be used to access the flag values, if you don't want to get them from ARGV. (It's a style thing)
+module Example extend OptiFlagSet
+  flag "dir"
+  flag "log"
+  flag "username"
+  flag "password"
+ 
+  and_process!
+end 
+
+# Some code to _use_ the values
+puts "User has input:#{ Example.flags.dir  } for dir"
+puts "User has input:#{ Example.flags.log  } for log"
+puts "User has input:#{ Example.flags.username  } for username"
+puts "User has input:#{ Example.flags.password  } for password"
+
+# Try the following inputs
+#   ruby example_1.rb
+#h#   ruby example_1.rb -log logdirectory -dir directory -username me -password fluffy

data/{doc/example → examples}/example_1_2.rb

@@ -1,21 +1,21 @@
 require 'optiflag'
 
-# Example 1.2:  
-#   Variation 2: Changing the universal short-form default symbol from '-' to '/'
-module Example extend OptiFlag::Flagset(:flag_symbol => "/")
+# Title: Changing the universal short-form symbol
+# Description:  Everything is still the same, except we are now changing the default symbol from '-' to '/'
+module Example extend OptiFlagSet(:flag_symbol => "/")
   flag "dir"
   flag "log"
   flag "username"
   flag "password"
 
-  handle_errors_and_help
+  and_process!
 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 "User has input:#{ ARGV.flags.dir  } for dir"
+puts "User has input:#{ ARGV.flags.log  } for log"
+puts "User has input:#{ ARGV.flags.username  } for username"
+puts "User has input:#{ ARGV.flags.password  } for password"
 
 
 # Try the following inputs

data/examples/example_2.rb

@@ -0,0 +1,31 @@
+require 'optiflag'
+$log = "c:/log"
+
+# Title:  Adding an optional flag and a usage flag.
+# Description: The optional flag allows us to declare that the flag is not required. Even though the help flag comes automatically with 'and_process!' we  can add more synonymns for the default '-h' and '-?'. Also, we show how to use the flag with a ? method.
+module Example extend OptiFlagSet
+  flag "dir"
+  optional_flag "log"
+  flag "username"
+  flag "password"
+  usage_flag "ayudame","help"
+
+  and_process!
+end 
+
+if ARGV.flags.log?  # note the question mark '?'
+  # this way we know whether or not the flag was
+  # set by the user or not
+  $log = ARGV.flags.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 -ayudame 
+#h#   ruby example_2.rb -?
+#   ruby example_2.rb -help
+

data/{doc/example → examples}/example_2_1.rb

@@ -1,8 +1,8 @@
 require 'optiflag'
 
-# Example 2.1:  
-#  Variation 1:  Using an extended usage flag
-module Example extend OptiFlag::Flagset
+# Title: Using an extended usage flag
+#  Description: The extended usage flag allows us to ask for detailed information about our declared flags.
+module Example extend OptiFlagSet
   flag "dir"
   optional_flag "log"
   flag "username"
@@ -10,7 +10,7 @@ module Example extend OptiFlag::Flagset
   usage_flag "h","help","?"
   extended_help_flag "superhelp"
 
-  handle_errors_and_help
+  and_process!
 end 
 
 #h#   ruby example_2_1.rb -superhelp --dir directory --username me --password fluffy

data/{doc/example → examples}/example_2_2.rb

@@ -1,23 +1,25 @@
 require 'optiflag'
 
-# Example 2.2:  
-#  Variation 2:  Adding descriptions to the flags (will appear in extended help)
+# Title: Adding 'description' as our first clause-level modifier.
+#  Description:  Adding descriptions to the flags so that they 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
+module Example extend OptiFlagSet
   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
+  # alternate form of description can be provided
+  # as a hash (to preserve vertical space)
+  flag "username", :description => "Database username."  
   flag "password" do
     description "Database password."
   end
   usage_flag "h","help","?"
   extended_help_flag "superhelp"
 
-  handle_errors_and_help
+  and_process!
 end 
 
 ## Works (triggers extended help):

data/{doc/example → examples}/example_2_3.rb

@@ -1,8 +1,8 @@
 require 'optiflag'
 
-# Example 2.3: 
-#  Variation 3:  Adding alternate forms and long forms
-module Example extend OptiFlag::Flagset
+#  Title:  Adding alternate forms and long forms
+#  Description: Alternate forms may be used in place of the regular flag.  Long forms are used with the long form dispatch symbol (usually '--')
+module Example extend OptiFlagSet
   flag "dir" do 
     alternate_forms "directory","D","d"
     description "The Appliction Directory"
@@ -18,15 +18,15 @@ module Example extend OptiFlag::Flagset
   usage_flag "h","help","?"
   extended_help_flag "superhelp"
 
-  handle_errors_and_help
+  and_process!
 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"
+puts "User has input: #{ ARGV.flags.dir  } for dir"
+puts "User has input: #{ ARGV.flags.username  } for username"
+puts "User has input: #{ ARGV.flags.password  } for password"
+if ARGV.flags.log?
+  puts "User has input: #{ARGV.flags.log  } for log"
 end
 
 # Try the following inputs

data/{doc/example → examples}/example_2_4.rb

@@ -1,8 +1,8 @@
 require 'optiflag'
 
-# Example 2_4:  
+# Title:  Other clause-level modifiers, like arity and flag symbol  
 #  Variation 4:  Selectively changing the symbol for a flag, and change the arity to be no-args
-module Example extend OptiFlag::Flagset
+module Example extend OptiFlagSet
   flag "dir" do 
     alternate_forms "directory","D","d"
     description "The Appliction Directory"
@@ -24,10 +24,10 @@ module Example extend OptiFlag::Flagset
   usage_flag "h","help","?"
   extended_help_flag "superhelp"
 
-  handle_errors_and_help
+  and_process!
 end 
 
-if ARGV.flag_value.delete? 
+if ARGV.flags.delete? 
   # super dangerous code to delete the database....
   puts "Special DELETE flag invoked with special flag-symbol"
 end

data/{doc/example → examples}/example_2_5.rb

@@ -1,8 +1,8 @@
 require 'optiflag'
 
-# Example 2.5:  
-#  Variation 5:  User can get help on a specific flag.
-module Example extend OptiFlag::Flagset
+# Title:  Help flag can be used for a specific flag.
+#  Description:  The normal help flag can be used with a parameter so that you can get more information on any of the particular flags.
+module Example extend OptiFlagSet
   flag "dir"
   optional_flag "log" do
     description "The directory into which log files will be written"
@@ -15,7 +15,7 @@ module Example extend OptiFlag::Flagset
   end
   usage_flag "h","help","?"
 
-  handle_errors_and_help
+  and_process!
 end 
 
 ## Normal mode: