TINMAN 3D / REALTIME TERRAIN
Software Development Kit - User Manual

class ConfigScript in Tinman.Core.Config

Represents a configuration script.

sealed class ConfigScript extends ConfigNode

Remarks

This is the Grammar of a configuration script:

#                      := '//' ~newline* newline | '/*' ~'*/'* '*/' ;
!config                := script? using* member* ;

member                 := function | variable ;
script                 := 'script' qualified-identifier ';' ;
using                  := 'using' qualified-identifier ';' ;

!function              := comment* 'intern'? identifier '(' (function-param .. ',')? ')' type-constraint-value ';' ;
!variable              := comment* 'intern'? identifier type-constraint-value ';' ;

function-param         := comment* identifier type-constraint-value ;

comment                := '`' ' '? ~newline* newline ;
type-constraint-value  := (':' type)? ('{' expr '}')? ('=' expr)? ;

newline                := '\r\n' | [\r\n] ;

!expr                  := expr-each ;
expr-additive          := expr-multiplicative !> (expr-additive-op expr-multiplicative)+ ;
expr-array             := '[' (type ':')? expr-list ','? ']' ;
expr-call              := qualified-identifier '::' <! identifier !> '(' expr-list ')' ;
expr-chain             := '@' type-named ('(' expr-list ')' | '{' expr-init '}') ;
expr-conditional       := expr-conditional-or !> '?' expr ':' expr ;
expr-conditional-and   := expr-logic-or !> ('&&' expr-logic-or)+ ;
expr-conditional-or    := expr-conditional-and !> ('||' expr-conditional-and)+ ;
expr-each              := expr-conditional !> (expr-each-op expr-conditional)+ ;
expr-element           := '[' expr ']' ;
expr-equality          := expr-relational !> (expr-equality-op expr-relational)+ ;
expr-init              := ((identifier '=' expr .. ',') ','?)? ;
expr-list              := (expr .. ',')? ;
expr-logic-and         := expr-equality !> ('&' expr-equality)+ ;
expr-logic-or          := expr-logic-xor !> ('|' expr-logic-xor)+ ;
expr-logic-xor         := expr-logic-and !> ('^' expr-logic-and)+ ;
expr-multiplicative    := expr-power !> (expr-multiplicative-op expr-power)+ ;
expr-object            := type-named? '{' expr-init '}' | '{' (type-named '}' | (type-named ':')? expr-list '}') ;
expr-power             := expr-unary !> (expr-power-op expr-unary)+ ;
expr-primary           := expr-literal | expr-array | expr-object | expr-call | '(' expr ')' | expr-value | expr-environment ;
expr-relational        := expr-shift !> (expr-relational-op expr-shift)+ ;
expr-shift             := expr-additive !> (expr-shift-op expr-additive)+ ;
expr-suffix            := expr-primary !> expr-suffix-op+ ;
expr-suffix-op         := expr-member | expr-element | expr-chain ;
expr-unary             := (expr-literal-primary !> expr-suffix-op+) | (expr-unary-op <! expr-suffix) ;

!type                  := type-simple | type-named !> '[]'+ ;

!type-named            := qualified-identifier \ ('nan' | 'null' | 'true' | 'false') ;

expr-environment       := '$' identifier ;
expr-literal           := expr-literal-hex | expr-literal-decimal | expr-literal-string | expr-literal-bool | expr-literal-null | expr-literal-path ;
expr-member            := '.' identifier | '->' identifier ;
qualified-identifier   := identifier .. '.' ;

expr-literal-decimal   := expr-literal-number ;
expr-literal-hex       := ('0x' | '#') hex-digit+ ;
expr-literal-primary   := 'nan' | '+inf' | '-inf' | '-' expr-literal-number ;
identifier             := identifier-start identifier-char* ;

expr-literal-number    := digit+ ('.' digit+)? (('e' | 'E') ('+' | '-') digit+)? ;
hex-digit              := digit | 'A'..'F' ;
identifier-char        := letter | digit ;
identifier-start       := letter ;

