Class: UsageMod::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/Usage.rb

Overview

This is the class that does the heavy lifting for the Usage class. It parses the usage string, options string and makes the information available by using method_missing.

see the README document for how to format the usage string and options string

Constant Summary collapse

DESC_PARSE_REGEX = 
/^-(\w),--(\S+)\s+(.*)$/
OPTION_NAME = 
1
OPTION_LONG_NAME = 
2
OPTION_DESCRIPTION = 
3
OPEN_PAREN_OR_BRACKET = 
1
DASH_OR_TYPE = 
2
ARG_OR_OPTION_NAME = 
3
INFINITE = 
4
CLOSE_PAREN_OR_BRACKET = 
5

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(usage_ui, usageString, optionsString = "", userArguments = ARGV) ⇒ Base

create a UsageMod::Base object. usageString specifies the arguments expected. The optionsString specifies further information about the arguments. userArguments defaults to the program arguments but allows the user to get the arguments from somewhere else.



595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
 
# File 'lib/Usage.rb', line 595

def initialize(usage_ui, usageString, optionsString="", userArguments=ARGV)
  @usage_ui = usage_ui
  @argHash = {}
  @usageString = usageString
  @optionsString = optionsString
  @userArguments = userArguments
  @custom_args = []

  # this is what is used to support plugin parsing

  @type_chars = @@type_chars.keys.sort_by{|x| -(x.size)}.map{|x| x.gsub(/./){|s| "\\" + s}}.join("|")
  $TRACE.debug 5, "type_chars = '#{@type_chars}'"
  
  # parse the usage string

  @argList = parse_usage(usageString)

  # parse the description

  @descriptions = parse_option_descriptions

  # update options hash now that some long names may have been parsed

  @argList.update_with_long_names
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(symbol, *args) ⇒ Object

uses the argHash to return data specified about the command line arguments by the symbol passed in.



947
948
949
950
951
952
 
# File 'lib/Usage.rb', line 947

def method_missing(symbol, *args)
  $TRACE.debug 5, "UsageMod::Base method missing: #{symbol}"
  if @argHash.has_key?(symbol.to_s) then
    @argHash[symbol.to_s]
  end
end

Class Method Details

.add_type_handler(type_char, klass) ⇒ Object 



567
568
569
 
# File 'lib/Usage.rb', line 567

def add_type_handler(type_char, klass)
  @@type_chars[type_char] = klass
end

.reset_type_handlers ⇒ Object 



571
572
573
574
575
576
577
578
579
580
581
582
583
 
# File 'lib/Usage.rb', line 571

def reset_type_handlers
  @@type_chars = {}
  add_type_handler("@", TimeArgumentPlugin)
  add_type_handler("%", IntegerArgumentPlugin)
  add_type_handler("#", FloatArgumentPlugin)
  add_type_handler(">>?", FileAppendQueryPlugin)
  add_type_handler(">>", FileAppendPlugin)
  add_type_handler("<<", FileReadLinesPlugin)
  add_type_handler(">?", FileOutputQueryPlugin)
  add_type_handler("<", FileInputPlugin)
  add_type_handler(">", FileOutputPlugin)
  add_type_handler("<@", OpenURIInputPlugin)
end

Instance Method Details

#convert_value(arg_type, value) ⇒ Object

convert a value to its typed equivalent



897
898
899
900
901
902
903
904
905
906
907
908
909
 
# File 'lib/Usage.rb', line 897

def convert_value(arg_type, value)
  $TRACE.debug 5, "convert_value: #{value} to #{arg_type}"
  case arg_type.to_s
  when /^Arg:(.+)$/
    klass = @@type_chars[$1]

    $TRACE.debug 5, "got custom arg type with char '#{$1}' about to call #{klass.inspect}"
    custom_arg = klass.new(@usage_ui, value)
    @custom_args.push(custom_arg)
    return custom_arg.value
  else
    return value
  end
end

#dump ⇒ Object

dump the argument hash



937
938
939
940
941
 
# File 'lib/Usage.rb', line 937

def dump
  @argHash.keys.sort.each do |k|
    puts "#{k} = #{@argHash[k].inspect}"
  end
end

#long_usage ⇒ Object

return the long usage string



921
922
923
924
925
926
927
928
929
930
931
932
 
# File 'lib/Usage.rb', line 921

def long_usage
  @optionsString.split("\n").map do |line|
    if m = DESC_PARSE_REGEX.match(line) then
      opt_str = "-#{m[OPTION_NAME]},--#{m[OPTION_LONG_NAME]}"
      opt_str + (" " * (@maxOptionNameLen + 2 - opt_str.size)) + m[OPTION_DESCRIPTION]
    elsif /^\s+(\S.*)$/.match(line) then
      (" " * (@maxOptionNameLen + 2)) + $1
    else
      line
    end
  end.join("\r\n")
