In the parlance of MIC, a datatype is a field. That is, each field has associated with it a single datatype object that manages the values associated with that field. The term `field' and `datatype' will be used interchangeably as clarity dictates.
A datatype is an encapsulator of data that knows what type of data it expects to be encapsulating and how it expects to display itself. It will generally be able to detect errors in the form or range of the data, though exactly what will be detected is outside of the scope of this specification.
list/scalar value ()
This will return the value encapsulated and will function appropriately in either a list or scalar context. The value that is returned might not be the value that was received as the functions verify, format and canonicalize may all act to change the form of the value, though not its canonical value.
set_value (list/scalar value)
Will set the value to value. Note that this will not cause MIC to think that the value has changed if called directly in code. It can be used to set default values, though using the default value code portion of a MICdefine is the preferred method for accomplishing this.
set_possible (scalar values)
This function takes a reference to a hash of possible values. For all datatypes, it will make sure that the canonical form of the encapsulated data can be found in the list passed in (there are no constraints if there is no list), and for scroll list, check boxes, etc., it will use this list to generate the user displayed list. The keys are the value of the encapsulated data. See documentation of the datatypes for additional meaning and usage of the keys and values.
list/scalar canonicalize ()
This will examine all the values associated with the field and try and massage the data into canonical form as defined for the datatype specified for the field. If successful (i.e., all the data forms were recognized and successfully tranformed), then it will return the list or the first member of the list of values. If not successful it will raise an exception.
verify ()
This will run field verification functions on the field to make sure that the encapsulated data conforms to the canonical form and possibly further restrictions. If there is an error, then it will throw an error of a specific type. A human readable description of the errors should be accessible by the text() method defined on the error which should return a reference to an array of messages.
scalar/list format (bool quite)
This will format the canonical data as per the users request. If the quite flag is set, then errors will be quitely ignored. If not set, then this function may throw an exception. If successful, it will return the formatted value.
scalar call_me (scalar name)
This will return the name by which this field should be referred to for the end user. It will optionally take a new name. Note that there is not any requirement to treat various dynamics differntly. That is, it's okay if all of them are required to have the same name.