32.10 Parameter Ranges and Legal/Illegal Values

Some parameters can have legal/illegal ranges and values. These are set with the !LEGAL_VALUE , !ILLEGAL_VALUE , !LEGAL_RANGE and !ILLEGAL_RANGE fields.

bool: Boolean parameters cannot have legal/illegal ranges and values
int, float and double: These parameters can have legal and illegal ranges and values. Checks for illegal ranges and values are performed first and if an invalid range or value is detected an error is returned. Then legal ranges and values are checked, and if the parameter setting matches or there are no legal ranges or values it passes. 'inf' and '-inf' are values are recognized as range limits, along with regular numerical values.
string, file and param_file: These parameters can have legal and illegal values, but not ranges. For file and param_file types the restriction is on the file name. Illegal values are check first, and a then if at least one legal value is specified it is check also. Legal and Illegal values for these types support up to 2 * wildcards for pattern matches. This is commonly used to force a file extension (e.g., "!LEGAL_VALUE *.txt").
OEMol and OEGraphMol: Molecule parameters cannot have legal and illegal ranges and values, however they are automatically restricted to files with recognized file extensions.

Chapter 32 - Example 13 : cpp file

#include "oeplatform.h"
#include "oesystem.h"

//Defines static const unsigned char* array InterfaceData
#include "ch32-13.itf"

//Defines static const unsigned char* array RequirementData
#include "ch32-13r.req"

using namespace OEPlatform;
using namespace OESystem;
using namespace std;
int main(int argc, char** argv)
{
  OEInterface itf;
  OEConfigure(itf,InterfaceData);
  if (OECheckHelp(itf,argc,argv)) return 0;
  OEParseCommandLine(itf,argc,argv,RequirementData);

  if (!itf.Has<string>("-op"))
  {
    OEThrow.Error("You must specify -op");
    return 1;
  }

  string op = itf.Get<string>("-op");
  float x = itf.Get<float>("-x");
  float y = itf.Get<float>("-y");

  if (op == "add")
  {
    oeout << x << " plus " << y << " is " << x+y << oeendl;
  }
  else if (op == "subtract")
  {
    oeout << x << " minus " << y << " is " << x-y << oeendl;
  }
  else if (op == "multiply")
  {
    oeout << x << " times " << y << " is " << x*y << oeendl;
  }
  else if (op == "divide")
  {
    oeout << x << " divided by " << y << " is " << x/y << oeendl;
  }

  //This isn't needed since op is now restricted to legal values
  //else
  //{
  //  OEThrow.Error("%s is not a valid operation",op.c_str());
  //  return 1;
  //}

  return 0;
}

Chapter 32 - Example 13 : OEConfigure txt configuration file

!CATEGORY Variables
  !BRIEF Category for variables

  !PARAMETER -x
    !TYPE float
    !DEFAULT 10
    !LEGAL_RANGE -inf -10
    !LEGAL_RANGE 10 1000
    !BRIEF First variable
  !END

  !PARAMETER -y
    !TYPE float
    !DEFAULT 0.0
    !LEGAL_RANGE 0 inf
    !BRIEF Second variable
  !END

!END

!CATEGORY operator

  !PARAMETER -op
    !TYPE string
    !BRIEF Operation to perform on x and y
    !REQUIRED yes
    !LEGAL_VALUE add
    !LEGAL_VALUE substract
    !LEGAL_VALUE multiply
    !LEGAL_VALUE divide
    !DETAIL
      The operation performed is

        x <-op> y

      So if -op is 'add' the operation is

        x + y
  !END

!END

Chapter 32 - Example 13 : Requirement txt configuration file

!REQUIREMENT
  !OPTION -y 0.0 !-op divide
  !OPTION !-y 0.0
  !ERROR_MSG
    Cannot divide by zero
    result would be undefined
!END

The following is example output from the above example program.

> ch32-13 -x -1 -y -1 -op add
Fatal: -1 is not a legal setting for parameter -x (specified on command line)

> ch32-13 -x -1 -y -1 -op divide
Fatal: -1 is not a legal setting for parameter -x (specified on command line)

> ch32-13 -x -99999 -y -1 -op divide
Fatal: -1 is not a legal setting for parameter -y (specified on command line)

> ch32-13 -x -99999 -y 0 -op divide
Fatal: Missing requirements:
    Cannot divide by zero
    result would be undefined

> ch32-13 -x -99999 -y 0 -op add
-99999.000000 plus 0.000000 is -99999.000000

>

The basic rules for the value range checking are

The parameter setting must not fall within or on an illegal range or value.
The parameter setting must fall with or on a legal range or value IF AND ONLY IF at least one legal range or value has been specified.

IMPORTANT: Default parameter values must be legal values.

				OEChem - C++ Theory Manual Version 1.3.1

				OEChem - C++ Theory Manual Version 1.3.1