digit                  := '0'..'9' ;
expr-additive-op       := '+' | '-' ;
expr-each-op           := '=>' | '?>' ;
expr-equality-op       := '==' | '!=' ;
expr-literal-bool      := 'true' | 'false' ;
expr-literal-null      := 'null' ;
expr-literal-path      := '<' ]\r>\n[* '>' | '`' ]`\r\n[* '`' ;
expr-literal-string    := '"' (]"\r\n[ | '""')* '"' | '\'' (]\r'\n[ | '\'\'')* '\'' ;
expr-multiplicative-op := '*' | '/' | '%' ;
expr-power-op          := '**' | '\\\\' ;
expr-relational-op     := '<=' | '<' | '>=' | '>' ;
expr-shift-op          := '<<' | '>>' ;
expr-unary-op          := '-' | '+' | '!' | '~' ;
expr-value             := '#' | '@' ;
letter                 := 'a'..'z' | 'A'..'Z' | '_' ;
type-simple            := 'bool' | 'string' | 'path' | 'number' ;

Private / Methods

Begin

[Internal]
public method Begin ()
inherited ConfigNode.Begin

End

[Internal]
public method End ()
inherited ConfigNode.End

Private / Attributes

HasBegun

The balance between calls to Begin and End greater than zero?

[Internal]
public property HasBegun { get }
type bool
value true if the balance is greater than zero,
false if it is not.
inherited ConfigNode.HasBegun

Public / Attributes

Domain

The config domain that shall be used by this config script in order to resolve external names: 'ScriptName::MemberName'.

public property Domain { get }
type ConfigDomain
value The config project or null.

GrammarCode

Returns the source code for config scripts in the grammar language.

public static property GrammarCode { get }
type string
value [not-null] The grammar source code.

GrammarRuleExpression

Returns the config script grammar rule: expr.

public static property GrammarRuleExpression { get }
type IGrammarRule
value [not-null] The grammar rule.

Input

The config script source code.

public property Input { get }
type ICodeInput
value The source code or null if this ConfigScript instance has not been created by using From or From.

Name

The fully-qualified name of this config script.

public property Name { get }
type string
value The config script name of null if this script has no name.

Remarks:

Members of unnamed scripts cannot be accessed from other scripts in a config domain.

Range

Returns source code range of this object.

public property Range { get }
type RangeI
value The source code character range or Inv if none.
inherited ConfigNode.Range

Scope

Returns an IConfigScope object that contains the members of this config script.

public property Scope { get }
type IConfigScope
value [not-null] The config scope object.

Public / Constructors

From

Parses the given configuration script.

public static method From (ICodeInput sourceCode, Path current = null, ConfigDomain domain = null)
type ConfigScript
params sourceCode [not-null] The script source code.
  current Optional directory to use for resolving relative path values that start with a '.' (e.g. <./a/b.txt>). All other relative paths (e.g. <a/b.txt>) will remain unchanged. If null, the current filesystem directory will be used. Defaults to null.
  domain The domain of the config script or null. Defaults to null.
returns [not-null] The resulting ConfigScript object.

Exceptions:


Parses the given configuration script.

public static method From (string sourceCode, Path current = null, ConfigDomain domain = null)
type ConfigScript
params sourceCode [not-null] The script source code.
  current Optional directory to use for resolving relative path values that start with a '.' (e.g. <./a/b.txt>). All other relative paths (e.g. <a/b.txt>) will remain unchanged. If null, the current filesystem directory will be used. Defaults to null.
  domain The domain of the config script or null. Defaults to null.
returns [not-null] The resulting ConfigScript object.

Exceptions:

Load

Loads a config script from a file.

public static method Load (Path path, ConfigDomain domain = null)
type ConfigScript
params path [not-null] The file path.
  domain The domain of the config script or null. Defaults to null.
returns [not-null] The loaded config script.

Exceptions:

Tinman

Creates the built-in config script 'Tinman' that provides some common utility functions.

public static method Tinman ()
type ConfigScript
returns [not-null] The created ConfigScript.

Public / Methods

CallFunction

Calls a public script function.

public method CallFunction (string name, ConfigValue[] arguments = null, bool intern = false)
type ConfigValue
params name [not-null] The script function name.
  arguments The function arguments. Defaults to null.
  intern Also include internal members (see IsIntern)? Defaults to false.
