Class: Como::Spec

Inherits:
ComoCommon show all
Defined in:
lib/como.rb

Overview

User interface for Como.

Constant Summary collapse

TYPE_PRIMS =

Option type primitives.

[
    # No arguments (i.e. switch).
    :none,
    # One argument.
    :one,
    # More than one argument.
    :many,
    # Optional argument(s).
    :opt,
    # Default option.
    :default,
    # Mutually exclusive option.
    :mutex,
    # Hidden option (no usage doc).
    :hidden
]
MAP_TYPE_PRIMS = 
{
    :switch =>      [ :none, :opt ],
    :single =>      [ :one ],
    :multi =>       [ :one, :many ],
    :opt_single =>  [ :one, :opt ],
    :opt_multi =>   [ :one, :many, :opt ],
    :opt_any =>     [ :none, :one, :many, :opt ],
    :default =>     [ :none, :one, :many, :opt, :default ],
    :exclusive =>   [ :none, :one, :many, :opt, :mutex ],
    :silent =>      [ :none, :opt, :hidden ],
}
@@argv =

Command line options source.

ARGV

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from ComoCommon

getIo, runHook, setHook, setIo

Constructor Details

#initialize(author, year) ⇒ Spec

Create Spec object that can handle subcmd definitions.

Parameters:

  • author (String) —

    Program author.

  • year (String) —

    Year (or dates) for program.



661
662
663
664
665
666
667
 
# File 'lib/como.rb', line 661

def initialize( author, year )
    @author = author
    @year = year

    Spec.ArgCheck( author.class == String, "Author name is not a String" )
    Spec.ArgCheck( year.class == String, "Year is not a String" )
end

Class Method Details

.check(opt = nil, &rule) ⇒ Object

Alias for Spec.checkRule.



891
 
# File 'lib/como.rb', line 891

def Spec.check( opt = nil, &rule ) Spec.checkRule( opt = nil, &rule ) end

.checkAlso(opt, error, &check) ⇒ Object

Additional option check.

Parameters:

  • opt (String) —

    Option name.

  • error (String) —

    Error string for false return values (from check).

  • check (Proc) —

    Checker proc run for the option. Either

Returns:

  • false or generate an exception when errors found.



918
919
920
 
# File 'lib/como.rb', line 918

def Spec.checkAlso( opt, error, &check )
    Opt.main.checkAlso( opt, error, &check )
end

.checkRule(opt = nil, &rule) ⇒ Object

Check option combination rules.

Parameters:

  • opt (String) (defaults to: nil) —

    Opt name to which rules are set. If not given, Opt.current is used.

  • rule (Proc) —

    Rules to check.



879
880
881
882
883
884
885
886
887
 
# File 'lib/como.rb', line 879

def Spec.checkRule( opt = nil, &rule )
    if opt
        opt = Opt[ opt ]
    else
        opt = Opt.current
    end
    opt.setRuleCheck( &rule )
    opt.checkRule
end

.command(prog, author, year, defs = [], config = {}) ⇒ Object

The primary entry point to Como. Defines the command switches and parses the command line. Performs “usage” display if “help” was selected.

Parameters:

  • prog (String) —

    Program (i.e. command) name.

  • author (String) —

    Author of the program.

  • year (String) —

    Year (or dates) for program.

  • defs (Array<Array>) (defaults to: []) —

    Option definitions.

  • config (Hash) (defaults to: {}) —

    Option definition’s behavioral config (changes @@config defaults).



584
585
586
587
 
# File 'lib/como.rb', line 584

def Spec.command( prog, author, year, defs = [], config = {} )
    Spec.defineCommand( prog, author, year, defs, config )
    Spec.execute
end

.defineCheckHelp(prog, author, year, defs, config = {}) ⇒ Object

Alias for command.

NOTE: This method is deprecated and will be removed in future releases.



645
646
647
 
# File 'lib/como.rb', line 645

def Spec.defineCheckHelp( prog, author, year, defs, config = {} )
    Spec.command( prog, author, year, defs, config )
