lib/opts.nit

   1 # This file is part of NIT ( http://www.nitlanguage.org ).
   2 #
   3 # Copyright 2008 Floréal Morandat <morandat@lirmm.fr>
   4 # Copyright 2008 Jean Privat <jean@pryen.org>
   5 #
   6 # This file is free software, which comes along with NIT.  This software is
   7 # distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
   8 # without  even  the implied warranty of  MERCHANTABILITY or  FITNESS FOR A
   9 # PARTICULAR PURPOSE.  You can modify it is you want,  provided this header
  10 # is kept unaltered, and a notification of the changes is added.
  11 # You  are  allowed  to  redistribute it and sell it, alone or is a part of
  12 # another product.
  13
  14 # Management of options on the command line
  15 module opts
  16
  17 # Super class of all option's class
  18 abstract class Option
  19         # Names for the option (including long and short ones)
  20         var names: Array[String]
  21
  22         # Type of the value of the option
  23         type VALUE: nullable Object
  24
  25         # Human readable description of the option
  26         var helptext: String
  27
  28         # Gathering errors during parsing
  29         var errors: Array[String] = new Array[String]
  30
  31         # Is this option mandatory?
  32         var mandatory: Bool = false is writable
  33
  34         # Is this option hidden from `usage`?
  35         var hidden: Bool = false is writable
  36
  37         # Has this option been read?
  38         var read: Bool = false is writable
  39
  40         # Current value of this option
  41         var value: VALUE is writable
  42
  43         # Default value of this option
  44         var default_value: VALUE is writable
  45
  46         # Create a new option
  47         init(help: String, default: VALUE, names: nullable Array[String]) is old_style_init do
  48                 init_opt(help, default, names)
  49         end
  50
  51         # Init option `helptext`, `default_value` and `names`.
  52         #
  53         # Also set current `value` to `default`.
  54         fun init_opt(help: String, default: VALUE, names: nullable Array[String])
  55         do
  56                 if names == null then
  57                         self.names = new Array[String]
  58                 else
  59                         self.names = names.to_a
  60                 end
  61                 helptext = help
  62                 default_value = default
  63                 value = default
  64         end
  65
  66         # Add new aliases for this option
  67         fun add_aliases(names: String...) do names.add_all(names)
  68
  69         # An help text for this option with default settings
  70         redef fun to_s do return pretty(2)
  71
  72         # A pretty print for this help
  73         fun pretty(off: Int): String
  74         do
  75                 var text = new FlatBuffer.from("  ")
  76                 text.append(names.join(", "))
  77                 text.append("  ")
  78                 var rest = off - text.length
  79                 if rest > 0 then text.append(" " * rest)
  80                 text.append(helptext)
  81                 #text.append(pretty_default)
  82                 return text.to_s
  83         end
  84
  85         # Pretty print the default value.
  86         fun pretty_default: String
  87         do
  88                 var dv = default_value
  89                 if dv != null then return " ({dv.to_s})"
  90                 return ""
  91         end
  92
  93         # Consume parameters for this option
  94         protected fun read_param(opts: OptionContext, it: Iterator[String])
  95         do
  96                 read = true
  97         end
  98 end
  99
 100 # Not really an option. Just add a line of text when displaying the usage
 101 class OptionText
 102         super Option
 103
 104         # Init a new OptionText with `text`.
 105         init(text: String) is old_style_init do super(text, null, null)
 106
 107         redef fun pretty(off) do return to_s
 108
 109         redef fun to_s do return helptext
 110 end
 111
 112 # A boolean option, `true` when present, `false` if not
 113 class OptionBool
 114         super Option
 115         redef type VALUE: Bool
 116
 117         # Init a new OptionBool with a `help` message and `names`.
 118         init(help: String, names: String...) is old_style_init do super(help, false, names)
 119
 120         redef fun read_param(opts, it)
 121         do
 122                 super
 123                 value = true
 124         end
 125 end
 126
 127 # A count option. Count the number of time this option is present
 128 class OptionCount
 129         super Option
 130         redef type VALUE: Int
 131
 132         # Init a new OptionCount with a `help` message and `names`.
 133         init(help: String, names: String...) is old_style_init do super(help, 0, names)
 134
 135         redef fun read_param(opts, it)
 136         do
 137                 super
 138                 value += 1
 139         end
 140 end
 141
 142 # Option with one parameter (mandatory by default)
 143 abstract class OptionParameter
 144         super Option
 145
 146         # Convert `str` to a value of type `VALUE`.
 147         protected fun convert(str: String): VALUE is abstract
 148
 149         # Is the parameter mandatory?
 150         var parameter_mandatory = true is writable
 151
 152         redef fun read_param(opts, it)
 153         do
 154                 super
 155
 156                 var ok = it.is_ok
 157                 if ok and not parameter_mandatory and not it.item.is_empty and it.item.chars.first == '-' then
 158                         # The next item may looks like a known command
 159                         # Only check if `not parameter_mandatory`
 160                         for opt in opts.options do
 161                                 if opt.names.has(it.item) then
 162                                         # The next item is a known command
 163                                         ok = false
 164                                         break
 165                                 end
 166                         end
 167                 end
 168
 169                 if ok then
 170                         value = convert(it.item)
 171                         it.next
 172                 else
 173                         errors.add("Parameter expected for option {names.first}.")
 174                 end
 175         end
 176 end
 177
 178 # An option with a `String` as parameter
 179 class OptionString
 180         super OptionParameter
 181         redef type VALUE: nullable String
 182
 183         # Init a new OptionString with a `help` message and `names`.
 184         init(help: String, names: String...) is old_style_init do super(help, null, names)
 185
 186         redef fun convert(str) do return str
 187 end
 188
 189 # An option to choose from an enumeration
 190 #
 191 # Declare an enumeration option with all its possible values as an array.
 192 # Once the arguments are processed, `value` is set as the index of the selected value, if any.
 193 class OptionEnum
 194         super OptionParameter
 195         redef type VALUE: Int
 196
 197         # Values in the enumeration.
 198         var values: Array[String]
 199
 200         # Init a new OptionEnum from `values` with a `help` message and `names`.
 201         #
 202         # `default` is the index of the default value in `values`.
 203         init(values: Array[String], help: String, default: Int, names: String...) is old_style_init do
 204                 assert values.length > 0
 205                 self.values = values.to_a
 206                 super("{help} <{values.join(", ")}>", default, names)
 207         end
 208
 209         redef fun convert(str)
 210         do
 211                 var id = values.index_of(str)
 212                 if id == -1 then
 213                         var e = "Unrecognized value for option {names.join(", ")}.\n"
 214                         e += "Expected values are: {values.join(", ")}."
 215                         errors.add(e)
 216                 end
 217                 return id
 218         end
 219
 220         # Get the value name from `values`.
 221         fun value_name: String do return values[value]
 222
 223         redef fun pretty_default
 224         do
 225                 return " ({values[default_value]})"
 226         end
 227 end
 228
 229 # An option with an Int as parameter
 230 class OptionInt
 231         super OptionParameter
 232         redef type VALUE: Int
 233
 234         # Init a new OptionInt with a `help` message, a `default` value and `names`.
 235         init(help: String, default: Int, names: String...) is old_style_init do
 236                 super(help, default, names)
 237         end
 238
 239         redef fun convert(str) do return str.to_i
 240 end
 241
 242 # An option with a Float as parameter
 243 class OptionFloat
 244         super OptionParameter
 245         redef type VALUE: Float
 246
 247         # Init a new OptionFloat with a `help` message, a `default` value and `names`.
 248         init(help: String, default: Float, names: String...) is old_style_init do
 249                 super(help, default, names)
 250         end
 251
 252         redef fun convert(str) do return str.to_f
 253 end
 254
 255 # An option with an array as parameter
 256 # `myprog -optA arg1 -optA arg2` is giving an Array `["arg1", "arg2"]`
 257 class OptionArray
 258         super OptionParameter
 259         redef type VALUE: Array[String]
 260
 261         # Init a new OptionArray with a `help` message and `names`.
 262         init(help: String, names: String...) is old_style_init do
 263                 values = new Array[String]
 264                 super(help, values, names)
 265         end
 266
 267         private var values: Array[String]
 268         redef fun convert(str)
 269         do
 270                 values.add(str)
 271                 return values
 272         end
 273 end
 274
 275 # Context where the options process
 276 class OptionContext
 277         # Options present in the context
 278         var options = new Array[Option]
 279
 280         # Rest of the options after `parse` is called
 281         var rest = new Array[String]
 282
 283         # Errors found in the context after parsing
 284         var context_errors = new Array[String]
 285
 286         private var optmap = new HashMap[String, Option]
 287
 288         # Add one or more options to the context
 289         fun add_option(opts: Option...) do
 290                         options.add_all(opts)
 291         end
 292
 293         # Display all the options available
 294         fun usage
 295         do
 296                 var lmax = 1
 297                 for i in options do
 298                         var l = 3
 299                         for n in i.names do
 300                                 l += n.length + 2
 301                         end
 302                         if lmax < l then lmax = l
 303                 end
 304
 305                 for i in options do
 306                         if not i.hidden then
 307                                 print(i.pretty(lmax))
 308                         end
 309                 end
 310         end
 311
 312         # Parse and assign options everywhere in the argument list
 313         fun parse(argv: Collection[String])
 314         do
 315                 var it = argv.iterator
 316                 parse_intern(it)
 317         end
 318
 319         # Must all option be given before the first argument?
 320         #
 321         # When set to `false` (the default), options of the command line are
 322         # all parsed until the end of the list of arguments or until "--" is met (in this case "--" is discarded).
 323         #
 324         # When set to `true` options are parsed until the first non-option is met.
 325         var options_before_rest = false is writable
 326
 327         # Parse the command line
 328         protected fun parse_intern(it: Iterator[String])
 329         do
 330                 var parseargs = true
 331                 build
 332                 var rest = rest
 333
 334                 while parseargs and it.is_ok do
 335                         var str = it.item
 336                         if str == "--" then
 337                                 it.next
 338                                 rest.add_all(it.to_a)
 339                                 parseargs = false
 340                         else
 341                                 # We're looking for packed short options
 342                                 if str.chars.last_index_of('-') == 0 and str.length > 2 then
 343                                         var next_called = false
 344                                         for i in [1..str.length[ do
 345                                                 var short_opt = "-" + str.chars[i].to_s
 346                                                 if optmap.has_key(short_opt) then
 347                                                         var option = optmap[short_opt]
 348                                                         if option isa OptionParameter then
 349                                                                 it.next
 350                                                                 next_called = true
 351                                                         end
 352                                                         option.read_param(self, it)
 353                                                 end
 354                                         end
 355                                         if not next_called then it.next
 356                                 else
 357                                         if optmap.has_key(str) then
 358                                                 var opt = optmap[str]
 359                                                 it.next
 360                                                 opt.read_param(self, it)
 361                                         else
 362                                                 rest.add(it.item)
 363                                                 it.next
 364                                                 if options_before_rest then
 365                                                         rest.add_all(it.to_a)
 366                                                         parseargs = false
 367                                                 end
 368                                         end
 369                                 end
 370                         end
 371                 end
 372
 373                 for opt in options do
 374                         if opt.mandatory and not opt.read then
 375                                 context_errors.add("Mandatory option {opt.names.join(", ")} not found.")
 376                         end
 377                 end
 378         end
 379
 380         private fun build
 381         do
 382                 for o in options do
 383                         for n in o.names do
 384                                 optmap[n] = o
 385                         end
 386                 end
 387         end
 388
 389         # Options parsing errors.
 390         fun errors: Array[String]
 391         do
 392                 var errors = new Array[String]
 393                 errors.add_all context_errors
 394                 for o in options do
 395                         for e in o.errors do
 396                                 errors.add(e)
 397                         end
 398                 end
 399                 return errors
 400         end
 401 end