[ioke-dev] IOpt - Command line processing the Ioke way.

[Victor Hugo Borja <vic.borja@gmail.com>]

Hi, 

Seeking something to use Ioke for, I noticed ispec, dokgen need more command line processing love. So I decided to create a little library - IOpt[1] - like ruby's optparse to help those little programs we have in the bin directory to handle more options. 
Also I'm planning to have a rake like tool for ioke - Mike[2] -, so I'll try to make IOpt as reusable as possible.

I hope I'll find something that makes me contibute more to ioke's core, while doing this. Here's a little document of what should be possible with IOpt. Any comments are greatly appreciated. 

[1] http://github.com/vic/ioke/tree/iopt
[2] http://github.com/vic/ioke/tree/mike


  Introduction.
  
  IOpt is a tool for command-line option analysis. It tries to take
  advantage from Ioke's homoiconic nature to make you write less.
  IOpt is inspired by similar tools ruby's optparse, and tries to
  make command line parsing as easy as possible for ioke binaries, 
  while still allowing a great degree of control.
  
  Usage.

  The following example tries to illustrate some IOpt features, to 
  see more advanced examples, please refer to the spec.
  
     ;; first we create an application object that will use the
     ;; values parsed by IOpt
     app = MyApp mimic
     
     opt = IOpt mimic
     
     ;; the `on' macro can be used to register an action. 
     ;; if the first argument is a flag, the following arguments
     ;; are used to create a LexicalBlock to handle that option.
     
     ;; In this case, our action takes no arguments, has a
     ;; simple documentation string and just prints a useful message.
     opt on("--help", "Show this help", opt println)
     
     ;; creating an alias for an option is made as follows
     opt["-h"] = "--help"

     ;; to execute the options from an array of strings
     opt parse(System programArguments)

     ;; IOpt supports all of Iokes argument types, so your actions
     ;; can have required, optional arguments, +rest style args,
     ;; keyword arguments or +:krest as with any other Ioke method.
     ;; The following example would consume this input:
     ;;
     ;;   myapp -a bKey:10 aKey: 5 hello say:me world again 
     ;;
     ;; Note that keyword arguments can be specified by either using
     ;; a paired key:value string or as separate strings.
     ;; +rest and +:krest arguments force the option to consume all 
     ;; input until it finds the next option.
     ;;
     opt on("-a", "Support ioke argument style", 
            required, optional "defValue", +rest,
            aKey:, bKey: 22, +:krest,
         required should == "hello"
         optional should == "world"
         rest should == ["again"]
         aKey should == "5"
         bKey should == "10"
         krest should == { say: "me" })
        

     ;; A common pattern while parsing program options is to 
     ;; simply store the input value on some object's cell,
     ;; we could in this example use our app object for
     ;; this end.

     ;; Create --file option that takes a single argument,
     ;; and stores it on app cell(:file).
     opt on(app, @file)
     
     ;; It is possible to explicitly specify the flag to use
     opt on(app, "--output" @file)

     ;; This example will store a boolean value on app cell(:magic?)
     ;; Actually it creates a --[no-]magic option, allowing
     ;; the user to specify --magic or --no-magic, storing
     ;; true or false. - More on alternation options later -
     opt on(app, @magic?)

     ;; Suppose you have a method on your app object like
     app loadConfig = method("Load configuration values", path,
       loadAndProcess(path))

     ;; IOpt supports activating an object cell directly by
     ;; using a symbol to specify the cell used to handle args.
     ;; In this example we explicitly specified the flag to use,
     ;; as the one guessed by IOpt --load-config would be   
     ;; rather large.
     ;; 
     ;; IOpt will use the cell documentation when displaying help.
     ;; Same thing happens with arguments definition allowing your
     ;; method to receive input directly from the command line.
     opt on(app, "--config" :loadConfig)
     
     ;; When using an object to handle options, the on macro allows
     ;; that instead of the verbose tipical idiom
     opt on("--file", v, app file = v)
     opt on("-d", l, app debugWithLevel(l))

     ;; you can write:
     opt on(app, @file, "-d" :debugWithLevel)

     ;; It's also possible to activate a value on a given object.
     ;; In this example the method argument is used only to handle
     ;; the option and is not stored on the app object.
     opt on(app, "-s" method(v, "scream", self scream(v, :loud)))
     
     ;; or you can simply give a message to be applied on the object
     ;; notice the :it cell is bound to the option argument.
     opt on(app, "-s" '(scream(it, :loud))) do(
       ;; we can override the documentation for this flag like this:
       documentation = "Scream out very loud"
     )
     
     ;; As with methods, you can give IOpt any activatable value to
     ;; handle an option, Methods, LexicalBlocks, Macros, etc,
     ;; though in the case of macros, you need to specify if you'd
     ;; like to capture arguments from the command line, as macros
     ;; don't have arguments declaration.
     ;; For example to activate a macro on app:
     app weird = dmacro("Weird destructuring macro for CLI", 
        [>one]
        . ;; received one arg

        [>one, two]
        . ;; expected at most two args)

     ;; Now, so that you can be abe to consume at most two arguments
     ;; from the command line, you need to specify the argumentsCode
     ;; that your macro would expect.
     opt on(app, :weird) argumentsCode = "a,b nil"

     ;; As previously noted, IOpt supports alternate options. 
     ;; These options have a flag with the following form:
     ;;
     ;;    --[alt]ern
     ;;
     ;; That can handle --ern or --altern. By default this
     ;; kind of options dont take arguments as the flag name
     ;; indicates which value to use. 
     ;;
     ;; A positive flag (--ern) would default to true
     ;; the alternation (--altern) evaluates to the negation of it.
     ;; We said "the negation" because IOpt simply negates the
     ;; default value (think `true not()') for --altern.
     ;;
     ;; This can be useful, for example if you want --ern to 
     ;; have a false value and --altern to be true.
     opt on(app, "--[alt]ern", @alt?) default = false

     ;; or having some other value
     opt on(app, "--[alt]ern", @alt) do(
       default = "yes, please"
       alternative = "dont you dare")

     ;; you could use any object that returns its negative value
     ;; by calling its :not cell.
     lin = Origin mimic
     win = Origin mimic
     lin cell(:not) = win
     opt on("app", "--[hate-]unix", @system) default = lin

  ;; Plans
  ;; value validation
  ;;  using shouldcontext like ispec.
  ;; coercing values 
  ;;  at least numbers, booleans, symbols
  ;; processing priority 
  ;;  (eg, --help, --version should be handled first if present)
  ;; repetition 
  ;;  provide a way to specify an option mix/man repetition
  ;; halt
  ;;  provide a way to halt processing (ignore everything after --)


-- 
vic

Quaerendo invenietis.