end

.defineCommand(prog, author, year, defs, config = {}) ⇒ Object

Define options specification for command. User should perform execute separately.

Parameters:

  • prog (String) —

    Program (i.e. command) name.

  • author (String) —

    Author of the program.

  • year (String) —

    Year (or dates) for program.

  • defs (Array<Array>) —

    Option definitions.

  • config (Hash) (defaults to: {}) —

    Option definition’s behavioral config (changes @@config defaults).



624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
 
# File 'lib/como.rb', line 624

def Spec.defineCommand( prog, author, year, defs, config = {} )

    preHookArgs = {
        :prog => prog,
        :author => author,
        :year => year,
        :defs => defs,
        :config => config,
    }

    ComoCommon.runHook( :preHook, preHookArgs )

    spec = Spec.new( author, year )
    spec.subcmd( prog, defs, config )
end

.defineProgram(author, year, config = nil) { ... } ⇒ Object

Define options specification for program. User should perform execute separately.

Parameters:

  • author (String) —

    Program author.

  • year (String) —

    Year (or dates) for program.

Yields:

  • Subcmd definitions.



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

def Spec.defineProgram( author, year, config = nil, &defs )
    preHookArgs = {
        :author => author,
        :year => year,
        :config => config,
        :defs => defs,
    }

    ComoCommon.runHook( :preHook, preHookArgs )

    if config
        Opt.configOverlay( config )
    end

    spec = Spec.new( author, year )
    spec.instance_eval( &defs )
end

.execute ⇒ Object

Perform command line options checking.



651
652
653
654
 
# File 'lib/como.rb', line 651

def Spec.execute
    Opt.main.check( ArgsParseState.new( @@argv ) )
    ComoCommon.runHook( :postHook, Opt.main )
end

.mapTypeToPrims(type) ⇒ Object

Convert option types (type definitions) to option type primitives.



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
845
846
847
 
# File 'lib/como.rb', line 820

def Spec.mapTypeToPrims( type )

    prims = nil

    if type.kind_of? Symbol
        prims = MAP_TYPE_PRIMS[ type ]
        unless prims
            raise "Unknown option type: \"#{type}\"..."
        end

    elsif type.kind_of? Array
        prims = []

        # Check that type primivives are valid before taking
        # them into use.
        type.each do |t|
            if TYPE_PRIMS.index( t )
                prims.push t
            else
                raise "Unknown option type primitive: \"#{t}\"..."
            end
        end
    else
        raise "Invalid option type definition: \"#{type}\"..."
    end
            
    prims
end

.program(author, year, config = nil) { ... } ⇒ Object

Create specification for program with subcmds.

Parameters:

  • author (String) —

    Program author.

  • year (String) —

    Year (or dates) for program.

Yields:

  • Subcmd definitions.



568
569
570
571
 
# File 'lib/como.rb', line 568

def Spec.program( author, year, config = nil, &defs )
    Spec.defineProgram( author, year, config, &defs )
    Spec.execute
end

.setArgv(newArgv) ⇒ Object

Set command line options source, i.e. @@argv (default: ARGV).



853
854
855
 
# File 'lib/como.rb', line 853

def Spec.setArgv( newArgv )
    @@argv = newArgv
end

.setUsageFooter(str) ⇒ Object

Set optional footer for “usage”.



869
870
871
 
# File 'lib/como.rb', line 869

def Spec.setUsageFooter( str )
    Opt.main.setUsageFooter( str )
end

.setUsageHeader(str) ⇒ Object

Set optional header for “usage”.



863
864
865
 
# File 'lib/como.rb', line 863

def Spec.setUsageHeader( str )
    Opt.main.setUsageHeader( str )
end

.specify(subcmd, table) ⇒ Object

Check/fix options specs and create option objects for the whole table.

Parameters:

  • subcmd (Opt) —

    Subcommand target.

  • table (Array<Array>) —

    Option definition table for subcommand.



717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
 
