Class: Como::Spec

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

Overview

User interface for Como.

Constant Summary

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



627
628
629
630
631
632
633
 
# File 'lib/como.rb', line 627

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.



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

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.



823
824
825
 
# File 'lib/como.rb', line 823

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.



784
785
786
787
788
789
790
791
792
 
# File 'lib/como.rb', line 784

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



550
551
552
553
 
# File 'lib/como.rb', line 550

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.



611
612
613
 
# File 'lib/como.rb', line 611

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



590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
 
# File 'lib/como.rb', line 590

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.



562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
 
# File 'lib/como.rb', line 562

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.



617
618
619
620
 
# File 'lib/como.rb', line 617

def Spec.execute
    Opt.main.check( ArgsParseState.new( @@argv ) )
    ComoCommon.runHook( :postHook, Opt.main )
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.



534
535
536
537
 
# File 'lib/como.rb', line 534

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



758
759
760
 
# File 'lib/como.rb', line 758

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

+ (Object) setUsageFooter(str)

Set optional footer for “usage”.



774
775
776
 
# File 'lib/como.rb', line 774

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

+ (Object) setUsageHeader(str)

Set optional header for “usage”.



768
769
770
 
# File 'lib/como.rb', line 768

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.



682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
 
# File 'lib/como.rb', line 682

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.



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

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

        case opt_or_sub[0]

        when :switch, :exclusive, :silent, :single, :multi,
            :opt_single, :opt_multi, :opt_any
            Opt.full( opt_or_sub[1], opt_or_sub[2], opt_or_sub[0], opt_or_sub[3] )

        when :default
            Opt.defaultOpt( opt_or_sub[3] )

        else
            raise "Unknown option type: \"#{opt_or_sub[0]}\"..."

        end

    end

end

+ (Object) usage

Display program usage (and optionally exit).



763
764
765
 
# File 'lib/como.rb', line 763

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.



803
804
805
806
807
808
809
810
 
# File 'lib/como.rb', line 803

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.



641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
 
# File 'lib/como.rb', line 641

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