unless @options[i].valuestring = argv_array.shift                      
         raise "\n  option \"#{s}\" requires a value, but no value given;\n" +
               "  option description: #{@options[i].description}\n"           

In most cases, after encountering a new option name, you just read in the value corresponding to that option, as the next little string that came from the command line. If there is nothing left to be parsed on the command line, that just means that the user has forgotten to provide a value: an error message is printed, and execution of the code is halted.

Alice: But what happens if the user provides a next option, instead of the value for the previous option? Imagine that the user writes -n -x.

Bob: In that case, an attempt will be made to set the number of particles to -x, which will result in something silly. But hey, we can't protect the user from all possible errors! I don't know how to anticipate on this level what is and is not correct. Others, using this code in the future, will undoubtedly use it for more general purposes than I can currently envision, so I don't want to constrain too much what can and cannot be said.

Alice: Hmmm. You could at least insist that a valid number would be provided when the type of a variable is given as an int or float.

Bob: Perhaps. We could come back to those questions later, and try to make everything industrial-strength. For the time being, I'm happy if everything works under reasonably normal circumstances with reasonably intelligent users.

Alice: Well, if you talk about users that don't make errors, then I have to conclude that nobody fits the criterion of being `reasonably intelligent'. But okay, for now let's move on. I'd probably want to come back to this point later, though.