end

#parse_args ⇒ Object

set up @argHash for the options and arguments based on two things (this calls UsageMod::Base#parse_options to parse the options:

# the parse usage string description in @argList (which is an ArgumentList object) # the arguments that the user ran the program with which is in @userArguments (which is an array of strings)

this allows method_missing to return the correct values when it is called



855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
 
# File 'lib/Usage.rb', line 855

def parse_args()
  parse_options
  $TRACE.debug 5, "parse_args: user arguments = #{@userArguments.inspect}"
  user_args_size = @userArguments.size
  req_args_size = @argList.required_arguments.size
  opt_args_size = @argList.optional_arguments.size
  $TRACE.debug 5, "user_args_size = #{user_args_size}, req_args_size = #{req_args_size}\n"
  if user_args_size < req_args_size then
    $TRACE.debug 5, "parse_args: required_arguments = #{@argList.required_arguments.inspect}"
    $TRACE.debug 5, "parse_args: optional_arguments = #{@argList.optional_arguments.inspect}"
    raise TooFewArgError.new("too few arguments #{req_args_size} expected, #{user_args_size} given")
  elsif user_args_size > (req_args_size + opt_args_size)
    if !@argList.has_infinite_arg then
      raise ExtraArgError.new("too many arguments #{req_args_size} expected, #{user_args_size} given")
    end
  end
  
  @userArguments.each_with_index do |userarg, index|
    arg = @argList.get_next_arg(index)
    $TRACE.debug 5, "userarg = '#{userarg}', arg = '#{arg}'"

    if @argList.has_infinite_arg && index + 1 >= req_args_size then
      @argHash[@argList.last_arg.name].push(userarg)
    else
      @argHash[arg.name] = convert_value(arg.arg_type, userarg)
    end
  end

  if block_given?
    begin
      yield self
    ensure
      @custom_args.each {|arg| arg.close}
    end
  end

  self
end

#parse_option_descriptions ⇒ Object

parse the option descriptions



627
628
629
630
631
632
633
634
635
636
637
638
639
640
 
# File 'lib/Usage.rb', line 627

def parse_option_descriptions
  @maxOptionNameLen = 0
  @optionsString.split("\n").each do |line|
    if m = DESC_PARSE_REGEX.match(line) then
      $TRACE.debug 5, "[#{m[1]}][#{m[2]}][#{m[3]}]"
      len = m[OPTION_NAME].size + m[OPTION_LONG_NAME].size + 4
      @maxOptionNameLen = len if len > @maxOptionNameLen
      if option = @argList.lookup_option(m[OPTION_NAME]) then
        option.long_name = m[OPTION_LONG_NAME]
        option.description = m[OPTION_DESCRIPTION]
      end
    end
  end
end

#parse_options ⇒ Object

set up @argHash for all the options based on two things:

# the parse usage string description in @argList (which is an ArgumentList object) # the arguments that the user ran the program with which is in @userArguments (which is an array of strings)

this allows method_missing to return the correct values when it is called



777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
 
# File 'lib/Usage.rb', line 777

def parse_options()
  last_index = @userArguments.size
  found_options = []
  option_waiting_for_argument = nil
  $TRACE.debug 5, "parse_options: user arguments = #{@userArguments.inspect}"
  @userArguments.each_with_index do |userarg, index|
    $TRACE.debug 7, "arg = '#{userarg}'"      
    # if we found an option 

    if m = /^-{1,2}(.*)$/.match(userarg) then
      # break out if we are waiting for an argument

      break if option_waiting_for_argument

      # handle requests for long usage string

      if m[1] == "help" || m[1] == "?" then
        raise LongUsageRequested
      end
      
      # look up the option

      if option = @argList.lookup_option(m[1]) then
        @argHash[option.name_as_symbol] = true
        @argHash[option.long_name_as_symbol] = true if option.long_name
        found_options.push(option)
        if option.has_argument then
          option_waiting_for_argument = option
        end
      else
        raise UnknownOptionError.new("unknown option '#{userarg}'")
      end
      
    # else its either a option or regular argument

    else
      # if it is an option argument

      if option = option_waiting_for_argument then
        # process the argument

        value = convert_value(option.arg_type, userarg)
        if option.arg_type == Choices then
          if !option.choices.include?(userarg) then
            raise InvalidChoiceError.new(option, userarg)
          end
          @argHash[option.name_as_symbol] = value
          @argHash[option.long_name_as_symbol] = value if option.long_name
        else
          @argHash[option.arg_name] = value
        end
        
        option_waiting_for_argument = nil
        
      # otherwise its a regular argument 

      else
        # we need to leave this loop

        last_index = index
        break
      end
    end
  end

  if option_waiting_for_argument then
    raise MissingOptionArgumentError.new(option_waiting_for_argument)
  end
  
  missing_options = @argList.required_options - found_options
  if missing_options.size > 0 then
    raise MissingOptionsError.new(missing_options)
  end
  
  $TRACE.debug 5, "parse_options: last_index = #{last_index}"
  @userArguments = @userArguments[last_index..-1]
end

#parse_usage(usageString) ⇒ Object

this parses the usage string and returns an ArgumentList object that describes the arguments by their characteristics (type, optional/required, etc)

Raises:



653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
 
# File 'lib/Usage.rb', line 653

def parse_usage(usageString)
  type_chars = @type_chars + "|\-"
  #                 ([      @%#<><<>>      name   ...      )]

  parse_regex = /^([\(\[])?(#{type_chars})?([^.\)\]]*)(\.\.\.)?([\)\]])?$/
  $TRACE.debug 5, "whole regex = #{parse_regex.source}"
  
  arg_list = ArgumentList.new
  option_stack = []
  processing_options = true
  option = nil
  choices = nil
  usageString.split(/\s/).each do |arg|
    $TRACE.debug 5, "arg = '#{arg}'"
    m = parse_regex.match(arg)
    infinite = false
    optional_arg = false
    option = nil
    if m then
      $TRACE.debug 5, "got match, opening='#{m[OPEN_PAREN_OR_BRACKET]}' " +
                 "dash_or_type='#{m[DASH_OR_TYPE]}' " + 
                 "main='#{m[ARG_OR_OPTION_NAME]}' " + 
                 "infinite = '#{m[INFINITE]}' " +
                 "closing='#{m[CLOSE_PAREN_OR_BRACKET]}'"
      $TRACE.debug 9, "option = #{option.inspect}, option_stack = #{option_stack.inspect}"

      choices = m[ARG_OR_OPTION_NAME].split(/\|/)
      raise ChoicesNotOnOptionError.new if choices.size > 1 && option_stack.size == 0
      
      if m[DASH_OR_TYPE] then
        raise ChoiceNoTypeError.new if choices.size > 1
        
        case m[DASH_OR_TYPE]
        when "-"
          option = Option.new(m[ARG_OR_OPTION_NAME])
          if m[OPEN_PAREN_OR_BRACKET] then
            option.is_required = (m[OPEN_PAREN_OR_BRACKET] == "(")
            option_stack.push(option)
          else
            option.arg_type = TrueClass
          end
        else
          arg_type = "Arg:#{m[DASH_OR_TYPE]}"
          $TRACE.debug 5, "is custom type '#{m[DASH_OR_TYPE]}'"
        end
      else
        arg_type = String
      end

      if m[CLOSE_PAREN_OR_BRACKET] then 
        if option_stack.size == 0 then
          if m[OPEN_PAREN_OR_BRACKET] && m[DASH_OR_TYPE] != '-' then
            # Assume this is an optional parameter

            optional_arg = true
            $TRACE.debug 9, "parse_usage: Optional paramater found: #{m[ARG_OR_OPTION_NAME]}"
          else
            raise NestingUnderflow.new
          end
        else
          option = option_stack.pop
          if option.is_required != (m[CLOSE_PAREN_OR_BRACKET] == ")") then
            raise MismatchedBracesError.new
          end
          # it has an argument if this token didn't also have a open bracket

          option.has_argument = !m[OPEN_PAREN_OR_BRACKET]
          if option.has_argument then
            if choices.size > 1 then
              option.choices = Choices.new(choices)
              option.arg_type = Choices
            else
              option.arg_name = m[ARG_OR_OPTION_NAME]
              option.arg_type = arg_type
            end
          end
        end
      end
      
      if m[INFINITE] != nil then
        $TRACE.debug 5, "is infinite"
        infinite = true
      end

      $TRACE.debug 9, "option = #{option.inspect}, option_stack = #{option_stack.inspect}"
      unless option || option_stack.size > 0
        $TRACE.debug 9, "no longer processing options"
        processing_options = false
      end
    else
      arg_type = String
      $TRACE.debug 5, "is string"
    end

    if processing_options then
      if option_stack.size == 0 then
        $TRACE.debug 5, "adding option #{option.name}"
        arg_list.push_option(option)
      end
    else
      arg = m[ARG_OR_OPTION_NAME]
      if infinite then
        @argHash[arg] = []
      else
        @argHash[arg] = nil
      end
      $TRACE.debug 5, "adding argument '#{arg}'"
      arg_list.push_arg(Argument.new(arg, arg_type, infinite, optional_arg))

      arg_list.process
    end
  end

  raise NestingOverflow.new if option_stack.size > 0
  
  $TRACE.debug 9, "arg_list = #{arg_list.inspect}\n"
  arg_list
end

#usage ⇒ Object

return the short usage string



914
915
916
 
# File 'lib/Usage.rb', line 914

def usage
  @usageString.gsub(/#{@type_chars}/, "") + "\n"
end