Class: Como::Spec

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

Overview

User interface for Como.

Constant Summary

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
]
@@argv =

Command line options source.

ARGV

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from ComoCommon

getIo, runHook, setHook, setIo

Constructor Details

- (Spec) initialize(author, year)

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

+ (Object) check(opt = nil, &rule)

Alias for Spec.checkRule.



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

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

+ (Object) checkAlso(opt, error, &check)

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.



913
914
915
 
# File 'lib/como.rb', line 913

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

+ (Object) checkRule(opt = nil, &rule)

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.



874
875
876
877
878
879
880
881
882
 
# File 'lib/como.rb', line 874

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

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

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

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

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

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

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

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

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

+ (Object) execute

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

+ (Object) mapTypeToPrims(type)

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



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

def Spec.mapTypeToPrims( type )

    prims = nil

    if type.kind_of? Symbol
        case type
        when :switch;     prims = [ :none, :opt ]
        when :single;     prims = [ :one ]
        when :multi;      prims = [ :one, :many ]
        when :opt_single; prims = [ :one, :opt ]
        when :opt_multi;  prims = [ :one, :many, :opt ]
        when :opt_any;    prims = [ :none, :one, :many, :opt ]
        when :default;    prims = [ :none, :one, :many, :opt, :default ]
        when :exclusive;  prims = [ :none, :one, :many, :opt, :mutex ]
        when :silent;     prims = [ :none, :opt, :hidden ]
        else 
            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

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

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

+ (Object) setArgv(newArgv)

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



848
849
850
 
# File 'lib/como.rb', line 848

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

+ (Object) setUsageFooter(str)

Set optional footer for “usage”.



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

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

+ (Object) setUsageHeader(str)

Set optional header for “usage”.



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

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

+ (Object) specify(subcmd, table)

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.



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

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

+ (Object) specifyOptOrSub(opt_or_sub)

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

Parameters:

  • opt_or_sub (Array<Array>) —

    Option definition table.



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

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

+ (Object) usage

Display program usage (and optionally exit).



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

def Spec.usage
    Opt.main.usage
end

Instance Method Details

- (Object) checkRule(opt = nil, &rule) 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.



893
894
895
896
897
898
899
900
 
# File 'lib/como.rb', line 893

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

- (Object) subcmd(cmd, defs = [], config = {}) 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
 
# 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.
        defs.insert( 0, [ :silent, "help", "-h", "Display usage info." ] )
    end

    Spec.specify( subcmd, defs )

end