# File 'lib/como.rb', line 717

def Spec.specify( subcmd, table )

    options = {}
    subcmds = {}

    # Type checks for valid user input.
    Spec.ArgCheck( table.class == Array, "Option table is not an Array" )

    table.each do |e|
        os = Spec.specifyOptOrSub( e )
        case os.type
        when :subcmd; subcmds[ os.name ] = os
        else options[ os.name ] = os
        end
    end

    subcmd.setOptionSubcmd( options.values, subcmds.values )
    subcmd
end

.specifyOptOrSub(opt_or_sub) ⇒ Object

Check/fix options specs and create option objects for the whole table.

Parameters:

  • opt_or_sub (Array<Array>) —

    Option definition table.



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
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
 
# File 'lib/como.rb', line 743

def Spec.specifyOptOrSub( opt_or_sub )

    # Fix the table entries if needed.

    Spec.ArgCheck( opt_or_sub.class == Array, "Option table entry is not an Array" )

    if opt_or_sub[0] == :default && opt_or_sub.length == 2

        # Add 2 dummy entries for :default type if needed.
        opt_or_sub = [ opt_or_sub[0], nil, nil, opt_or_sub[1] ]

    elsif opt_or_sub[0] == :subcmd && opt_or_sub.length == 3

        # Add 1 dummy entry for :subcmd type if needed.
        opt_or_sub = [ opt_or_sub[0], opt_or_sub[1], nil, opt_or_sub[2] ]

    end

    Spec.ArgCheck( opt_or_sub.length == 4,
        "Option table entry length not 4" )

    if opt_or_sub[0] == :subcmd

        Opt.subcmd( opt_or_sub[1], opt_or_sub[3] )

    else

        types = Spec.mapTypeToPrims( opt_or_sub[0] )

        if types.index( :default )
            Opt.defaultOpt( opt_or_sub[3] )
        else
            Opt.full( opt_or_sub[1],
                      opt_or_sub[2],
                      Spec.mapTypeToPrims( opt_or_sub[0] ),
                      opt_or_sub[3] )
        end

    end

end

.usage ⇒ Object

Display program usage (and optionally exit).



858
859
860
 
# File 'lib/como.rb', line 858

def Spec.usage
    Opt.main.usage
end

Instance Method Details

#checkRule(opt = nil, &rule) ⇒ Object Also known as: check

Check option combination rules.

Parameters:

  • opt (String) (defaults to: nil) —

    Opt name to which rules are set. If not given, Opt.current is used.

  • rule (Proc) —

    Rules to check.



898
899
900
901
902
903
904
905
 
# File 'lib/como.rb', line 898

def checkRule( opt = nil, &rule )
    if opt
        opt = Opt[ opt ]
    else
        opt = Opt.current
    end
    opt.setRuleCheck( &rule )
end

#subcmd(cmd, defs = [], config = {}) ⇒ Object Also known as: command

Define subcommand options.

Parameters:

  • cmd (String) —

    Subcmd name.

  • defs (Array<Array>) (defaults to: []) —

    Option definition table.

  • config (defaults to: {}) —

    Configuration options.



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
 
# File 'lib/como.rb', line 675

def subcmd( cmd, defs = [], config = {} )

    unless Opt.main

        main = MainOpt.new( @author, @year,
            cmd, nil, :subcmd, nil )
        Opt.setMain( main )
        subcmd = main

    else

        subcmd = Opt.findOpt( cmd )

        Opt.setSubcmd( subcmd )

        Spec.ArgCheck( false, "Subcommand \"#{cmd}\" not defined." ) unless subcmd

    end

    # Overlay user config on top of default.
    subcmd.applyConfig( config )

    if subcmd.config[ :autohelp ]
        # Automatically add the help option and make it also mutex.
        spec = MAP_TYPE_PRIMS[ :silent ] + [ :mutex ]
        defs.insert( 0, [ spec, "help", "-h", "Display usage info." ] )
    end

    Spec.specify( subcmd, defs )

end