Class: Como::Spec

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

Overview

User interface for Como.

Constant Summary collapse

@@argv =

Command line options source.

ARGV

Constants inherited from ComoCommon

ComoCommon::VERSION

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.



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

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.



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

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.



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

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.



731
732
733
734
735
736
737
738
739
 
# File 'lib/como.rb', line 731

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

    Option definitions.

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

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



547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
 
# File 'lib/como.rb', line 547

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

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

    ComoCommon.runHook( :preHook, preHookArgs )

    Spec.defineCheck( prog, author, year, defs, config )

    ComoCommon.runHook( :postHook, Opt.main )
end

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

Same as “defineCheckHelp” except without automatic “help” option processing.



573
574
575
576
577
 
# File 'lib/como.rb', line 573

def Spec.defineCheck( prog, author, year, defs, config = {} )
    spec = Spec.new( author, year )
    spec.subcmd( prog, defs, config )
    Opt.main.check( ArgsParseState.new( @@argv ) )
end

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

Alias to Spec.command.



566
567
568
 
# File 'lib/como.rb', line 566

def Spec.defineCheckHelp( prog, author, year, defs, config = {} )
    Spec.command( prog, author, year, defs, config )
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.



515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
 
# File 'lib/como.rb', line 515

def Spec.program( 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 )
    Opt.main.check( ArgsParseState.new( @@argv ) )

    ComoCommon.runHook( :postHook, Opt.main )
end

.setArgv(newArgv) ⇒ Object

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



705
706
707
 
# File 'lib/como.rb', line 705

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

.setUsageFooter(str) ⇒ Object

Set optional footer for “usage”.



721
722
723
 
# File 'lib/como.rb', line 721

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

.setUsageHeader(str) ⇒ Object

Set optional header for “usage”.



715
716
717
 
# File 'lib/como.rb', line 715

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

.specify(table) ⇒ Object

Specify and check options spec.

Parameters:

  • table (Array<Array>) —

    Option definition table.



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

def Spec.specify( table )

    options = {}
    subcmds = {}

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

    table.each_index do |idx|

        i = table[ idx ]

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

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

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

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

            # Add 1 dummy entry for :subcmd type if needed.
            table[ idx ] = [ i[0], i[1], nil, i[2] ]
        end

        Spec.ArgCheck( table[ idx ].length == 4,
            "Option table entry length not 4" )
    end


    table.each do |e|

        if e[0] == :subcmd

            subcmds[ e[1] ] = Opt.subcmd( e[1], e[3] )

        else

            option = nil

            case e[0]

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

            when :default
                option = Opt.defaultOpt( e[3] )

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

            options[ option.name ] = option

        end

    end

    [ options.values, subcmds.values ]
end

.usage ⇒ Object

Display program usage (and optionally exit).



710
711
712
 
# File 'lib/como.rb', line 710

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.



750
751
752
753
754
755
756
757
 
# File 'lib/como.rb', line 750

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

    Option definition table.

  • config (defaults to: {}) —

    Configuration options.



598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
 
# File 'lib/como.rb', line 598

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

    subcmd.setSubopt( *Spec.specify( defs ) )
    subcmd

end