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,
    # Option can be repeated.
    :repeat,
    # 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 ],
    :comp =>        [ :one, :repeat ],
    :multi =>       [ :one, :many, :repeat ],
    :opt_single =>  [ :one, :opt ],
    :opt_comp =>    [ :one, :repeat, :opt ],
    :opt_multi =>   [ :one, :many, :repeat, :opt ],
    :opt_any =>     [ :none, :one, :many, :repeat, :opt ],
    :default =>     [ :none, :one, :many, :opt, :default ],
    :exclusive =>   [ :none, :one, :many, :opt, :mutex ],
    :silent =>      [ :none, :opt, :repeat, :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.



676
677
678
679
680
681
682
# File 'lib/como.rb', line 676

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.



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

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.



937
938
939
# File 'lib/como.rb', line 937

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.



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

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).



599
600
601
602
# File 'lib/como.rb', line 599

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.



660
661
662
# File 'lib/como.rb', line 660

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).



639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
# File 'lib/como.rb', line 639

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.



611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
# File 'lib/como.rb', line 611

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

.executeObject

Perform command line options checking.



666
667
668
669
# File 'lib/como.rb', line 666

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.



839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
# File 'lib/como.rb', line 839

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.



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

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).



872
873
874
# File 'lib/como.rb', line 872

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

.setUsageFooter(str) ⇒ Object

Set optional footer for “usage”.



888
889
890
# File 'lib/como.rb', line 888

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

.setUsageHeader(str) ⇒ Object

Set optional header for “usage”.



882
883
884
# File 'lib/como.rb', line 882

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.



732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
# File 'lib/como.rb', line 732

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.



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
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
# File 'lib/como.rb', line 758

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

.usageObject

Display program usage (and optionally exit).



877
878
879
# File 'lib/como.rb', line 877

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.



917
918
919
920
921
922
923
924
# File 'lib/como.rb', line 917

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.



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

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