Class OptiFlag::Flagset::EachFlag
In: ../src/optiflag.rb
Parent: Object

The class EachFlag is the template for each flag instantiated by a flag set declaration. One EachFlag is instantiated for each flag declaration. For example, the following flag-set declaration:

    module Example extend OptiFlagSet
      flag "dir"
      optional_flag "log"
      flag "username"
      flag "password"
    end

will instantiate four EachFlag instances.

The flag declarations are methods on the OptiFlag::Flagset module that actually instantiate each one of these EachFlag instances. They are listed in the RDoc for the OptiFlag::Flagset sub-module and are labeled as top-level flag-declarers.

An EachFlag object has many methods belonging to different categories of usage (though nothing enforced by the language or the code itself).

Clause Level Modifiers

These are methods that are used by the API user of the OptiFlag suite,(i.e. a programmer of other Ruby code but not the OptiFlag code itself). These methods are used within a flag declaration. For example, in the following code:

    module Example extend OptiFlagSet
      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
    end

There will be two EachFlag instances instantiated. For the first EachFlag instance, the one named "dir", two of these clause-level modifiers are invoked on the Eachflag instance by the OptiFlag user. These clause-level modifiers modify the expected behavior of each

List (clause API) of clause level modifiers

Internal Implementation Notes

This RDoc section is of concern only to implementors of OptiFlag. If you are using OptiFlag in your application, chances are this section is of little use to you.

‘the’ members.

Because OptiFlag seeks to provide a nice DSL to the user, many of the names of the clause-level modifiers are also useful names for methods which could access the internal field.

So, we have a problem. For instance, in the following code:

    module Example extend OptiFlagSet
      flag "username", :description => "Database username."  # alternate form

      and_process!
    end

the method ‘description’ has been written to modify the EachClass instance appropriately. But now, if you are accessing this EachClass instance in some other part of the OptiFlag internals (as, for instance, the help functionality would), then the use of the attr syntax would clash with this method.

  attr_accessor :description
  # this meta-code would generate both the
  # getter and the setter, where the getter method
  #    def description()
  #       return @desciption
  #    end
  # would conflict with the description method we
  # have provided for the user

The solution to this problem is to leave the standard (useful) method names for the clause level modifiers of the EachFlag instance and introduce another consistent name for the actual internal field. For a while, these internal fields and their attr‘s were named the_actual_description etc. But this proved to be a mouthful. Thereafter, the consistent naming scheme was to place ‘the_’ in front of the field.

Therefore, for most of the data based clause level modifiers (live ‘description’ which saves the description the user has provided), there is provided a parallel ‘the_description’ accessor ( or reader or writer, depending on the needs).

In summary, ‘description’ is a public API (for use by users of the OptiFlag suite) and ‘the_description’ is a a package-protected API.

Methods

Attributes

default_used  [R] 
enclosing_module  [R] 
flag  [R] 
for_extended_help  [RW] 
for_help  [RW] 
name  [R] 
order_added  [R] 
proxied_bound_method  [RW] 
the_alternate_forms  [R]  the ‘the’ values.. the actual means by which to access the values set by the clause-level modifiers.
the_arity  [R]  the ‘the’ values.. the actual means by which to access the values set by the clause-level modifiers.
the_dash_symbol  [R]  the ‘the’ values.. the actual means by which to access the values set by the clause-level modifiers.
the_description  [R]  the ‘the’ values.. the actual means by which to access the values set by the clause-level modifiers.
the_form_that_is_actually_used  [W] 
the_is_required  [R]  the ‘the’ values.. the actual means by which to access the values set by the clause-level modifiers.
the_long_dash_symbol  [R]  the ‘the’ values.. the actual means by which to access the values set by the clause-level modifiers.
the_long_form  [R]  the ‘the’ values.. the actual means by which to access the values set by the clause-level modifiers.
the_posttranslate  [R]  the ‘the’ values.. the actual means by which to access the values set by the clause-level modifiers.
the_posttranslate_all  [R]  the ‘the’ values.. the actual means by which to access the values set by the clause-level modifiers.
the_pretranslate  [R]  the ‘the’ values.. the actual means by which to access the values set by the clause-level modifiers.
the_pretranslate_all  [R]  the ‘the’ values.. the actual means by which to access the values set by the clause-level modifiers.
the_validation_rules  [R]  the ‘the’ values.. the actual means by which to access the values set by the clause-level modifiers.
validation_error  [R] 
value  [RW] 

Public Class methods

Public Instance methods

clause-level flag-modifier

clause-level flag-modifier

clause-level flag-modifier

clause-level flag-modifier

clause-level flag-modifier

clause-level flag-modifier

clause-level flag-modifier

clause-level flag-modifier

clause-level flag-modifier

  • Clause-level flag-modifier.
  • Synonym for ‘no_args’.
  • Takes no arguments (for itself).
  • Indicates that the flag takes no arguments. (i.e. the flag has zero arity).
  • Sample usage (embedded within a flag set declaration):
      flag "log" do
        no_arg
      end
    

Clause-level flag-modifier.

clause-level flag-modifier

clause-level flag-modifier

clause-level flag-modifier

clause-level flag-modifier

clause-level flag-modifier

clause-level flag-modifier

clause-level flag-modifier

translate() is a clause-level flag-modifier. It can be used in the following form:

clause-level flag-modifier

clause-level flag-modifier

Clause-level modifier. The user of this construct will pass a block that accepts two arguments:

  • the flag (of class EachFlag) and
  • an errors array.

If the user wants to indicate that a validation error has occurred (and that further processing should stop) he/she needs to add a string of the problem to the errrors array.<br/> The following (silly) example validates that the username is ‘daniel’. If it‘s not, the code adds to the errors array, and OptiFlag will indicate a validation error.

  flag "username"
      description "The username"
      validates_against do |flag,errors|
        if flag.value != "daniel"
          errors << "You are NOT DANIEL!"
        end
      end
  end
with_long_form(form)

Alias for long_form

[Validate]