Value (Interface Manipulation Package)

[using it]

Interface Manipulation Package v4.0 (2008-06-25)

©copyright

imp.core
Class Value

java.lang.Object
  imp.core.Value

All Implemented Interfaces:: Cloneable, Comparable<Value>

Direct Known Subclasses:: Chars, Condition, Measure, Numeric, Structure, Time

public class Value
extends Object
implements Cloneable, Comparable<Value>
extends Object
implements Cloneable, Comparable<Value>

Defines a string-value and the basic capability of a value in this context.

A value is the root object in this implementation. It has a name (its type, defining which kind of value) and the value itself.

Primitive values are:

condition: boolean values corresponding to true/false values. Represented as a string with the convention that if equal to the (case insensitive) word true the related boolean value is true and false otherwise.
name: naming logical structures and fields.
number: numeric values, implemented using high-precision calculations.
string: non formatted char-sequences. Complex strings are enclosed between quotes (e.g. "my string" or `yet another string').

Structured values are logical-structure the basic data being:

enumeration: closed list of names, separated by either a tabulation '\t' or a white space ' '.
expression: algebraic/boolean/functional expressions.
location: uniform resource identifier of a location.
measure: a physical numerical parameter.
date: date with time.
text: structured, annotated text with links.

These values form a hierarchy:

In this context each value:

can be created from a XML string, and have a canonical XML string-value,
can be loaded / saved from / into a location,
is a null value by default,
may have some property, either fields or elements,
is cloneable and comparable as any other objects.

Field Summary
`static Value`	`NULL` The null value of type "imp:null".

Method Summary
`Value`	`add(int index, Value element)` Adds, inserts or deletes an element and return this.
`Value`	`cloneThis()` Creates and returns a copy of this value and all its fields and elements.
`static Value`	`create(String value)` Creates a value from a XML string definition and return it.
`Value[]`	`elements()` Gets all elements of this value.
`String[]`	`fields()` Gets all fields names of this value.
`Value`	`get(String name, Value value)` Gets a property of this value.
`String`	`getType()` Returns the type of this value.
`static Value`	`getWrapping(Object object, Value value)` Gets a wrapping of the current java object.
`boolean`	`isCyclic()` Tests if this value is cyclic.
`static boolean`	`isName(String name)` Tests if the string is a valid name.
`int`	`length()` Returns the number of elements.
`static Value`	`load(String location)` Loads a value from a location.
`static void`	`main(String[] arguments)` Checks a if a XML document is well-formed and contains a valid value in this context.
`Value`	`save(String location)` Saves this value into a location, thus erase the previous stored value, and return this.
`Value`	`set(String name, Value value)` Sets a property of this value.
`String`	`stringValue()` Returns the value of this object as a string.
`String`	`toString()` Returns this value as a string.
`Object`	`wrappedObject()` Gets the wrapped object if any.

Methods inherited from class java.lang.Object
`getClass, notify, notifyAll, wait, wait, wait`

Field Detail

NULL

public static final Value NULL

The null value of type "imp:null".

By contract a value is null if it is this NULL value.

Method Detail

add

public Value add(int index,
                 Value element)

Adds, inserts or deletes an element and return this.

With this method, the element is inserted in the list, shifting any subsequent elements to the right, while subsequent elements are shifted to the left when deleted, whereas the set() method allows to set/replace/cancel elements without shifting other.

Parameters:: index - [optional, default is -1] The element index, from 0. A value of -1 means to append the element at the end of the list (default).; element - The element to insert. If the element value is null, the corresponding element is deleted. The java null value is not allowed.
As Boolean,Number,String:
The element as a scalar value.
Returns:: A reference to this object, allowing to define some predefined values with the following construct: new Value().add(index_i, value_i). ...
Throws:: IllegalStateException - if the index is not valid or the element cannot written.; IllegalArgumentException - if the element value is not valid.

cloneThis

public Value cloneThis()

Creates and returns a copy of this value and all its fields and elements.

create

public static Value create(String value)
                    throws IllegalArgumentException

Creates a value from a XML string definition and return it.

The root logical structures of the well-formed XML construct contained in the string is parsed, even if the entry has some obviously recoverable syntax error or unused (thus ignored) deprecated XML syntax features.

Parameters:: value - The value defined as an XML string.
As String[]:
The values correspond to a sequence of the form
(-name ( (-)? value )? | (-)? element_1 .. )?* (here - stands for it-self)
which is the common syntax of software applications parametrization and is typically provided by a public static void main(String value[]) construct when specifying a standalone application program.
Throws:: IllegalArgumentException - If the value can not be parsed.

elements

public Value[] elements()

Gets all elements of this value.

A element is a property with an numeric name (not a literal one).

Returns:: An array with all elements.

fields

public String[] fields()

Gets all fields names of this value.

A field is a property with an literal name (not a numeric one).

Returns:: An array with all fields names.

get

public final Value get(String name,
                       Value value)

Gets a property of this value.

Parameters:: name - The property name: either literal or numeric.; value - [optional, default is NULL] Default value returned if the field value is undefined.
As Boolean,Number,String:
The default value as a scalar value.
Returns:: The property value or the NULL value if undefined.

getType

public String getType()

Returns the type of this value.

Returns:: The java or user-defined type as an XML name.

getWrapping

public static final Value getWrapping(Object object,
                                      Value value)

Gets a wrapping of the current java object.

Parameters:: object - The object to be wrapped.; value - [optional, default is null] Fields and elements to be copied in the wrapped object.

isCyclic

public boolean isCyclic()

Tests if this value is cyclic.

A value is cyclic if in its field/element tree, there is a reference to itself or to a cyclic value.

Returns:: True if this value is cyclic.

isName

public static final boolean isName(String name)

Tests if the string is a valid name.

Parameters:: name - The string to test.
Returns:: True is the string is valid name.

length

public int length()

Returns the number of elements.

The length of a logical-structure is the number of elements (it is formally defined as the maximal value of numerical attributes).

The following construct allows to enumerate the elements: for(int i = 0; i < my_imp.length(); i++) { Value element_i = my_imp.get(i); ../.. }.

Returns:: The element list length (thus 0 if no element).

load

public static final Value load(String location)
                        throws IOException,
                               IllegalArgumentException

Loads a value from a location.

Parameters:: location - The location where the value is stored as a string.
Throws:: IOException - If the location can not be read.; IllegalArgumentException - If the value can not be parsed.

main

public static void main(String[] arguments)

Checks a if a XML document is well-formed and contains a valid value in this context.

Usage: $JAVA imp.core.Value [-list] <document-file> to check if a document is well-formed and valid in this context.

-list : list the value on the output.

Usage: $JAVA imp.core.Value to run a few tests regarding the imp core internal mechanisms.

save

public final Value save(String location)
                 throws IOException

Saves this value into a location, thus erase the previous stored value, and return this.

Parameters:: location - The location where the value is stored as a string.
Throws:: IOException - If the location can not be read.

set

public Value set(String name,
                 Value value)

Sets a property of this value.

By contract literal properties are implemented via setName(value) methods.

Parameters:: name - The property name: either literal or numeric.
As int:
The property index.; value - [optional, default is true] The property value: either a value or a string or any compatible object.
As Boolean,Number,String:
The value as a scalar value.
Returns:: A reference to this object, allowing to define some predefined values with the following construct: new Value().add(index_i, value_i). ...
Throws:: IllegalStateException - If the value can not be set.; IllegalArgumentException - If the value can not be parsed.

stringValue

public String stringValue()

Returns the value of this object as a string.

Returns:: The value (i.e. the field of name value) of this object as a string or "" if the object is not defined by its value.

toString

public final String toString()

Returns this value as a string.

By contract, each value has a canonical XML string representation.

As a consequence each value is serializable as a string.

Overrides:: toString in class Object

Returns:: This object as a string.

wrappedObject

public Object wrappedObject()

Gets the wrapped object if any.

Returns:: The wrapped object is this value is a Java object wrapping, otherwise return this.

imp.core Class Value