[ANN] Usage 0.0.2 - Yet another command line option processor

Discussion in 'Ruby' started by stevetuckner, Sep 21, 2005.

  1. stevetuckner

    stevetuckner Guest

    What is Usage?
    ===========

    Usage is simple way to access command line parameters for quick scripts
    that you write where you don't want to even think about command line
    processing. It handles many simple cases but does not have enough power
    to handle complicated option processing.

    How can I get it?
    ============

    gem install Usage

    Where is it at?
    =============

    http://raa.ruby-lang.org/project/usage/

    Show me some examples
    =================

    1. Simple Usage

    The only thing you have remember to use usage are how commands are
    usually documented.
    First you need to require the usage library:

    require "Usage"

    Then set up the usage string for the command:

    usage = Usage.new "infile outfile"

    The above would be a command with two require arguments: an input file
    and an output file.
    To access those arguments, you just need to use the usage variable that
    was created and
    send the .infile or .outfile message to them.

    File.open(usage.infile) do |fi|
    File.open(usage.outfile, "w") do |fo|
    fo.write(fi.read)
    end
    end

    If the user doesn't supply the correct number of arguments, the program
    exits with an error
    and the usage for the program (hence the libraries name).

    PROGRAM: test.rb
    ERROR: too few arguments 2 expected, 0 given

    USAGE: test.rb infile outfile

    2. Lists of files (...)

    You can write a program that accepts a list of files by using elipses
    appended to an
    argument (the following program concatenates the input files into one
    output file).

    usage = Usage.new "outfile infiles..."

    File.open(usage.outfile, "w") do |fo|
    usage.infiles.each do |infile|
    File.open(usage.infile) { |fi| fo.write(fi.read)}
    end
    end

    3. Optional arguments

    You can have optional arguments by surounding them in square brackets.

    usage = Usage.new "required_arg [optional_arg] "

    These are accessed in the standard way

    usage.optional_arg # this is nil if it is not given by the user

    usage.required_arg

    4. Options

    You can have dash options that are either required or optional. Options
    can also have
    arguments associated with them.

    usage = Usage.new "[-y] [-x excluded_tags] (-z ztag) (-w
    warning_arg) files..."

    The options are accessed with "dash_" prefixing the option so that the
    -y is accessed
    via .dash_y. The -x can be accessed either with #dash_x (which would be
    either nil or
    true) or #excluded_tags (which would be either nil or the argument for
    the -x option).
    The -z option is required and has one argument, also the -w option is
    also required.
    They can appear in any order (-z option first or -w option first). The
    optional arguments
    can appear either before, interspersed with, or after the required options.

    5. Long Options

    You can also have long options by including lines following the initial
    usage line that
    associates the short options with the long ones. Example below:

    usage = Usage.new "-x files...", <<EOT
    -x,--exclusive specifies exclusive access to the files
    EOT

    With this case, now #dash_x and #exclusive give the same result when
    applied to the usage
    variable.

    6. Typed options

    In order to remove a step and improve argument checking, you can also
    add in a "type"
    character to identify its type. The characters I used are somewhat
    arbitrary. Some of
    them I took from BASIC which I programmed in long long ago.

    % - Integer
    $ - String (but this is unnecessary as this is default)
    # - Float
    @ - Date-Time

    So when you send the argument message to the usage object, you will get
    a value of that
    type and if the user does not give that type, then they get an error
    message.

    usage = Usage.new "%num_times @on_date"

    In this example, #num_times returns and Integer object and #on_date
    returns a Time object.

    7. Choice options

    You can have optional options that have a set of values which they can
    be. The choices
    are separated by pipe symbols. See below:

    usage = Usage.new "[-a coffee|tea|milk]"

    After this #dash_a will give the string coffee, tea, or milk. If the
    value given isn't
    one of the given choices, then the user is given an error message with the
    appropriate choices.

    Steve Tuckner
    stevetuckner, Sep 21, 2005
    #1
    1. Advertising

  2. On 9/21/05, stevetuckner <> wrote:
    > What is Usage?
    > [...]
    > gem install Usage
    > [...]
    > require "Usage"


    I have no opinion on this library as such, but can I ask a couple of
    favours for future releases of this and other libraries?

    1. RubyGems is, inexplicably, case-sensitive. Can you please make sure
    that your gem names themselves are lowercased?
    2. Can we avoid, in the future, library file names with capital letters?
    Unix folk might enjoy having "Makefile" and "makefile" in the same
    directory, but the rest of us don't and therefore have smarter
    case-preserving filesystems. I would much rather do "require 'usage'"
    than "require 'Usage'".

    I would also argue that "usage" may be too common and could perhaps be
    namespaced (e.g., SimpleUsage, UsageSimple, Simple::Usage,
    Usage::Simple, or somesuch as appropriate).

    Beyond that, I haven't really read the announcement -- but
    congratulations on the release in any case. ;)

    -austin
    --
    Austin Ziegler *
    * Alternate:
    Austin Ziegler, Sep 21, 2005
    #2
    1. Advertising

  3. Austin Ziegler wrote:

    > Beyond that, I haven't really read the announcement -- but
    > congratulations on the release in any case. ;)


    i think you should. :)
    I did and will definitly try this lib next time i need something like that.

    Steve, keep it up, i like it...
    (But of course it would be even better if you could follow austin's
    suggestions)

    cheers

    Simon
    Simon Kröger, Sep 21, 2005
    #3
  4. stevetuckner

    stevetuckner Guest

    --------------080100000708020308060308
    Content-Type: text/plain; charset=ISO-8859-1; format=flowed
    Content-Transfer-Encoding: 7bit

    Austin Ziegler wrote:

    >On 9/21/05, stevetuckner <> wrote:
    >
    >
    >>What is Usage?
    >>[...]
    >>gem install Usage
    >>[...]
    >> require "Usage"
    >>
    >>

    >
    >I have no opinion on this library as such, but can I ask a couple of
    >favours for future releases of this and other libraries?
    >
    >1. RubyGems is, inexplicably, case-sensitive. Can you please make sure
    > that your gem names themselves are lowercased?
    >
    >

    I have never released a library before (on this list), so I guess I am
    not sure about where I should know the ettiquite for case-sensitivity of
    library names. I just named mine in line with the actual class name. I
    did notice that RAA requires lower case names. That was long after I had
    created a ruby forge project, etc. Also, there are 45 other gem packages
    with staring Upper case letters (see gem.rubyforge.org -- snippet
    below), included BlueCloth and RedCloth!

    Asami-0.04.gem 05-Dec-2004 06:50 163k
    Bangkok-0.1.0.gem 25-Mar-2005 09:50 39k
    Bloglines4R-0.1.0.gem 16-Jan-2005 10:55 6k
    ....
    Wiki2Go-1.16.1.gem 04-Sep-2005 15:05 121k
    XDCC-Fetch-1.409.gem 13-Feb-2005 10:15 158k
    ZenHacks-1.0.1.gem 14-Jul-2005 03:45 30k

    >2. Can we avoid, in the future, library file names with capital letters?
    > Unix folk might enjoy having "Makefile" and "makefile" in the same
    > directory, but the rest of us don't and therefore have smarter
    > case-preserving filesystems. I would much rather do "require 'usage'"
    > than "require 'Usage'".
    >
    >
    >

    Why doesn't it make sense to require a library name with the same case
    as the class name?

    >I would also argue that "usage" may be too common and could perhaps be
    >namespaced (e.g., SimpleUsage, UsageSimple, Simple::Usage,
    >Usage::Simple, or somesuch as appropriate).
    >
    >
    >

    I will think about re-releasing this as SimpleUsage.

    >Beyond that, I haven't really read the announcement -- but
    >congratulations on the release in any case. ;)
    >
    >
    >

    Thanks. After years of just lurking I am finally starting to release
    some stuff.

    >-austin
    >--
    >Austin Ziegler *
    > * Alternate:
    >
    >
    >
    >



    --------------080100000708020308060308--
    stevetuckner, Sep 21, 2005
    #4
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Manlio Perillo

    Yet Another Command Line Parser

    Manlio Perillo, Oct 26, 2004, in forum: Python
    Replies:
    9
    Views:
    352
    Manlio Perillo
    Oct 27, 2004
  2. Berehem
    Replies:
    4
    Views:
    538
    Lawrence Kirby
    Apr 28, 2005
  3. chandanlinster
    Replies:
    10
    Views:
    2,712
    Thad Smith
    Jul 24, 2006
  4. brahatha
    Replies:
    1
    Views:
    645
  5. Eric Mahurin
    Replies:
    10
    Views:
    235
    Eric Mahurin
    Sep 14, 2005
Loading...

Share This Page