std/flags documentation

std/flags▲toc

Parsing of command line flags.

For example:

struct myflags(
  verbose : bool = False,
  version : bool = False, 
  name : string = "",
  output : string = "",
  arguments : list<string> = []
)

val myflags : list<flag<myflags>>
  = [ Flag( "V?", ["version"], Bool(set-version),     "display version information" ),
      Flag( "v",  ["verbose"], Bool(set-verbose),     "verbosely list files"),
      Flag( "o",  ["output"],  Opt(set-output,"FILE"),"use FILE for dump" ),
      Flag( "n",  ["name"],    Req(set-name,"USER"),  "only show USER files" ),
    ]

fun set-name( t : myflags, name )  { t(name = name) }
fun set-verbose( t : myflags, v )  { t(verbose = v) }
fun set-version( t : myflags, v )  { t(version = v) }
fun set-output( t : myflags, mbs : maybe<string> ) : myflags
{
  match(mbs) {
    Nothing -> t(output = "stdout")
    Just(s) -> t(output = s)
  } 
}

public fun test( cmdargs )
{
  val header = "usage:\n program [options] files\n\noptions:"
     testflags.usageInfo( header ).println
  val (flags,args,errs) = parse( Myflags(), myflags, cmdargs )
  if (errs.nil?) {
    println( "\nsuccess!" );
    println( "flags: " + flags.show-flags)
    println( "arguments: " + args.join(" ") );
    if (flags.version) myflags.usage(header).println
  }
  else {
    println( errs.join("\n") + "\n" + myflags.usage(header) )
  }
}

fun show-flags( o : myflags ) {
  "{" + ["verbose=" + o.verbose.show,
         "version=" + o.version.show,
         "name=" + o.name.show,
         "output=" + o.output.show,
         "arguments=" + o.arguments.join(",")].join(";") + "}"
}
struct myflagsstd/flags/myflags: V(
  verbose : boolstd/core/bool: V = Falsestd/core/False: bool,
  version : boolstd/core/bool: V = Falsestd/core/False: bool, 
  name : stringstd/core/string: V = "",
  output : stringstd/core/string: V = "",
  arguments : liststd/core/list: V -> V<stringstd/core/string: V> = []
)

val myflags : liststd/core/list: V -> V<flagstd/flags/flag: V -> V<myflagsstd/flags/myflags: V>>
  = [ Flagstd/flags/Flag: forall<a> (short-names : string, long-names : list<string>, parser : flag-parser<a>, help : string) -> flag<a>( "V?", ["version"], Bool(set-version),     "display version information" ),
      Flagstd/flags/Flag: forall<a> (short-names : string, long-names : list<string>, parser : flag-parser<a>, help : string) -> flag<a>( "v",  ["verbose"], Bool(set-verbose),     "verbosely list files"),
      Flagstd/flags/Flag: forall<a> (short-names : string, long-names : list<string>, parser : flag-parser<a>, help : string) -> flag<a>( "o",  ["output"],  Optstd/flags/Opt: forall<a> (parse : (a, maybe<string>) -> a, help : string) -> flag-parser<a>(set-output,"FILE"),"use FILE for dump" ),
      Flagstd/flags/Flag: forall<a> (short-names : string, long-names : list<string>, parser : flag-parser<a>, help : string) -> flag<a>( "n",  ["name"],    Reqstd/flags/Req: forall<a> (parse : (a, string) -> a, help : string) -> flag-parser<a>(set-name,"USER"),  "only show USER files" ),
    ]

fun set-name( t : myflagsstd/flags/myflags: V, name )  { t(name = name) }
fun set-verbose( t : myflagsstd/flags/myflags: V, v )  { t(verbose = v) }
fun set-version( t : myflagsstd/flags/myflags: V, v )  { t(version = v) }
fun set-output( t : myflagsstd/flags/myflags: V, mbs : maybestd/core/maybe: V -> V<stringstd/core/string: V> ) : myflagsstd/flags/myflags: V
{
  match(mbs) {
    Nothingstd/core/Nothing: forall<a> maybe<a> -> t(output = "stdout")
    Juststd/core/Just: forall<a> (value : a) -> maybe<a>(s) -> t(output = s)
  } 
}

public fun test( cmdargs )
{
  val header = "usage:\n program [options] files\n\noptions:"
     testflags.usageInfo( header ).println
  val (flags,args,errs) = parse( Myflags(), myflags, cmdargs )
  if (errs.nil?) {
    println( "\nsuccess!" );
    println( "flags: " + flags.show-flags)
    println( "arguments: " + args.join(" ") );
    if (flags.version) myflags.usage(header).println
  }
  else {
    println( errs.join("\n") + "\n" + myflags.usage(header) )
  }
}

fun show-flags( o : myflagsstd/flags/myflags: V ) {
  "{" + ["verbose=" + o.verbose.show,
         "version=" + o.version.show,
         "name=" + o.name.show,
         "output=" + o.output.show,
         "arguments=" + o.arguments.join(",")].join(";") + "}"
}

.

struct flagstd/flags/flag: V -> V<a>(short-names : stringstd/core/string: Vlong-names : liststd/core/list: V -> V<stringstd/core/string: V>parser : flag-parserstd/flags/flag-parser: V -> V<a>help : stringstd/core/string: V)

Specifies a single command line flag For example: flag("h?",["help"],Bool(helpstd/flags/help: forall<a> (flag : flag<a>) -> string),"show help information").

Automatically generated. Retrieves the helpstd/flags/help: forall<a> (flag : flag<a>) -> string constructor field of the flagstd/flags/flag: V -> V type.

type flag-orderstd/flags/flag-order: V -> V<a>

Specifies how to handle flags that follow non-flag command line arguments.

con Permute

Allow flags to be permuted with non-flag arguments (default).

Flags following non-flag arguments are treated as arguments.

con Wrap(wrap : (stringstd/core/string: V) -> a)

Wrap each non-flag argument into an flag.

type flag-parserstd/flags/flag-parser: V -> V<a>

Specifies the argument of an flag.

An flagal argument.

con Req(parse : (a, stringstd/core/string: V) -> ahelp : stringstd/core/string: V)

A required argument.

con Bool(default : (a, boolstd/core/bool: V) -> a)

For a flag foo Automatically enables forms --no-foo and --foo=true|false.

Automatically generated. Tests for the Bool constructor of the flag-parserstd/flags/flag-parser: V -> V type.

fun parse( initial : a, flags : liststd/core/list: V -> V<flagstd/flags/flag: V -> V<a>>, args : liststd/core/list: V -> V<stringstd/core/string: V>, ordering : ?flag-orderstd/flags/flag-order: V -> V<a> ) : totalstd/core/total: E (a, liststd/core/list: V -> V<stringstd/core/string: V>, liststd/core/list: V -> V<stringstd/core/string: V>)

Parse the command line arguments args (see get-argsstd/env/get-args: () -> ndet list<string>) according to the flag descriptions flags. Takes an flagal argument ordering (=Permutestd/flags/Permute: forall<a> flag-order<a>) that specifies how optare handled that follow non-flag arguments. Returns three lists: the list of parsed flags, a list of non-flag arguments, and a list of potential error messages.

fun test( cmdargs : liststd/core/list: V -> V<stringstd/core/string: V> ) : consolestd/core/console: X ()std/core/(): V
fun usage( flags : liststd/core/list: V -> V<flagstd/flags/flag: V -> V<a>>, header : ?stringstd/core/string: V ) : stringstd/core/string: V

Return a nicely formatted string describing the usage of a command, consisting of a header followed by the descriptions of the flags. The default header is "usage:\n program [flags] arguments\n\nflags:".