returns [not-null] The config value.

Exceptions:

ClearRange

Clears the source code range.

public method ClearRange ()
inherited ConfigNode.ClearRange

See also:

ConfigNode.Range

DependsOn

Does this config script depend on the given one by referring to one of its members using an external name 'ScriptName::MemberName'?

public method DependsOn (ConfigScript other)
type bool
params other [not-null] The other script.
returns true if this script depends on other, false if not.

Evaluate

Evaluates the given expression within the scope of this config script.

public method Evaluate (string expression)
type ConfigValue
params expression [not-null] The expression to evaluate.
returns [not-null] The evaluated config value.

Exceptions:

FindAt

Finds all config nodes which code range (see Range) contains the given range (see Contains).

public override method FindAt (RangeI range, ICollector<ConfigNode> nodes)
params range The code range to intersect with.
  nodes [not-null] The output nodes.
overrides ConfigNode.FindAt

GetMembers

Returns the script members.

public method GetMembers (bool intern = false)
type IVectorConst<ConfigMember>
params intern Also include internal members (see IsIntern)? Defaults to false.
returns [>=0] The list of script members.

HasMember

Checks if a public script member (i.e. function or variable) of the given name exists.

[Pure]
public method HasMember (string name, bool intern = false)
type bool
params name [not-empty] The member name.
  intern Also include internal members (see IsIntern)? Defaults to false.
returns true if the member exists, false if not.

ImplementFunction

Provides an external implementation for a script function, replacing the current external implementation, if existent.

public method ImplementFunction (string name, ConfigFunctionDelegate implementation)
params name [not-null] The script function name.
  implementation The external implementation or null to clear.

Exceptions:

MakeIdentifier

Generates a valid config script identifier (see grammar rule identifier) from the given string value by replacing all sequences of invalid characters with a single underscore ('_') character.

[Pure]
public static method MakeIdentifier (string value)
type string
params value The input string value.
returns [not-empty] A valid config script identifier.

Member

Returns a public script member (i.e. function or variable) by its name.

[Pure]
public method Member (string name, bool intern = false)
type ConfigMember
params name [not-empty] The member name.
  intern Also include internal members (see IsIntern)? Defaults to false.
returns [not-null] The config member object.

Exceptions:

MemberAt

Returns the script member at the given source code offset (see Range).

[Pure]
public method MemberAt (int32 offset)
type ConfigMember
params offset The source code offset.
returns The found script member or null.

Remarks:

If no member contains the given offset, the next member is returned (if existent).

MemberNull

Returns a public script member (i.e. function or variable) by its name.

[Pure]
public method MemberNull (string name, bool intern = false)
type ConfigMember
params name [not-empty] The member name.
  intern Also include internal members (see IsIntern)? Defaults to false.
returns The config member object or null if not found.

Returns the public script variable which current value is stored in the given config value.

[Pure]
public method MemberNull (ConfigValue value, bool intern = false)
type ConfigMember
params value The config value object.
  intern Also include internal members (see IsIntern)? Defaults to false.
returns The script variable or null.

See also:

ConfigMember.CallFunction
ConfigMember.Variable

Exceptions:

Resolve

Resolves all references in this PSI node.

public override method Resolve ()
type ResolveResult
returns The result of the resolver cycle.
implements ConfigNode.Resolve

Save

Saves this config script to a file.

public method Save (Path path)
params path [not-null] The file path

Exceptions:

SetParseInfo

Provides additional information about the parsing process.

public method SetParseInfo (RangeI range)
params range The source code range.
inherited ConfigNode.SetParseInfo

ToString

[Pure]
public override method ToString ()
type string
inherited ConfigNode.ToString

Validate

Validates the state of this object.

public override method Validate (Validator validator)
params validator [not-null] The validator object.
implements ConfigNode.Validate

WriteSourceCode

Produces source code by feeding the given source code writer.

public override method WriteSourceCode (SourceCodeWriter writer, Context context)
params writer [not-null] The source code writer to use.
  context [not-null] Context information.
implements ConfigNode.WriteSourceCode

Exceptions:

Logging

Logger

The logger object of this class.

public static readonly field Logger
type ILogger