Module dev.civl.gmc
Package dev.civl.gmc

Class GMCSection

java.lang.Object
dev.civl.gmc.GMCSection
All Implemented Interfaces:
Serializable
public class GMCSection extends Object implements Serializable

A GMCSection has a unique name and it encapsulates a set of key-value pairs, where the keys correspond to commandline parameters and the value is the value assigned to that parameter. In addition, there can be any number of "free arguments" that are not assigned to any parameter. The free arguments are always strings.

A section is typically generated by parsing a command line, or at least the suffix of a command line after the initial command(s). The command line suffix -verbose -errBound=10 filename.c, for example, would yield an anonymous section in which "verbose" is mapped to true, "errBound" is mapped to the integer 10, and with one free argument "fileName.c". An anonymous section has the name "anonymous" which is a reserved name for anonymous sections.

Each GMCSection has associated to it a configuration, which has it either as the anonymous section or in its section map.

Each option is an instance of class Option. An option has a name and a type. The type is one of STRING, INTEGER, DOUBLE, BOOLEAN, or MAP. The type determines the kind of value that can be assigned to an option. The first four are "scalar" types and take values of type String, Integer, Double, and Boolean, respectively.

An option of MAP type may be assigned a value of type Mapinvalid input: '<'String,Object>. This kind of option is provided for command line arguments such as -inputX=10 -inputB=true -inputZ="hello". This constructs a map from String to Object which maps "X" to the Integer 10, "B" to the Boolean true, and "Z" to the String "hello". This map is the value that is assigned to the option named "input". In general, the values of the map can be any scalar values, and their types will be inferred from their format. For example 1.0 will be interpreted as a Double, 1 as an Integer, "1" (with quotes) a String.

