ConfigScript

Description

sealed class Tinman.Core.Config.ConfigScript

Derived from

ConfigNode abstract

Represents a configuration script.

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' ;

Public / Constructors

From

2 overloads


public static method From1 → (3)

sourceCode in : ICodeInput

[not-null]
The script source code.

current opt : Path = null

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 opt : ConfigDomain = null

The domain of the config script or null.

returns → ConfigScript

The resulting ConfigScript object.

Parses the given configuration script.

The config domain opt that is passed to this method will be used to resolve references to other config scripts. The returned config script will not be added to the given domain opt by this method (see ConfigDomain.Add).

ValidatingException

If one or more parsing errors have occurred.


public static method From2 → (3)

sourceCode in : string

[not-null]
The script source code.

current opt : Path = null

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 opt : ConfigDomain = null

The domain of the config script or null.

returns → ConfigScript

The resulting ConfigScript object.

Parses the given configuration script.

The config domain opt that is passed to this method will be used to resolve references to other config scripts. The returned config script will not be added to the given domain opt by this method (see ConfigDomain.Add).

ValidatingException

If one or more parsing errors have occurred.

Load


public static method Load → (2)

path in : Path

[not-null]
The file path.

domain opt : ConfigDomain = null

The domain of the config script or null.

returns → ConfigScript

The loaded config script.

Loads a config script from a file.

The config domain opt that is passed to this method will be used to resolve references to other config scripts. The returned config script will not be added to the given domain opt by this method (see ConfigDomain.Add).

IOException

If an I/O error has occurred.

ValidatingException

If one or more parsing errors have occurred.

Tinman


public static method Tinman → ()

returns → ConfigScript

The created ConfigScript.

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

Public / Methods

Call​Function


public method CallFunction → (3)

name in : string

[not-null]
The script function name.

arguments opt : ConfigValue [ ] = null

The function arguments.

intern opt : bool = false

Also include internal members (see ConfigMember.IsIntern)?

returns → ConfigValue

The config value.

Calls a public script function.

ConfigException

If an unexpected error has occurred while obtaining the config value, for example while evaluating default argument expressions for the function call.

Depends​On


public method DependsOn → (1)

other in : ConfigScript

[not-null]
The other script.

returns → bool

true if this script depends on other in, false if not.

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

Evaluate


public method Evaluate → (1)

expression in : string

[not-null]
The expression to evaluate.

returns → ConfigValue

The evaluated config value.

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

ValidatingException

If the given expression in source code is malformed.

ConfigException

If an error has occurred while evaluating the expression (e.g. identifier not found).

Get​Members


public method GetMembers → (1)

intern opt : bool = false

Also include internal members (see ConfigMember.IsIntern)?

returns → IVectorConst<ConfigMember>

The list of script members.

Returns the script members.

Has​Member


[Pure]
public method HasMember → (2)

name in : string

[not-empty]
The member name.

intern opt : bool = false

Also include internal members (see ConfigMember.IsIntern)?

returns → bool

true if the member exists, false if not.

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

Implement​Function


public method ImplementFunction → (2)

name in : string

[not-null]
The script function name.

implementation in : ConfigFunctionDelegate

The external implementation or null to clear.

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

ConfigException

If there is no script function of the given name in.
If the script function already has an implementation in the script code.

Make​Identifier


[Pure]
public static method MakeIdentifier → (1)

value in : string

The input string value.

returns → string

A valid config script identifier.

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.

Member


[Pure]
public method Member → (2)

name in : string

[not-empty]
The member name.

intern opt : bool = false

Also include internal members (see ConfigMember.IsIntern)?

returns → ConfigMember

The config member object.

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

ConfigException

If there is no script member of the given name in.

Member​At


[Pure]
public method MemberAt → (1)

offset in : int32

The source code offset.

returns → ConfigMember

The found script member or null.

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

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

Member​Null

2 overloads


[Pure]
public method MemberNull1 → (2)

name in : string

[not-empty]
The member name.

intern opt : bool = false

Also include internal members (see ConfigMember.IsIntern)?

returns → ConfigMember

The config member object or null if not found.

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


[Pure]
public method MemberNull2 → (2)

value in : ConfigValue

The config value object.

intern opt : bool = false

Also include internal members (see ConfigMember.IsIntern)?

returns → ConfigMember

The script variable or null.

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

ConfigException

If an unexpected error has occurred while finding the config value, for example while retrieving a virtual field of a class value.

Save


public method Save → (1)

path in : Path

[not-null]
The file path

Saves this config script to a file.

IOException

If an I/O error has occurred.

Public / Attributes

Domain


public attribute Domain → (get)

value : ConfigDomain

The config project or null.

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

Grammar​Code


public static attribute GrammarCode → (get)

value : string

[not-null]
The grammar source code.

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

Grammar​Rule​Expression


public static attribute GrammarRuleExpression → (get)

value : IGrammarRule

[not-null]
The grammar rule.

Returns the config script grammar rule: expr.

Input


public attribute Input → (get)

value : ICodeInput

The source code or null if this ConfigScript instance has not been created by using From2 or From1.

The config script source code.

Name


public attribute Name → (get)

value : string

The config script name of null if this script has no name.

The fully-qualified name of this config script.

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

Scope


public attribute Scope → (get)

value : IConfigScope

[not-null]
The config scope object.

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

Logging

Logger


public static readonly attribute Logger → (ILogger)

The logger object of this class.