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

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from ComoCommon

getIo, 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.



494
495
496
497
498
499
500
 
# File 'lib/como.rb', line 494

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

.ArgCheck(cond, str) ⇒ Object

Raises:

  • (ArgumentError) 


674
675
676
 
# File 'lib/como.rb', line 674

def Spec.ArgCheck( cond, str )
    raise( ArgumentError, str ) unless cond
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.



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

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.



637
638
639
640
641
642
643
644
645
 
# File 'lib/como.rb', line 637

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



471
472
473
474
 
# File 'lib/como.rb', line 471

def Spec.command( prog, author, year, defs, config = {} )
    Spec.defineCheck( prog, author, year, defs, config )
    # Spec.usage if Opt['help'].given
end

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

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



483
484
485
486
487
 
# File 'lib/como.rb', line 483

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.



477
478
479
 
# File 'lib/como.rb', line 477

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.



451
452
453
454
455
456
457
458
 
# File 'lib/como.rb', line 451

def Spec.program( author, year, config = nil, &defs )
    if config
        Opt.configOverlay( config )
    end
    spec = Spec.new( author, year )
    spec.instance_eval( &defs )
    Opt.main.check( ArgsParseState.new( @@argv ) )
end

.setArgv(newArgv) ⇒ Object

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



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

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

.setUsageFooter(str) ⇒ Object

Set optional footer for “usage”.



627
628
629
 
# File 'lib/como.rb', line 627

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

.setUsageHeader(str) ⇒ Object

Set optional header for “usage”.



621
622
623
 
# File 'lib/como.rb', line 621

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

.specify(table) ⇒ Object

Specify and check options spec.

Parameters:

  • table (Array<Array>) —

    Option definition table.



544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
 
# File 'lib/como.rb', line 544

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



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

def Spec.usage
    Opt.main.usage
end

Instance Method Details

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



653
654
655
656
657
658
659
660
 
# File 'lib/como.rb', line 653

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

#subcmd(cmd, defs, config = {}) ⇒ Object

Define subcommand options.

Parameters:

  • cmd (String) —

    Subcmd name.

  • defs (Array<Array>) —

    Option definition table.

  • config (defaults to: {}) —

    Configuration options.



508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
 
# File 'lib/como.rb', line 508

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