See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    GMCSection(GMCConfiguration config, String name)
    Constructs a new instance of GMCSection with the given GMCConfiguration and name.
    GMCSection(String name)
    Constructs a new GMCSection with the given name

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addFreeArg(String arg)
    Adds a free argument to the list of free arguments associated to this configuration.
    GMCSection
    clone()
    Returns a deep copy of this configuration.
    String
    getFreeArg(int i)
    Returns the i-th free argument, indexed from 0.
    Object
    getMapEntry(Option option, String key)
    Given an option of map type, and a key, this returns the value associated to the key in the map associated to option.
    Map<String,Object>
    getMapValue(Option option)
    Gets the map value associated to an option of map type, or null if no value is associated to that option.
    String
    getName()
    Returns the name of this section.
    int
    getNumFreeArgs()
    Returns the current number of free arguments associated to this configuration.
    Object
    getValue(Option option)
    Gets the value associated to an option or null if no value is associated to that option.
    Object
    getValueOrDefault(Option option)
    Returns the value associated to an option or the default value for that option if no value is associated to it.
    boolean
    isTrue(Option option)
    Determines whether the value associated to a boolean option should be construed as true in most circumstances.
    void
    print(PrintStream out)
    Prints the current state of this configuration in a manner similar to what would appear on a commandline.
    Object
    putMapEntry(Option option, String key, Object value)
    Given an option of map type, adds or removes the key-value pair to the map corresponding to that option.
    void
    read(GMCSection that)
    Modifies this section by reading in the values of the given configuration and using those to set values of this one.
    void
    setConfiguration(GMCConfiguration config)
    Updates the configuration associates with this section.
    Map<String,Object>
    setMapValue(Option option, Map<String,Object> value)
    Sets map value or removes map entry from this configuration.
    Object
    setScalarValue(Option option, Object value)
    Adds the key-value pair for a scalar value to the parameter map.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • GMCSection

      public GMCSection(String name)
      Constructs a new GMCSection with the given name
      Parameters:
      name - the name of the section

    • GMCSection

      public GMCSection(GMCConfiguration config, String name)
      Constructs a new instance of GMCSection with the given GMCConfiguration and name.
      Parameters:
      config - The GMCConfiguraiton that the new section associates with.
      name - The name of the new section

  • Method Details

    • getValue

      public Object getValue(Option option)
      Gets the value associated to an option or null if no value is associated to that option.
      Parameters:
      option - an option associated to this configuration
      Returns:
      the value assigned to the option or null
      Throws:
      IllegalArgumentException - if the given option is not associated to this configuration

    • getValueOrDefault

      public Object getValueOrDefault(Option option)
      Returns the value associated to an option or the default value for that option if no value is associated to it.
      Parameters:
      option - an option associated to this configuration
      Returns:
      the value assigned to the option or the option's default value
      Throws:
      IllegalArgumentException - if the given option is not associated to this configuration

    • getMapValue

      public Map<String,Object> getMapValue(Option option)
      Gets the map value associated to an option of map type, or null if no value is associated to that option.
      Parameters:
      option - an option of map type controlled by this configuration
      Returns:
      the map value associated to the option or null
      Throws:
      IllegalArgumentException - if the given option does not have map type or is not associated to this configuration

    • getMapEntry

      public Object getMapEntry(Option option, String key)
      Given an option of map type, and a key, this returns the value associated to the key in the map associated to option. If the map associated to this option is null, this returns null. If there is no entry in the map for the key, this returns null.
      Parameters:
      option - an option of map type associated to this configuration
      key - a string to be used as the key in the map
      Returns:
      the value associated to the key or null

    • isTrue

      public boolean isTrue(Option option)
      Determines whether the value associated to a boolean option should be construed as true in most circumstances. Specifically: if there is a value associated to this option, this method will return that value. If there is no value associated to this option but the default value for the option is true, this method will return true, otherwise it will return false.
      Parameters:
      option - an option of boolean type controlled by this configuration
      Returns:
      true iff there is a value associated to that option and it is true or there is no value associated to the option and the option's default value is true
      Throws:
      IllegalArgumentException - if the given option is not associated to this configuration or does not have boolean type

    • getNumFreeArgs

      public int getNumFreeArgs()
      Returns the current number of free arguments associated to this configuration.
      Returns:
      number of free arguments

    • getFreeArg

      public String getFreeArg(int i)
      Returns the i-th free argument, indexed from 0.
      Parameters:
      i - integer in range 0..n-1, where n is the current number of free arguments assigned to this configuration
      Returns:
      the i-th free argument

    • getName

      public String getName()
      Returns the name of this section.
      Returns:
      the name of this section

    • addFreeArg

      public void addFreeArg(String arg)
      Adds a free argument to the list of free arguments associated to this configuration.
      Parameters:
      arg - a String

    • setScalarValue

      public Object setScalarValue(Option option, Object value)
      Adds the key-value pair for a scalar value to the parameter map. If an entry with that key already exists, it is replaced by the new one. If the value is null, this instead removes the entry with that key (if one exists), returning the old entry.
      Parameters:
      value - the value to associate to the parameter; either null or a non-null Boolean, Integer, Double, or String
      key - a non-null string, the name of the parameter
      Returns:
      the previous value associated to key, or null if there was none
      Throws:
      IllegalArgumentException - if option is not associated to this configuration, or if value does not have a type compatible with the type of the option, or if the option has MAP type

    • setMapValue

      public Map<String,Object> setMapValue(Option option, Map<String,Object> value)
      Sets map value or removes map entry from this configuration.
      Parameters:
      option - an option of MAP type associated to this configuration
      value - a map to assign to that option, or null
      Returns:
      the old map value associated to the option, or null if there wasn't one
      Throws:
      IllegalArgumentException - if the option is not associated to this configuration, or if option's type is not MAP

    • putMapEntry

      public Object putMapEntry(Option option, String key, Object value)
      Given an option of map type, adds or removes the key-value pair to the map corresponding to that option. If the given option does not currently have an assigned value, a new empty map is created for it. If the key is null, this removes the entry with that key if one exists.
      Parameters:
      option - an option of map type that is associated to this configuration
      key - a string which is the key for the map entry
      value - a scalar value which is an instance of one of String, Integer, Double, or Boolean
      Returns:
      the previous value associated to that key or null if there was none
      Throws:
      IllegalArgumentException - if the given option is not associated to this configuration, or it does not have map type

    • clone

      public GMCSection clone()
      Returns a deep copy of this configuration. The two configurations will share references to the same options, and to the same Strings, but not to anything else. As options and strings are immutable, this should not be a problem.
      Returns:
      deep copy of this section

    • read

      public void read(GMCSection that)
      Modifies this section by reading in the values of the given configuration and using those to set values of this one. Existing entries in this one may be overwritten in the process.
      Parameters:
      that - another configuration; the set of options associated to that should be a subset of the set of options associated to this

    • print

      public void print(PrintStream out)
      Prints the current state of this configuration in a manner similar to what would appear on a commandline. Each scalar assignment appears on one line. At the end the free arguments are printed, one on each line. Never prints the name of anonymous sections.
      Parameters:
      out - print stream to which to print

    • setConfiguration

      public void setConfiguration(GMCConfiguration config)
      Updates the configuration associates with this section.
      Parameters:
      config - The configuration that this section belongs to.