EF.Tree

Defines the tree and node class that implement a tree of named data values. A tree can represent a Yaml file or a JSON stream, for example.

TEFDataType class

Base class for node data types. The system supports pluggable data types. Descendants of this class define how to interpret, store, copy, encode and decode data of a particular type.

class function GetTypeName: string;

Returns the type's registration name (the class name stripped of the 'TEF' prefix and 'DataType' suffix).

class function HasSize: Boolean;

Returns True if this data type has a meaningful size (such as a string length).

class function HasScale: Boolean;

Returns True if this data type has a meaningful scale (number of decimal digits).

class function GetFieldType: TFieldType;

Returns the TFieldType that corresponds to this data type.

class function NeedsQuotes: Boolean;

Returns True if values of this type need to be quoted (for example in SQL or Yaml).

class procedure SetNodeDataTypeAndValueFromYaml(const AYamlValue: string;

Guesses a suitable data type from a Yaml value string and sets ANode's data type and value accordingly. When APreferStrings is True numbers are kept as strings.

procedure FieldValueToNode(const AField: TField;

Reads AField's value into ANode, setting the node to null when the field is null.

procedure NodeToField(const ANode: TEFNode;

Writes ANode's value into AField, clearing the field when the node is null.

procedure NodeToParam(const ANode: TEFNode;

Writes ANode's value into AParam, setting the param to null when the node is null.

procedure YamlValueToNode(const AYamlValue: string;

Parses a Yaml value string into ANode according to this data type.

function GetDefaultDisplayWidth(const ASize: Integer): Integer;

Returns the default display width, in characters, for a value of the given size.

function GetDefaultColumnAlignment: string;

Returns the default column alignment ('left', 'right', ...) for this data type.

function SupportsEmptyAsNull: Boolean;

Returns True if an empty value may be treated as null for this data type.

function GetDefaultEmptyAsNull: Boolean;

Returns the default EmptyAsNull setting for this data type.

function SupportsJSON: Boolean;

Returns True if values of this type can be represented in JSON.

function SupportsXML: Boolean;

Returns True if values of this type can be represented in XML.

function IsBlob(const ASize: Integer): Boolean;

Returns True if a value of the given size is stored as a BLOB.

function IsText: Boolean;

Returns True if this is a text data type.

function IsBoolean: Boolean;

Returns True if this is the boolean data type.

function NodeToJSONValue(const AForDisplay: Boolean;

Formats ANode's value as a JSON value, optionally quoted, returning 'null' (or '' if AEmptyNulls) for null nodes.

function NodeToXMLValue(const AForDisplay: Boolean;

Formats ANode's value as an XML element (<Name>value</Name>).

procedure JSONValueToNode(const ANode: TEFNode;

Parses a JSON value string into ANode, setting it to null for empty or 'null' input.

function GetJSTypeName: string;

Returns the JavaScript/ExtJS type name for this data type.

function ValueToString(const AValue: Variant): string;

Converts the stored variant value to a string.

function ValueToInteger(const AValue: Variant): Integer;

Converts the stored variant value to an Integer.

function ValueToObject(const AValue: Variant): TObject;

Converts the stored variant value to an object reference.

function ValueToBoolean(const AValue: Variant): Boolean;

Converts the stored variant value to a Boolean.

function ValueToStringArray(const AValue: Variant): TStringDynArray;

Converts the stored variant value to a string array.

function ValueToPairs(const AValue: Variant): TEFPairs;

Converts the stored variant value to a list of name/value pairs.

function ValueToDate(const AValue: Variant): TDate;

Converts the stored variant value to a Date.

function ValueToTime(const AValue: Variant): TTime;

Converts the stored variant value to a Time.

function ValueToDateTime(const AValue: Variant): TDateTime;

Converts the stored variant value to a DateTime.

function ValueToChar(const AValue: Variant): Char;

Converts the stored variant value to a Char.

function ValueToCurrency(const AValue: Variant): Currency;

Converts the stored variant value to a Currency.

function ValueToFloat(const AValue: Variant): Double;

Converts the stored variant value to a Double.

function ValueToDecimal(const AValue: Variant): TBcd;

Converts the stored variant value to a decimal (BCD).

function ValueToBytes(const AValue: Variant): TBytes;

Converts the stored variant value to a byte array.

function StringToValue(const AString: string): Variant;

Converts a string to this type's variant representation.

function IntegerToValue(const AInteger: Integer): Variant;

Converts an Integer to this type's variant representation.

function ObjectToValue(const AObject: TObject): Variant;

Converts an object reference to this type's variant representation.

function BooleanToValue(const ABoolean: Boolean): Variant;

Converts a Boolean to this type's variant representation.

function StringArrayToValue(const AStringArray: TStringDynArray): Variant;

Converts a string array to this type's variant representation.

function PairsToValue(const APairs: TEFPairs): Variant;

Converts a list of pairs to this type's variant representation.

function DateToValue(const ADate: TDate): Variant;

Converts a Date to this type's variant representation.

function TimeToValue(const ATime: TTime): Variant;

Converts a Time to this type's variant representation.

function DateTimeToValue(const ADateTime: TDateTime): Variant;

Converts a DateTime to this type's variant representation.

function CurrencyToValue(const ACurrency: Currency): Variant;

Converts a Currency to this type's variant representation.

function FloatToValue(const AFloat: Double): Variant;

Converts a Double to this type's variant representation.

function DecimalToValue(const ADecimal: TBcd): Variant;

Converts a decimal (BCD) to this type's variant representation.

function BytesToValue(const ABytes: TBytes): Variant;

Converts a byte array to this type's variant representation.

function CharToValue(const AChar: Char): Variant;

Converts a Char to this type's variant representation.

TEFStringDataType class

Data type for text values (Delphi strings).

class function GetFieldType: TFieldType;

Returns ftString.

function GetDefaultDisplayWidth(const ASize: Integer): Integer;

Returns the default display width for a string of the given size.

function SupportsEmptyAsNull: Boolean;

Returns True: empty strings may be treated as null.

function IsBlob(const ASize: Integer): Boolean;

Returns False: a plain string is not a BLOB.

function GetJSTypeName: string;

Returns the JavaScript type name for strings.

class function HasSize: Boolean;

Returns True: strings have a size (length).

function IsText: Boolean;

Returns True: this is a text data type.

function GetDefaultEmptyAsNull: Boolean;

Returns the default EmptyAsNull setting for strings.

TEFMemoDataType class

Data type for long text (memo) values.

function IsBlob(const ASize: Integer): Boolean;

Returns True when the size marks the value as a BLOB-sized memo.

class function HasSize: Boolean;

Returns False: memo values have no fixed size.

TEFBlobDataType class

Data type for binary (BLOB) values.

class function GetFieldType: TFieldType;

Returns ftBlob.

function IsBlob(const ASize: Integer): Boolean;

Returns True: this is always a BLOB.

function SupportsJSON: Boolean;

Returns False: BLOBs are not represented in JSON.

TEFDateTimeDataTypeBase class

Common base for the Date, Time and DateTime data types.

function GetDefaultEmptyAsNull: Boolean;

Returns the default EmptyAsNull setting for date/time types.

TEFDateDataType class

Data type for date-only values.

class function GetFieldType: TFieldType;

Returns ftDate.

function GetDefaultDisplayWidth(const ASize: Integer): Integer;

Returns the default display width for a date value.

function SupportsEmptyAsNull: Boolean;

Returns True: empty dates may be treated as null.

function InternalFormatNodeValue(const AForDisplay: Boolean;

Formats the node's date value, using ISO format when not for display.

function GetJSTypeName: string;

Returns the JavaScript type name for dates.

function ValueToString(const AValue: Variant): string;

Converts the stored date value to a string.

TEFTimeDataType class

Data type for time-only values.

class function GetFieldType: TFieldType;

Returns ftTime.

function GetDefaultDisplayWidth(const ASize: Integer): Integer;

Returns the default display width for a time value.

function SupportsEmptyAsNull: Boolean;

Returns True: empty times may be treated as null.

function InternalFormatNodeValue(const AForDisplay: Boolean;

Formats the node's time value, using ISO format when not for display.

function ValueToString(const AValue: Variant): string;

Converts the stored time value to a string.

TEFDateTimeDataType class

Data type for combined date and time values.

class function GetFieldType: TFieldType;

Returns ftDateTime.

function GetDefaultDisplayWidth(const ASize: Integer): Integer;

Returns the default display width for a date/time value.

function SupportsEmptyAsNull: Boolean;

Returns True: empty date/times may be treated as null.

function InternalFormatNodeValue(const AForDisplay: Boolean;

Formats the node's date/time value, using ISO format when not for display.

function GetJSTypeName: string;

Returns the JavaScript type name for date/times.

function ValueToString(const AValue: Variant): string;

Converts the stored date/time value to a string.

TEFBooleanDataType class

Data type for boolean values.

class function NeedsQuotes: Boolean;

Returns False: boolean values are not quoted.

class function GetFieldType: TFieldType;

Returns ftBoolean.

function GetDefaultDisplayWidth(const ASize: Integer): Integer;

Returns the default display width for a boolean value.

function InternalFormatNodeValue(const AForDisplay: Boolean;

Formats the node's boolean value as a string.

function GetJSTypeName: string;

Returns the JavaScript type name for booleans.

function IsBoolean: Boolean;

Returns True: this is the boolean data type.

TEFNumericDataTypeBase class

Common base for the numeric data types (Integer, Float, Currency, Decimal).

class function NeedsQuotes: Boolean;

Returns False: numeric values are not quoted.

TEFIntegerDataType class

Data type for integer values.

class function GetFieldType: TFieldType;

Returns ftInteger.

function GetDefaultColumnAlignment: string;

Returns 'right': integers are right-aligned.

function GetDefaultDisplayWidth(const ASize: Integer): Integer;

Returns the default display width for an integer value.

function GetJSTypeName: string;

Returns the JavaScript type name for integers.

TEFDecimalNumericDataTypeBase class

Common base for the decimal numeric data types (Currency, Float, Decimal).

TEFCurrencyDataType class

Data type for currency (monetary) values.

class function GetFieldType: TFieldType;

Returns ftCurrency.

function GetDefaultColumnAlignment: string;

Returns 'right': currency values are right-aligned.

function GetDefaultDisplayWidth(const ASize: Integer): Integer;

Returns the default display width for a currency value.

function SupportsEmptyAsNull: Boolean;

Returns True: empty currency values may be treated as null.

function InternalFormatNodeValue(const AForDisplay: Boolean;

Formats the node's currency value as a string.

function GetJSTypeName: string;

Returns the JavaScript type name for currency values.

class function HasSize: Boolean;

Returns True: currency values have a size.

class function HasScale: Boolean;

Returns True: currency values have a scale.

TEFFloatDataType class

Data type for floating-point values.

class function GetFieldType: TFieldType;

Returns ftFloat.

function GetDefaultColumnAlignment: string;

Returns 'right': float values are right-aligned.

function GetDefaultDisplayWidth(const ASize: Integer): Integer;

Returns the default display width for a float value.

function SupportsEmptyAsNull: Boolean;

Returns True: empty float values may be treated as null.

function InternalFormatNodeValue(const AForDisplay: Boolean;

Formats the node's float value as a string.

function GetJSTypeName: string;

Returns the JavaScript type name for float values.

TEFDecimalDataType class

Data type for high-precision decimal (BCD) values.

class function GetFieldType: TFieldType;

Returns ftFMTBcd.

function GetDefaultColumnAlignment: string;

Returns 'right': decimal values are right-aligned.

function GetDefaultDisplayWidth(const ASize: Integer): Integer;

Returns the default display width for a decimal value.

function SupportsEmptyAsNull: Boolean;

Returns True: empty decimal values may be treated as null.

function InternalFormatNodeValue(const AForDisplay: Boolean;

Formats the node's decimal value as a string.

function GetJSTypeName: string;

Returns the JavaScript type name for decimal values.

class function HasSize: Boolean;

Returns True: decimal values have a size.

class function HasScale: Boolean;

Returns True: decimal values have a scale.

TEFObjectDataType class

Stores the address of an object. This is only used for in-memory transfers, it is not persistable.

function GetDefaultDisplayWidth(const ASize: Integer): Integer;

Returns the default display width for an object reference value.

TEFTree class

The root of a tree. Contains a set of nodes which are in turn trees.

TComparer class

TEFPersistentTree class

A tree that stores a file name (or other logical identifier).

procedure AfterLoad;

Called after the tree is loaded from its persistent store; triggers post-load processing.

procedure Assign(const ASource: TEFTree;

Makes this tree a copy of ASource, also copying the persistent name.

property PersistentName: string read FPersistentName write FPersistentName;

Logical identifier (usually the file name without path/extension) of the persistent tree.

property IsPersistent: Boolean read GetIsPersistent;

Returns True if the tree has a persistent name.

property PersistentFileName: string read GetPersistentFileName;

Returns the full path name of the persistent file.

TEFNode class

A node in a tree. Has a name and a value, and can have subnodes.

function GetEnumerator: TEnumerator<TEFNode>;

Returns an enumerator over the node's direct children (enables for-in loops).

function GetEmptyAsNull: Boolean;

Returns whether an empty value should be treated as null, per the node's data type.

function GetRoot: TEFTree;

Returns the root of the tree, walking up through the parent nodes.

function FindNode(const APath: string;

Finds a node by path relative to this node; an empty path returns the node itself.

procedure Assign(const ASource: TEFTree;

Copies everything from ASource, overwriting any existing data. if ASource is a node, name and value are copied as well.

procedure AssignValue(const ASource: TEFNode);

Copies the value (and datatype) from the specified node. The name is unchanged.

property Parent: TEFTree read FParent;

A reference to the parent node, if any.

property Index: Integer read GetIndex;

Index of the node in the parent's list of node.

-1 if the node has no parent.

constructor Create(const AName: string;

Creates a node with specified name and value.

constructor Create(const AName: string);

Creates a node with specified name and no value.

constructor Create;

Creates a node with no name and no value.

constructor Clone(const ASource: TEFTree;

Creates a new node and assigns the specified node to it.

procedure Clear;

Deletes all subnodes, recursively.

procedure Delete;

Removes itself from its parent. This causes the parent to free the current object.

property Name: string read GetName write SetName;

Identifies the node among its siblings. Should be unique inside the parent.

procedure Rename(const ANewName: string);

Renames the node. Normally shouldn't be used.

property DataType: TEFDataType read GetDataType write SetDataType;

A reference to the node's data type. Should be an object managed by the data type factory.

function LockDataType: Integer;

Increments and returns the DataType lock count. When the number is > 0, assigning a value through the As... properties will not change the datatype (unless it's unknown). This also applies to any other operation that implicitly changes the DataType. Explicitly setting DataType is still allowed even when locked.

function UnlockDataType: Integer;

Decrements and returns the DataType lock count. This call does not guarantee that the DataType will be unlocked. It will only when the returned value is zero, which happens when calls to LockDataType and UnlockDataType are balanced. LockDataType

property Value: Variant read GetValue write SetValue;

Plain value of the node.

property ValueAttributes: string read FValueAttributes write FValueAttributes;

Used for I/O.

property IsMultiLineValue: Boolean read GetIsMultiLineValue;

True if the value spans multiple lines or is flagged as folded ('>') in its value attributes.

property IsMultiLineWithNLValue: Boolean read GetIsMultiLineWithNLValue;

True if the value contains explicit line breaks or is flagged as literal ('|') in its value attributes.

property AsString: string read GetAsString write SetAsString;

Node value as a string.

property AsChar: Char read GetAsChar write SetAsChar;

Node value as a string.

property AsStringArray: TStringDynArray read GetAsStringArray write SetAsStringArray;

Node value as a string array.

property AsPair: TEFPair read GetAsPair write SetAsPair;

Node value as a pair.

property AsExpandedPair: TEFPair read GetAsExpandedPair;

Node value as a pair with expanded macros in the value part.

property AsPairs: TEFPairs read GetAsPairs write SetAsPairs;

Node value as a list of pairs.

property AsExpandedString: string read GetAsExpandedString;

Node value as an expanded string.

property AsInteger: Integer read GetAsInteger write SetAsInteger;

Node value as an Integer.

property AsObject: TObject read GetAsObject write SetAsObject;

Node value as an object.

property AsBoolean: Boolean read GetAsBoolean write SetAsBoolean;

Node value as a Boolean.

property AsDate: TDate read GetAsDate write SetAsDate;

Node value as a Date.

property AsTime: TTime read GetAsTime write SetAsTime;

Node value as a Time.

property AsDateTime: TDateTime read GetAsDateTime write SetAsDateTime;

Node value as a DateTime.

property AsCurrency: Currency read GetAsCurrency write SetAsCurrency;

Node value as a Currency.

property AsFloat: Double read GetAsFloat write SetAsFloat;

Node value as a Double floating point value.

property AsDecimal: TBcd read GetAsDecimal write SetAsDecimal;

Node value as a decimal (BCD) value.

property AsBytes: TBytes read GetAsBytes write SetAsBytes;

Node value as a byte array.

procedure LoadBytesFromStream(const AStream: TStream);

Loads the whole content of AStream into the node's value as a byte array.

function SetAsYamlValue(const AValue: string;

Parses AValue trying to guess its data type and sets Value and DataType accordingly.

Parameters:

• AValue — Value to parse, usually read from a Yaml stream.
• AFormatSettings — Format settings to use to parse the value. You can use Session.UserFormatSettings, or Session.JSFormatSettings, or custom settings.

Returns: Returns Self to allow for fluent calls.

function SetAsJSONValue(const AValue: string;

Parses AValue according to DataType and sets its own value to the parsed value.

Parameters:

• AValue — Value to parse, usually got from a web request.
• AUseJSDateFormat — Set to True if date/times are specified in JS long format.
• AFormatSettings — Format settings to use to parse the value. You can use Session.UserFormatSettings, or Session.JSFormatSettings, or custom settings.

Returns: Returns Self to allow for fluent calls.

property IsNull: Boolean read GetIsNull;

True if the node is null. Null is meant as absence of a value. Nodes are made null by calling their SetToNull method.

procedure SetToNull(const AForceChangeNotification: Boolean = False);

Sets the node to null, effectively clearing the value.

Children are unaffected.

function EqualsNode(const ANode: TEFNode): Boolean;

Returns true if the current node has the same name and value as the specified node, or if both are null.

Children are not considered.

function EqualsValue(const AValue: Variant): Boolean;

Returns True if the current node has specified value or if both the node and the value are null.

Children are not considered.

function GetChildStrings(const ASeparator: string = sLineBreak;

Returns all child nodes as a string of name<AConnector>value pairs separated by ASeparator.

function GetChildStrings(const AStrings: TStrings): Integer;

Adds to the specified string list all child nodes as strings in the form Name=Value. Returns the number of added items. All existing contents in AStrings are deleted.

function GetChildValues(const AStrings: TStrings): Integer;

Adds to the specified string list all child node values. Returns the number of added items. All existing contents in AStrings are deleted.

function GetChildNames(const AStrings: TStrings): Integer;

Adds to the specified string list all child node names. Returns the number of added items. All existing contents in AStrings are deleted.

procedure SetChildStrings(const AStrings: TStrings);

Deletes all children and adds a new children for each string in the specified string list. Strings must be in the form Name=Value. All existing contents in AStrings are deleted.

function GetExpandedChildStrings(const ASeparator, AConnector, ADefaultValue: string): string;

Returns all child nodes as a string of name<AConnector>value pairs separated by ASeparator. Values are expanded.

function GetChildPairs(const AExpandMacrosInValues: Boolean = False): TEFPairs;

Returns all child nodes as name/value pairs.

function GetChildNames: TStringDynArray;

Returns an array of names of all direct children of the node.

function ToArray: TArray<TEFNode>;

Returns an array of references to all direct children of the node.

procedure AssignFieldValue(const AField: TField);

Assigns a field's value to the node. May also change or set the node's datatype.

procedure AssignValueToField(const AField: TField);

Assigns the node's value to the specified field.

procedure AssignValueToParam(const AParam: TParam);

Assigns the node's value to the specified param. May also set the param's data type.

procedure AssignToParam(const AParam: TParam);

Assigns the node's name and value to the specified param. May also set the param's data type.

function GetPath: string;

Returns the node's slash-separated path, up to the root.

TEFTreeFactory class

Creates trees of specified types from files.

class function LoadFromFile<T: TEFTree, constructor>(const AFileName: string): T;

Loads the specified yaml file and builds a tree of the specified type with all data in it.

class procedure ReloadFromFile(const ATree: TEFTree;

Reloads the specified yaml file into an existing tree, overwriting any data in it.

TEFTreeMacroExpander class

A macro expander that expands all the strings contained in a TEFTree object. Each macro in this format:

%<NameSpace>:<Path>%

is expanded to the string value of the tree node located by the path. This macro expander holds a reference to a TEFTree. <NameSpace> is a value set upon creation. If it is empty, then no ':' separator is required in the macros.

The need for a name space stems from the fact that you can have multiple macro expanders of this kind active at the same time, each linked to a differentàtree object, and use the namespace string to differentiate them.

This macro expander is not registered by default, as it needs a reference to an external object to work. So, applications will create and use this class autonomously (by querying it directly or adding it to an expansion engine, without registering it) as required.

constructor Create(const ATree: TEFTree;

Creates the expander bound to ATree, using ANameSpace as the macro name space prefix.

TEFDataTypeRegistry class

Keeps track of all registered data types.

function GetClass(const AId: string): TEFDataTypeClass;

Returns the registered data type class with the given Id.

property Classes;

The registered classes, so the factory can instantiate them all up front and keep its dictionary read-only while requests are served.

TEFDataTypeFactory class

Holds a list of registered data types and manages their lifetimes.

procedure PreloadRegisteredTypes;

Instantiates every registered data type, so that the dictionary is complete before any request is served and GetDataType becomes a plain read. Called once at unit initialization: this is a singleton shared by every thread, on a path taken by each and every value assignment, so filling it lazily meant two concurrent first uses of the same type could both add it (EListError) or read it during a rehash.

class destructor Destroy;

Frees the singleton instance at unit finalization.

procedure AfterConstruction;

Creates the internal dictionary of instantiated data types.

destructor Destroy;

Frees all instantiated data types and the factory.

function GetDataType(const AId: string): TEFDataType;

Returns a reference to the registered data type specified by name.

function GetDataType(const ADataTypeClass: TEFDataTypeClass): TEFDataType;

Returns a reference to the registered data type specified by class.

Routines

constructor Create;

Creates an empty tree.

destructor Destroy;

Destroys the tree and all its nodes.

procedure BeforeSave;

Called before the tree is saved; recursively notifies all children.

function QueryInterface(const IID: TGUID;

IInterface support: queries for a supported interface.

function _AddRef: Integer;

IInterface support: no-op reference count increment (lifetime is not managed by refcounting).

function _Release: Integer;

IInterface support: no-op reference count decrement (lifetime is not managed by refcounting).

constructor Clone(const ASource: TEFTree;

Creates a new tree holding a deep copy of the specified tree.

function GetRoot: TEFTree;

Returns the root of the tree. In this class, returns Self.

procedure Clear;

Clears the tree, recursively deleting all nodes.

procedure Assign(const ASource: TEFTree;

Makes the current object a copy of the specified tree.

procedure Merge(const ASource: TEFTree);

Adds all nodes in ASource, overwriting any existing nodes with the same name. Note: does not copy annotations.

function AddChild(const ANode: TEFNode): TEFNode;

Adds a child node. Returns a reference to the added object.

function AddChild(const AName: string;

Creates a child node of a type that may depend on the parameters, fills and adds it. Then returns a reference to the added object.

function AddChild(const AName: string): TEFNode;

Creates a child node of a type that may depend on the parameters, sets the name and adds it. Then returns a reference to the added object.

function FindChild(const AName: string;

Finds a child node by name. Returns nil if not found.

Parameters:

• AName — Name of the child node to look for.
• ACreateMissingNode — Creates the node if not found.
• ARecursively — If true, searches also in child nodes recursively

function FindChildByNameAndValue(const AName: string;

Finds a child node with specified name and value and returns a reference to it, or nil if the node is not found.

Parameters:

• AName — Name of the child node to look for.
• AValue — Value of the child node to look for.
• ARecursively — If true, searches also in child nodes recursively

function FindChildByValue(const AValue: Variant;

Finds a child node with specified value and returns a reference to it, or nil if the node is not found.

Parameters:

• AValue — Value of the child node to look for.
• ARecursively — If true, searches also in child nodes recursively

function HasChild(const AName: string;

Returns True if a child with the given name exists, and False otherwise.

function HasChild(const AChild: TEFNode;

Returns True if the specified child exists, and False otherwise.

function FindChildByPredicate(const APredicate: TNodePredicate;

Finds a child node by predicate. The predicate function is called for each child and should return True if a child qualifies. The method returns the first qualifying child (and stops as soon as it is found). If no qualifying child is found, the method return nil.

Parameters:

• APredicate — Function for testing purpose
• ARecursively — If true, searches also in child nodes recursively

procedure EnumChildren(const AProc: TNodeProc;

Calls APredicate for each direct child node. If APredicate returns True, calls AProc passing the qualifying child node.

function ChildByName(const AName: string): TEFNode;

Finds a child node by name. Raises an exception if not found.

procedure RemoveChild(const ANode: TEFNode);

Removes the child from the list of children, if present.

procedure ClearChildren;

Removes all children, recursively.

function GetChildCount<T: class>: Integer;

Returns the count of direct children of a specified type.

function GetChild<T: class>(const AIndex: Integer): T;

Indexed access to a list of children limited to the set of children that are of the specified type.

function GetChildIndex<T: class>(const AChild: T): Integer;

Returns the index of a given child node in a list of children limited to the set of children that are of the specified type, or -1 if the specified children is not a direct child of the current tree.

function FindNode(const APath: string;

Searches a node by a path. Separate hierarchy elements with a /.

Parameters:

• APath — A string path. Example: Node/SubNode.
• ACreateMissingNodes — If True, creates any missing nodes throughout the path and the final node as well. This guarantees that the result is not nil.

Returns: The found node, or nil.

function FindNode(const APaths: TStringDynArray): TEFNode;

Searches a node by trying a sequence of paths in given order.

Parameters:

• APaths — A sequence of string paths to try. Example: ['Node/SubNode', 'Node/SubNode2'].

Returns: The first node found, or nil.

function GetNode(const APath: string;

Works like FindNode, but raises an exception if ACreateMissingNodes is False and the wanted node does not exist.

Parameters:

• ACreateMissingNodes — If True, creates any missing nodes throughout the path and the final node as well. This guarantees that the result is not nil.

Returns: The found node.

procedure DeleteNode(const APath: string);

Finds a node by path and, if found, deletes it.

function GetValue(const APath: string;

Finds a node by path and, if found, returns its value, otherwise returns ADefaultValue.

function GetValue(const APath: string): Variant;

Finds a node by path and, if found, returns its value, otherwise returns Null.

function GetBoolean(const APath: string;

Finds a node by path and, if found, returns its value as a Boolean, otherwise returns ADefaultValue.

function GetFloat(const APath: string;

Finds a node by path and, if found, returns its value as a Double, otherwise returns ADefaultValue.

function GetInteger(const APath: string;

Finds a node by path and, if found, returns its value as an Integer, otherwise returns ADefaultValue.

function GetString(const APath: string;

Finds a node by path and, if found, returns its value as a string, otherwise returns ADefaultValue.

function GetChar(const APath: string;

Finds a node by path and, if found, returns its value as a char, otherwise returns ADefaultValue.

function GetDate(const APath: string;

Finds a node by path and, if found, returns its value as a Date, otherwise returns ADefaultValue.

function GetExpandedString(const APath: string;

Finds a node by path and, if found, returns its value as an expanded string, otherwise returns ADefaultValue.

<returns> The found node's string with any macros expanded. <returns>

If the node is not found, macros in ADefaultValues are expanded as well before returning it. This method guarantees that the return value has all known macros expanded anyway.

function GetStringArray(const APath: string;

Finds a node by path and, if found, returns its value as a string array, otherwise returns ADefaultValue.

function GetPairs(const APath: string;

Finds a node by path and, if found, returns its value as a list of pairs, otherwise returns ADefaultValue.

function GetChildrenAsStrings(const APath: string;

Returns a separated list of all children of the specified node in the form Name<AConnector>AsString.

Parameters:

• APath — Locates the parent node of the strings to extract.
• ASeparator — Separator for name/value pairs (ex. '=').
• AConnector — String used to connect pairs (ex. sLineBreak).
• ADefaultValue — Value to return when the node does not exist.

Returns: A concatenation of all children of the specified node built according to the arguments.

function GetChildrenAsStrings(const APath: string;

Returns a list of all children of the specified node in the form Name=AsString.

Parameters:

• APath — Locates the parent node of the strings to extract.
• AStrings — Object to which strings are to be added. Any exiting contents are deleted.

Returns: The number of appended items.

procedure SetChildrenAsStrings(const APath: string;

Deletes all children nodes and replaces them with one node for each item in the specified string list. Strings must be in the form Name=Value.

function GetChildrenAsPairs(const APath: string;

Returns an array of all children of the specified node, which must be in name=value format, as pairs.

Parameters:

• APath — Locates the parent node of the strings to extract.

Returns: Array of name/value pairs.

function GetChildrenAsExpandedStrings(const APath: string;

Same as GetChildrenAsStrings, but returns expanded strings: Each string is passed to the macro expander before concatenation.

function GetObject(const APath: string;

Finds a node by path and, if found, returns its value as an object, otherwise returns ADefaultValue.

function GetObject<T: class>(const APath: string): T;

Finds a node by path and returns its object value cast to T, or nil if not found.

procedure SetInteger(const APath: string;

Sets a node value by path. The node is created if it doesn't exist yet.

function SetString(const APath: string;

Sets a node value by path. The node is created if it doesn't exist yet.

function SetFloat(const APath: string;

Sets a node value by path. The node is created if it doesn't exist yet.

function SetValue(const APath: string;

Sets a node value by path. The node is created if it doesn't exist yet.

procedure SetObject(const APath: string;

Sets a node value by path. The node is created if it doesn't exist yet.

procedure SetBoolean(const APath: string;

Sets a node value by path. The node is created if it doesn't exist yet.

procedure SetDateTime(const APath: string;

Sets a node value by path. The node is created if it doesn't exist yet.

procedure AddFieldsAsChildren(const AFields: TFields);

Creates a children for each field in AField and sets its value to the field's value. Node names are field names. Existing nodes are overwritten.

function AddAnnotation(const AAnnotation: string): Integer;

Adds an annotation string and returns its index.

procedure AssignAnnotations(const AStrings: TStrings);

Replaces the tree's annotations with the contents of AStrings.

function GetPath: string;

Returns a string-based path. Returns '' in the tree, and a slash-separated path in the nodes.

procedure Sort(const ACompareFunc: TEFNodeCompareFunc);

Sorts the direct child nodes using the given comparison function.

procedure SetPropertyFromNode(const AInstance: TObject;

Looks for the node specified by APath and, if found, sets the same-named property of AInstance to the node's value. If APath is a compound path (such as Path/To/Property) then only the last part is used. If ApathIsName is True, then the path is assumed not to be compound and the code is more efficient.

procedure SetPropertiesFromNode(const AInstance: TObject;

Same as SetPropertyFromNode but for an array of nodes/properties.

procedure SetPropertiesFromChildNodes(const AInstance: TObject);

Calls SetPropertyFromNode for all direct children. If any children don't have corresponding properties, then an exception is raised.

procedure CopyChildValues(const ASource: TEFTree;

Tries to read from ASource a value for each child node, interpreting it according to the child node's DataType. Read values are stored in the child nodes.

Parameters:

• ASource — Source data. Only top-level nodes are copied. Each node may contain a single value. If AValueIndex is >= 0, each node may contain one or more comma-separated string values, of which only the one with index AValueIndex is read.
• AUseJSDateFormat — True if any dates in source strings are in JS format; False for system format.
• AFormatSettings — Custom format settings to decode values.
• ATranslator — Pass a translation function if key names in ASource do not match wanted child node names and you need to translate them. The function receives the child name and should return the corresponding source name.