4.6. Extracting the Value: Compact Case

     if s =~ /^-[^-]/ and (value = $') =~ /\w/                                
       @options[i].valuestring = value                                        

This addresses the case where a one-character option is used, without any space separating the option and the value, as in -n3, a very compact notation which we already discussed before.

Alice: What is the meaning of this funny looking repetition of the symbols ^-? They occur twice, with a square bracket in between, and a closing bracket at the end, as ^-[^-].

Bob: This is one of the most confusing aspects in the notation of regular expressions, this overloading of the meaning of the up-arrow ^. In fact, the two up-arrows here are two completely different things. In order to see this, let us inspect the whole regular expression:

            /^-[^-]/

Alice: Yes, that notation I am familiar with. But how can you start at the beginning of a line for the second time.

Bob: You don't. Within square brackets, the up-arrow ^ has the effect of negating the meaning of the next character. So the combination [^-] simply means: any character but the - character!

In other words, by writing

    if s =~ /^-[^-]/

  |gravity> irb
  irb(main):001:0> "-n" =~ /^-[^-]/
  => 0
  irb(main):002:0> "--nono" =~ /^-[^-]/
  => nil

Bob: You'll get used to it.

4.7. Interesting or Confusing?

     if s =~ /^-[^-]/ and (value = $') =~ /\w/                                
       @options[i].valuestring = value                                        

You have told me that the variable $' contains the rest of the string, the part after the part which matched. So if we start with the option "-n", and if we insist that it should start with one and only one hyphen, then $' = n, right?

Bob: Wrong.

Alice: Huh?

Bob: Try it!

Alice: Okay:

  |gravity> irb
  irb(main):001:0> s = "-n"
  => "-n"
  irb(main):002:0> s =~ /^-[^-]/
  => 0
  irb(main):003:0> $'
  => ""

Bob: Why don't you try the compact option-value notation -n3

Alice: Here goes:

  irb(main):004:0> s = "-n3"
  => "-n3"
  irb(main):005:0> s =~ /^-[^-]/
  => 0
  irb(main):006:0> $'
  => "3"

Bob: What happened is that the matching attempt s =~ /^-[^-]/ involves two characters: first the hyphen and then the next character, for which it is checked that it is not a hyphen.

Alice: Ah, although in plain English we can describe this match as `a check that there is one and only one hyphen', in fact it is a match where the first two characters are being checked as being an ordered pair `hyphen followed by non-hyphen.'

Now I see what happened. And since this all happens in the case of a one-character option, the non-hyphen that gets eaten is the option character, so that what is left is exactly the value that needs to be assigned to the variable corresponding to the option.

So what you do at the end of this complicated line, is that you check whether the remainder, stored in $' contains at least one alphanumeric character or underscore, which is what the \w stands for.

Bob: Exactly.

Alice: Okay, I see now what happens. But I think you could have written this in a simpler way.

Bob: How?

Alice: Instead of

    if s =~ /^-[^-]/ and (value = $') =~ /\w/

    if s =~ /^-\w/ and (value = $') =~ /\w/

Alice: I just find it confusing, rather than interesting, but to each his own taste! Let's move on to the last case, at the end.

4.8. Extracting the Value: Vector Case

     if @options[i].type =~ /^float\s*vector$/                                
       while (@options[i].valuestring !~ /\]/)                                
         @options[i].valuestring += " " + argv_array.shift                    

You allow some flexibility in writing the type: it could be float vector or float vector or even float vector.

Bob: Sure, it would seem to restricted to insist on one literal way of writing it. I can easily see someone adding an extra space between the two words, and perhaps a tab or whatever would strike them as looking better. I have consistently given the users that freedom, also in parsing the lines within the Clop_Option class, as we will see in our next journey.

Alice: And then you keep shifting new content from the ARGV array until you finally encounter a string that contains a closing square bracket ]. During that whole process, you keep adding what you find to the valuestring of the option you are working with, so that you build up the whole vector again, from the bits and pieces from the command line that were stored in successive elements of the ARGV array, here called argv_array.

One last question: why don't you just string those strings together? What is the need for adding a " " between the bits and pieces?

Bob: If all the vector elements were comma separated, as in [2,3,4], there would be no need to do so. However, I give the user the flexibility to use a space separated notation as well. Take the example of a vector written as [2 3]. In the ARGV array, this will be distributed over two elements, the first being "[2" and the second one "3]". Now if you would just string those two strings together, as you suggested, you would get "[23]", a one-dimensional vector with one element, 23. Not what you wanted.

Alice: I see. Good! Now I believe there is one station left on our first journey?

4.9. Inspecting initialize_global_variables

   def initialize_global_variables
     @options.each{|x| x.initialize_global_variable}
     check_required_options
   end    

I am asking each option to do its own work, initializing the internal variables that contain the external information presented on the command line. For example, the time step value may have been presented on the command line as -d 0.001, and in order to give that value to the method evolve that we have used to integrate an N-body system, we have to store it somewhere in a variable, which we would normally called dt or something like that.

As we have seen in our new driver, for convenience we chose to use global variables, which means the name actually has to be something like $dt. Now the conversion from the string -d 0.001 to the actual floating point numerical value $dt = 0.001 is being done within the Clop_Option class, by its method initialize_global_variable.

Alice: And then you check something about the options. What do you mean with `required'?

Bob: For many options, a default value is specified, in the original definition string. However, for some options there is no natural default. For example, you may not want to specify a default value for an output file. Not only is there no obviously appropriate name for such a file, you don't want to risk overwriting another file that the user may have added to the current directory. In that case, you could start the entry for the output file option in the original here document with:

  Short name:           -o
  Long name:            --output_file_name
  Value type:           string
  Default value:        none

Alice: Instead of check_whether_all_required_options_have_been_provided, you abbreviated the method name. Even for me an eight-word name would have been too long. Can you show me the code?

Bob: Here it is, all very straightforward.

   def check_required_options
     options_missing = 0
     @options.each do |x|
       if x.valuestring == "none"
         options_missing += 1
         STDERR.print "option "
         STDERR.print "\"#{x.shortname}\" or " if x.shortname
         STDERR.print "\"#{x.longname}\" required.  "
         STDERR.print "Description:\n#{x.longdescription}\n"
       end
     end
     if options_missing > 0
       STDERR.print "Please provide the required command line option"
       STDERR.print "s" if options_missing > 1
       STDERR.print ".\n"
       exit(1)
     end
   end

Alice: All clear! I think this finishes our first journey?

Bob: Yes, time to finally descend into the Clop_Option class.

Previous

ToC

Up

Next