Overview

ShockScript is a strongly typed, multi-paradigm scripting language.

Note: The document is a work in progress, and may lack content.

eXtensible Markup Language

ShockScript incorporates eXtensible Markup Language (XML) expressions suitable for implementing User Interfaces (UI), and also includes capabilities for users interested on XML data processing.

For the Whack Engine, XML expressions create WhackDS nodes by default.

Events

ShockScript incorporates a basic event model and allows easily declaring event types and documenting them. Implementations may extend the event model for working with a Document Object Model.

ShockDoc comments

ShockScript supports documentation comments allowing for Markdown notation, special tags such as @throws and media inclusion.

Embed

The Embed() expression may be used for embedding files and media into the program. Its default behavior is to return a data: (for small files) or external URL (for large files).

Embed("thumb.webp")

Note: When returning an external URL, implementations such as Whack Engine use the app:// scheme to fetch a file in the application's installation directory.

Note: Implementations may support an artifact path interpolation, as in:
Embed("{target}/auto.generated")
That is useful when a build script is involved that generates files at the artifact path.

Including statically

The user may embed files statically as either an UTF-8 encoded string, or ByteArray, rather than obtaining an URL.

Embed("data.txt", "text/plain")
Embed("data.bin", "application/octet-stream")

Versus

This section compares ShockScript to other technologies and languages.

React.js

ShockScript incorporates XML capabilities, and XML expressions allow for implementations to produce anything desired, similiar to JSX. There are certain differences to JSX or React.js.

The following demonstrates a basic XML expression for WhackDS:

<w:HGroup>
    <w:Button click&={trace("clicked!")}>button 1</w:Button>
</w:HGroup>

In ShockScript, event handlers are expressed as e&={statementList} (note the ampersand &) as a shorthand to e={function(event){statementList}}. Furthermore, event handlers are conventionally expressed without an on prefix (for instance, click instead of onClick), and they are documented with the @eventparam tag.

Prefixes

ShockScript allows for <q:N>, whose name resolution equals q::N. Dots may be used for entities other than namespaces, as in:

<com.business.components.AppBar/>

For brevity, you do either:

import bc = com.business.components.*;

<bc:AppBar/>

or:

import com.business.components.*

<AppBar/>

Interpolation

Interpolation works similiarly to React.js, except for HTML.

<w:VGroup>
    {undefined}
    {null}
    {node}
    {nodeList}
    {plainText}
    {number}
</w:VGroup>

Interpolating attributes uses { object } and not { ...object } and must appear at most once at the end of all attributes:

<w:Button {arguments}>click me</w:Button>

States

Unlike React.js, in WhackDS there is no risk of accessing an outdated state's value, due to how states are constructed.

package com.business.components {
    //
    public function HelloWorld():whack.ds.Node {
        // x
        [State]
        var x:Number = 0;

        // layout
        return (
            <w:VGroup>
                <w:Label>clicked {x} times</w:Label>
                <w:Button click&={x++}>click me</w:Button>
            </w:VGroup>
        );
    }
}

The state's initializer represents the state's initial value.

Like React.js, there is no transitive detection of mutation methods; therefore, the following is necessary over an array .push(v):

x = [...x, v];

As to Map objects:

m = { ...m, k: v };

Bindables

In WhackDS the concept of "refs" is called bindables.

package com.business.components {
    //
    public function HelloWorld():whack.ds.Node {
        [Bindable]
        var button:Button?;

        //
        whack.ds.useEffect(function() {
            trace(button!);
        }, []);

        return (
            <w:Button bind={button}>click me</w:Button>
        );
    }
}

Contexts

Context usage is represented as whack.ds.ContextValue.<T> objects, although they are used as natural Context-annotated locals.

function ExampleComponent():whack.ds.Node {
    //
    [Context("ExampleContext")]
    const example;

    return (
        <></>
    );
}

Effects

The popular "useEffect" hook requires the second argument, preventing mistakes. For listening to any changes, use "*".

whack.ds.useEffect(function() {
    //
    return function() {
        // cleanup
    };
}, [dep1, ...depN]);

whack.ds.useEffect(function() {
    //
}, "*");

Styling

Unlike with React.js, there is built-in support for linking style sheets in a WhackDS component.

<w:Group>
    <w:Style>
        <![CDATA[
            :host {
                background: red;
            }
        ]]>
    </w:Style>
</w:Group>

MXML

The MXML language, as part of the Apache Flex framework, was used for describing UI components in an intuitive way. ShockScript uses XML expressions semantically similiar to the React.js + JSX technologies, but designed to feel close to MXML in readability.

The following demonstrates a basic UI component implemented in WhackDS:

package com.business.components {
    //
    public function AppBar():whack.ds.Node {
        return (
            <w:HGroup>
                <w:Button click&={trace("clicked!")}>button 1</w:Button>
            </w:HGroup>
        );
    }
}

Event handlers

In MXML, event handlers were expressed as e="statements". In ShockScript, they are expressed as e&={statements} (note the ampersand &) as a shorthand to e={function(event){statements}}.

Note: Although not demanded as such, as opposed to React.js + DOM, event handlers are conventionally expressed without a on prefix, such as click&={trace("clicked!")} rather than React.js onClick={e=>{console.log("clicked!")}}. Event parameters are conventionally given the @eventparam tag in the ShockDoc comments. Classes continue using the Event meta-data, though without needing the @eventType tag.

Rendering components

The Whack Engine's WhackDS feature allows programmers to implement UI components as functions that wrap around the built-in class-based components of Whack Engine. The component is rendered by evaluating the function initially and whenever a state changes.

Effects

The whack.ds.useEffect hook may be used to detect state, parameter or derived changes as well as the component mount and unmount phases.

whack.ds.useEffect(function() {
    // cleanup
    return function() {
        //
    };
}, [dep1, ...depN]);

whack.ds.useEffect(function() {
    //
}, "*");

When the dependencies list is empty ([]), the hook is equivalent to a component mount/unmount event, with the unmount phase handled through the returned function.

whack.ds.useEffect(function() {
    // did mount
    return function() {
        // unmount
    };
}, []);

States

In the top-level of a component, declare states using the State meta-data:

[State]
var counter:uint = 0;

The initial value of counter is zero, although that initializer evaluates only the first time the component renders.

Overwriting a state with a different value (as by an .equals() comparison) will re-render the component.

Note that, like with React.js, arrays and structures as states will not trigger a re-render on operations like .push(); instead the programmer needs to reconstruct the array or structure, like in:

list = [...list, v];

Bindables

In the top-level of a WhackDS component, declare bindables by using the Bindable meta-data. Bindables have certain use-cases, such as persisting a value across renders, and extracting class-based components from certain tags (in which case the bind attribute is used).

[Bindable]
var button:Button? = null;

return (
    <w:Button bind={button}>click me</w:Button>
);

Contexts

In the top-level of a component, reflect inherited contexts by using the Context meta-data.

[Context("ThemeContext")]
const theme;

Capture safety

Unlike in React.js combined with TypeScript, states, bindables ("refs") and context values are captured by reference from nested functions, guaranting the "outdated" value of, say, a state, is never captured, which facilitates development by requiring no additional bindable declaration.

Styling

Unlike with React.js, there is built-in support for linking style sheets in a WhackDS component.

<w:Group>
    <w:Style>
        <![CDATA[
            :host {
                background: red;
            }
        ]]>
    </w:Style>
</w:Group>

ActionScript 3

ShockScript looks like ActionScript 3. This section describes several details that changed on the language.

String type

The String type stores an UTF-8 encoded text, not an UTF-16 encoded text.

"\u{10ffff}".length    // utf-8 length
"\u{10ffff}".charAt(0) // code point at byte 0

for each (var ch in "shockscript".chars()) {
    // ch:uint
}

"shockscript".chars().length() // code point length

Include directive

The include directive is not included in ShockScript.

Default XML namespace

The default xml namespace = E4X statement is not included in ShockScript due to WebAssembly limitations.

Dynamic

The Object type is not dynamic per se, nor does it contain undefined, nor are there dynamic classes, nor are there legacy ECMAScript prototype objects. Only the * type is dynamic and contains undefined.

Matching: The str.match resulting object is slightly different, but still supports indexing.

Obtaining constructor: o.Reflect::class()

Nullability

Types except * are non-nullable by default. Use T? or ?T as a shorthand to (null, T), and T! as a way to exclude undefined and/or null.

Overriding methods

Instance methods may override another method and include additional optional parameters (including the rest parameter).
Instance methods may override another method and return a more contravariant result type.

class A {
    function m() {}
}
class B extends A {
    override function m(...rest:[float]) {}
}

“in” operator

The in operator behaves differently. It triggers shock_proxy::has() which is in general used for determining whether a collection contains a specific value; for Maps it determines whether a pair key exists; for XML and XMLList objects it performs the same E4X behavior.

trace(e in arr);
trace(k in m);

Filter operator

The filter operator has been modified to use a * identifier rather than cluttering the lexical scope with dynamic names.

xnode.(*.@x.startsWith("abc"))

With statement

The with statement is modified to use the * identifier to avoid cluttering the lexical scope.

with (o) {
    *.x =
    *.y = 10;
}

“this” capture

The this object is always captured from the parent activation in nested activations; there is no way to override the this object with another value.

class A {
    function m() {
        function n() {
            // this:A
        }
    }
}

E4X

XML expressions do not produce XML or XMLList unless the inference type is one of these; they are implementation-defined by default. Such expressions have also undergone incremental syntax additions:

<t a/> equals <t a={true}/>
<t e&={}/> equals <t e={function(event){}}/> or <t e={function(){}}/>

<w:VGroup>
    <w:Label variant="heading">Welcome</w:Label>
    <w:Button click&={trace("clicked me");}>Click me</w:Button>
</w:VGroup>

Note: XML(<tag/>) equals var _loc_0:XML = <tag/>;.

Events

Events are declared without defining related static constants, as ShockScript performs vast type inference; thus, the ASDoc @eventType tag does not exist in ShockScript.

/** Some event */
[Event(name="act", type="Event")]
/** Some class */
class A extends EventTarget {}

Note: The @eventparam tag introduced in ShockScript is used for documenting events better in reactive systems that use record types rather than classes for component parameters.

Embedding

Embedding files is much easier in ShockScript. The following returns typically an app:// URI for a file that will be automatically added to the application's installation directory.

trace(Embed("flower.webp"));

Note: Implementations may support interpolating an artifact directory at the Embed path, such as {target}.
trace(Embed("{target}/auto.generated.bin"));
This is useful for when a build script generates a file at an artifact directory.

For static embedding, use a second option as either "text/plain" or "application/octet-stream".

Embed("data.txt", "text/plain")               // :String
Embed("data.bin", "application/octet-stream") // :ByteArray

Variable shadowing

In ShockScript the following is valid in an activation:

var m:* = complexCentral.manager;
// more code...
var m = Manager(m);

Switch fallthroughs

The switch statement does not support fallthroughs, which helps preventing logical bugs by not requiring the break statement.

switch (v) {
    case 0:
        trace("zero");
    case 1:
        trace("one");
    default:
        trace("rest");
}

Switch type

The switch type statement allows for simple type matching:

switch type (v) {
    case (d : Date) {
        //
    }
    default {
        //
    }
}

JavaScript

ShockScript gets too many roots from JavaScript, although more particularly linked to a previously abandoned version, JavaScript 2 (or ECMAScript 4th).

Map data type

The ShockScript's Map data type differs fundamentally from JavaScript's Map in that key-value pairs are accessed more naturally. ShockScript resolves the ambiguity between pairs and the prototype by differentiating property read and call.

m.x = 10
m.length()

Note: For a customized type, it might be necessary to access a fixed variable rather than an arbitrary key-value pair; for that, the user may use a fixed expression as in <?fixed={object.q::n}?>.

Variable shadowing

In ShockScript the following is valid in an activation:

var m:* = complex.manager;
// more code...
var m = Manager(m);

“not” keyword

not may be used to negate in or is operators:

e not in a
v is not T

“this” binding

The this binding is fixed and present only in instance methods.

Methods like [object Function].apply() do not take a this binding: only the parameters.
Instance methods are bound.

Java

Package flexibility

While importing definitions, the user can alias a definition, or even a package.

package com.business.product.core {
    //
    public class Chart {
        //
    }
}
package com.business.product.core {
    //
    public enum ChartType {
        const BAR;
        const FLOW;
    }
}

import pns = com.business.product.*;
//
const chart_type : pns::ChartType = "flow";
//
const chart = new pns::Chart(chart_type);

XML

The ShockScript language includes XML capabilities.

XML expressions

XML expressions by default are used for creating implementation-defined objects; however, when the inference type is XML or XMLList, XML expressions evaluate to one of these types.

package com.business.components {
    //
    public function AppBar():whack.ds.Node {
        return (
            <w:HGroup>
                <w:Button click&={trace("clicked!")}>button 1</w:Button>
            </w:HGroup>
        );
    }
}

package com.business.editor {
    //
    public function data(a:String):XML {
        return (
            <tag>{a}</tag>
        );
    }
}

const xn = XML(<tag/>);

Attributes

<t a/> is equivalent to <t a={true}/>. Accessing XML attributes can be directly done by the @ operator, as in xnode.@x.

Event handlers

Inline event handlers may be expressed as eventName&={statementList} as a shortcut to eventName={function(event){statementList}}, as in:

<w:Button click&={trace("clicked!")}>Click me</w:Button>

If the event has no parameters, then the attribute above is equivalent to eventName={function(){statementList}}.

Interpolation

<w:VGroup {params}>
    {undefined}
    {null}
    {node}
    {nodeList}
    {plainText}
    {number}
</w:VGroup>

Filtering

XML and XMLList implement the filter operator.

xnode.(*.@name == "Diantha")

Descendants

XML and XMLList implement the descendants operator.

xnode..tag

Whack XML

This section describes XML features specifically when applied as WhackDS nodes.

Native tags

Native tags belong to the implicit w namespace, such as <w:Button>. The w namespace is not overridable.

DOM “data” attributes

data attributes (like data-x) set over native tags, such as <w:Button>, contribute plain data attributes to the underlying DOM element.

Using a WhackDS bindable, the attribute would be accessed as bindable!.@["data-name"].

“key” attribute

The key attribute is reserved for uniquely identifying interpolated collection items.

Linking cascading style sheets

<w:Style> tags are used for linking style sheets to the parent tag and passing arguments to the style sheet (which are referred by the style sheet as param(color)).

package com.fun.components {
    //
    public function CustomComponent() {
        return (
            <w:Button>
                <w:Style color="yellow">
                    <![CDATA[
                        :host { color: param(color) }
                    ]]>
                </w:Style>

                click me
            </w:Button>
        );
    }
}

If the style sheet is too large, it may be moved out of the ShockScript file; for instance:

// CustomComponent.sx
package com.fun.components {
    //
    public function CustomComponent() {
        return (
            <w:Button>
                <w:Style
                    source="CustomComponent.css"
                    color="yellow"/>
                click me
            </w:Button>
        );
    }
}
/* CustomComponent.css */
:host {
    color: param(color);
}

Style blocks can be conditional, as in:

<w:Style if={condition}>
    ...
</w:Style>

An arbitrary map of parameters (Map.<String, String>) may be passed as well:

<w:Style {map}>
    ...
</w:Style>

Linking style sheets in custom components

For a component to support <w:Style> tags, it simply needs to support a stylesheet : [whack.ds.StyleSheet] parameter.

package com.fun.components {
    //
    public function CustomComponent(vars: {
        stylesheet? : [whack.ds.StyleSheet],
    }) {
        //

        return (
            <w:Button>
                <w:Style extend={vars.stylesheet}/>
                click me
            </w:Button>
        );
    }
}

The extend attribute may be used to include externally loaded styles as well.

Specifying inline styles

Use s:n={v} attributes as a shortcut to style={{ ..., n: v }}.

<w:Button s:background="orange">button1</w:Button>

WhackDS

WhackDS is a feature of the Whack engine used for extending the closed set of Whack's UI component classes with reactive components. It is functionally similiar to React.js, but its syntax is more similiar to Adobe MXML.

Memoization

WhackDS automatically memoizes components, allowing for user customizable parameter/state equality comparison through overriding the [object Object].equals(obj) method. Memoization basically serves the purpose of avoiding re-rendering a component when its parameters do not change.

Just like with React.js, memoizing components has drawbacks such as possibly volatile code regions (such as when internationalizing a product with locale-specific translation strings). In such cases, relying on a WhackDS context will re-render the component when the context changes regardless of whether parameters did or not change.

WhackDS skips re-rendering component if the parent re-renders and the parameters are equals to the previous render; the WhackDS component's own states updating with a different value will always re-render it.

Style blocks

WhackDS supports style sheets out of the box. Here is a simple example:

<w:VGroup>
    <w:Style>
        <![CDATA[
            :host {
                background: red;
            }
        ]]>
    </w:Style>
</w:VGroup>

Tooling

Building and structuring projects should feel way like Cargo from the Rust language, at least in the Whack engine.

Configuration ease

Configuring ShockScript projects is way easier compared to other technologies.

Unlike NPM + TypeScript, you do not have to worry about transpilation or whatsoever when building libraries or applications; not even comparable as ShockScript targets WebAssembly. If you were implementing a library in NPM + TypeScript, you were forced to transpile TypeScript to JavaScript first due to the tsconfig.json file which is ignored from third-party dependencies while compiling, otherwise you would get inconsistent transpilation or compiler errors.

Whack case

API documentation

API documentation is automatically built for packages that are published to the Whack package registry.

Namespaces

ShockScript define properties whose name is tied to a namespace, which is useful for version control and protection.

package com.company.runner {
    /** @private */
    public namespace runner_internals;
}

package com.company.runner {
    //
    public class Helper {
        /** @private */
        runner_internals const cache : [Number] = [];

        //
        public function track() {
            runner_internals::cache.push(0);
        }
    }
}

package com.company.runner.advanced {
    import com.company.runner.*;

    //
    public function f(helper:Helper) {
        helper.runner_internals::cache.push(10);
    }
}

Namespaces additionally apply to record types.

package com.business.product {
    /**
     * Flexible version control namespace.
     */
    public namespace Flexible = "http://business.com/product/flexible";
}

package com.business.product {
    /**
     * Judgement version control namespace.
     */
    public namespace Judgement = "http://business.com/product/judgement";
}

package com.business.product {
    /**
     * Pair.
     */
    public type Pair = {
        Flexible::strength : [decimal],
        Judgement::strength : [decimal],
    };
}

Event model

The native EventTarget class is designated for dispatching and listening to events, and actual implementations may use it for implementing a hierarchic DOM event model.

In addition, the IEventTarget interface may be implemented instead of extending the EventTarget class.

Implementing an event target

The following program demonstrates implementing a basic EventTarget subclass that is able to emit events:

/**
 * Some event.
 */
[Event(name="act", type="Event")]
/**
 * Some class.
 */
class Actor extends EventTarget {
    /**
     * Some method.
     */
    public function m() {
        this.emit(new Event("act"));
    }
}

Listening to an event

Subscribing to an event looks as follows:

actor.on("act", function() { trace("acting") });

Implementing an event class

Event constructors must always take the event type as the first argument; any other arguments may follow. In the following code the user inherits the Event constructor.

class SomeEvent extends Event {}

EventTarget implementation

It is a rare case for the user to need to implement their own EventTarget class: it may only arise if the user needs EventTarget to work with their own Document Object Model.

emit()

The emit() method is defined as follows:

[Limit(E, eventOf="this", match="object")]
/**
 * Dispatches an event.
 */
public function emit.<E>(e:E):Boolean {
    // code
}

When the emit() method is used, it will force a new E(...) expression to be a correct Event object construction, by ensuring the first argument identifies a determined event type according to E.

on()

The on() method is roughly defined as follows:

[Limit(E, eventOf="this", match="type")]
/**
 * Registers an event listener.
 */
public function on.<E>(type:E.name, listener:function(E.type):void) : void {
    //
}

The third parameter was omitted for clarity.

Conditional compilation

NAMESPACE::CONSTANT

NAMESPACE::CONSTANT {
    //
}

NAMESPACE::CONSTANT var x

Clonage

The [object Object].clone() implementation clones tuples, arrays and maps structurally; for class instances, the default implementation requires an optional constructor. You may override clone for a custom clonage implementation.

object.clone()

Iteration

ShockScript features full object-oriented iteration.

iterator.length()
iterator.some(function(v) v > 0)
iterator.(* > 0) // filter

The user may override the key and value iterators by implementing the Iterable.<K, V> interface.

class A implements Iterable.<String, Number> {
    /**
     * Iterate keys.
     */
    public function keys():Iterator.<String> {
        for (var i = 0; i < 10; i++) {
            yield i.toString();
        }
    }

    /**
     * Iterate values.
     */
    public function values():Iterator.<Number> {
        for (var i = 0; i < 10; i++) {
            yield i;
        }
    }
}

Environment variables

Environment variables may be read from the project's .env file using the DotEnv::VAR_NAME expression:

DotEnv::SECRET

Type matching

“is” operator

v is T

“switch type” statement

switch type (v) {
    case (regex : RegExp) {
        trace("a regex");
    }
    case ([x, y] : [Number, Number]) {
        trace("a tuple of double");
    }
    default {
        trace("any other");
    }
}

Scope

This document specifies the syntax, semantics, execution and global objects of the ShockScript language.

Definitions

Code Point

A Code Point as specified by the Unicode standard.

Scalar Value

A Scalar Value as specified by the Unicode standard.

Required function

A function that contains at least one required parameter.

Required method

A method that contains at least one required parameter.

Required constructor

A constructor that contains at least one required parameter.

Notational conventions

Syntactic and lexical grammars

This document uses the following notation to define one or more productions of a nonterminal of the syntactic grammar:

Symbol

Production1

Symbol1

ProductionN

This document uses double colon (::) notation to define productions of a nonterminal of the lexical grammar:

Symbol

terminal

The _opt subscript is used to indicate that a nonterminal symbol is optional.

Symbol

Symbol1

_opt

A bracketed clause or predicate may appear between the rules of a production, such as in:

Symbol

Symbol1

default

Symbol2

SourceCharacters

<![CDATA[

The «empty» clause is matched by the grammar where other rules do not match otherwise.

Symbol

«empty»

Braces subscripts are used to quantify a rule:

Symbol_{4} — Four of Symbol
Symbol_{2,} — At least two of Symbol
Symbol_{1,4} — One to four of Symbol

Types

This section describes the data types and certain type expressions available in ShockScript.

Wildcard type

The * type is dynamically typed and consists of all possible values in other types.

void type

The void type consists of the undefined value.

null type

The null type consists of the null value.

String type

The String type represents an UTF-8 encoded character sequence.

Note: the .length property of a String equals the byte total, and the .chars().length() method of a String equals the Code Point total.

Nullability

Even though it is a primitive type, the String type may be assigned null to indicate absence of value, as it is a reference type.

Note: null and "" are two different values. You may test for both through using String as a falsy condition.

Boolean type

The Boolean type consists of the values false and true.

Number type

The Number type represents an IEEE 754 double-precision floating point.

BigInt type

The BigInt type represents an arbitrary range integer.

float type

The float type represents an IEEE 754 single-precision floating point.

decimal type

The decimal type represents a 128 bit decimal number.

int type

The int type represents a signed 32-bit integer.

uint type

The uint type represents an unsigned 32-bit integer.

Array type

The Array.<T> type, abbreviated [T], represents a growable list of elements.

Numeric optimization

[T] is optimized for when T is a number type; for instance, [uint] will use a growable buffer optimized specifically for 32-bit unsigned integers.

Map type

The Map.<K, V> type represents a hash map.

Map.<K, V>

Note: Property access on a Map equals data access. Method call on a Map equals a Map method use.

Instance usage

const map = new Map.<String, Number>();

// x=10
map.x = 10;

const fns = new Map.<String, Function>();

// m=function
fns.m = function() 10;

// m()
trace((fns.m)());

Tuple types

Tuple types, of the form [T1, T2, ...TN], are immutable sequences consisting of known element types at compile time. A tuple type contains at least two elements.

[Boolean, float]

Function types

Structural function types inherit from the Function class, taking the form function(...) : T.

function(T1, T=, ...[T]):T

A structural function type may specify:

zero or more required parameters (T) followed by
zero or more optional parameters (T=) followed by
a rest parameter (...[T]),
and a result type.

Record types

Record types { ... } are simple property records. Record types are memory-efficient in cost of a hash-map-like field access.

Note: The decision for having record types compiling into hash-map structures is because these types use to contain many fields, for instance, in WhackDS components and in operations requiring a large number of options.

type N1 = { x : decimal, y : decimal };

type N2 = {
    /** x */
    x:Number,

    /** y */
    y?:Boolean,
};

Note: Record types do not match with types structurally unlike in structural-type-first languages. They are simply structures the user may express inline.

Version control

Fields of a record type may be tied to a namespace, which is useful for version control.

package com.business.product {
    /**
     * Flexible version control namespace.
     */
    public namespace Flexible = "http://business.com/product/flexible";
}

package com.business.product {
    /**
     * Judgement version control namespace.
     */
    public namespace Judgement = "http://business.com/product/judgement";
}

package com.business.product {
    /**
     * Pair.
     */
    public type Pair = {
        Flexible::strength : [decimal],
        Judgement::strength : [decimal],
    };
}

Field omission

All fields are required unless they contain undefined or null. A field such as x?:T is equivalent to x:(void, T).

Field order

Due to sensitive field order, record types with equivalent fields but in different orders will be incompatible.

Writing ShockDoc comments

Fields may have a preceding ShockDoc comment, as in:

type R = {
    /**
     * Comment.
     */
    x : Number,
};

Compatibility

Two record types are compatible only if either a) one is used as a subset of another or b) fields are equivalent and appear in the same order.

Rest

One trailing ...rest component may appear in a record, where rest must be another record type. The resulting type is a subtype of rest and properties must not collide.

// A
type A = { x:Number };
// B < A
type B = { y:Number, ...A };

Union types

The structural union type, written (m1, m2, ...mN), consists of two or more non-union member types containing all possible values of the member types.

(decimal, String)

Restrictions

Unions never contain the * type.
Unions contain two or more members.

Default value

The default value of an union type is determined as follows:

If it contains void, then undefined.
If it contains null, then null.
No default value.

Nullability

The following shorthands are available for nullability:

T? or ?T is equivalent to (null, T).
T! removes null and/or void from T.

Object type

All types but { void, null, uint, int, float, Number, decimal, BigInt, Boolean } represent referenceable objects, which are nullable by default. The Object class is inherited by all types but { *, void, null, union }.

Note: When it is necessary to obtain the constructor of an object, use:
obj.Reflect::class()

This type

The this type expression may be used to match the this literal's type, which changes across subclasses.

class A {
    function chainable():this (this);
}

class B extends A {}

const obj = new B();
obj.chainable() // known as B

Conversions

This section describes which type conversions are available.

Explicit conversions may occur as either T(v) (strict conversion) or v as T (optional conversion). The behavior of the call operator over a type may not always be a conversion depending on if T implements the static shock_proxy::call() method.

T(v)       // failure throws a TypeError
v as T     // returns T?. failure returns null

Constant coercions

Constant coercions occur implicitly both at compile-time and runtime, converting a constant into another constant.

Kind	Result
`undefined` to flag enumeration	Interned instance whose value is zero (0).
`null` to flag enumeration	Interned instance whose value is zero (0).
`undefined` to `T` containing both `undefined` and `null`	`undefined`
`undefined` to `T` containing `undefined` and no `null`	`undefined`
`undefined` to `T` containing `null` and no `undefined`	`null`
`null` to `T` containing `undefined` but not `null`	`undefined`
`null` to `T` containing `null` but not `undefined`	`null`
`null` to `T` containing both `undefined` or `null`	`null`
Numeric constant to `*` or `Object`	Equivalent constant of the target type.
String constant to `*` or `Object` or union containing `String`	Equivalent constant of the target type.
Boolean constant to `*` or `Object` or union containing `Boolean`	Equivalent constant of the target type.
Namespace constant to `*` or `Object` or union containing `Namespace`	Equivalent constant of the target type.
Type constant to `*` or `Object` or union containing `Class`	Equivalent constant of the target type.
Numeric constant to another compatible numeric type	Numeric constant with value coerced to target type.
Numeric constant to union containing at least one compatible numeric type	Numeric constant of the target type containing value coerced to the containing numeric type, preferring the same numeric type or otherwise the first numeric type found.
`NaN` to `float`	`NaN`
`-Infinity` to `float`	`-Infinity`
`+Infinity` to `float`	`+Infinity`

Implicit coercion

Implicit coercions occur implicitly both at compile-time and runtime, after trying a constant coercion.

Kind	Result
From `*`
To `*`
From numeric type to compatible numeric type
To covariant (includes base classes, implemented interfaces, unions and inherited record type)
From union to compatible union
From union member to union
From structural function type to another compatible function type

Note: interface types inherit Object.

Explicit conversions

Explicit conversions occur when resolving v as T or T(v), after trying an implicit coercion.

Kind	Result
To contravariant (from `interface` to `interface` subtype, from `class` to subclass, or record type subtype)
To union member
From `*` or `Object` to `interface`
To another `[T]` type	An array filtering out incompatible elements.
`String` to enumeration	Identification of an enumeration variant by its `String` name.
Number to enumeration (using the same numeric type)	For regular enumerations, identifies a variant by its numeric value. For flag enumerations, identifies variant bits.
To `String`	For `undefined`, returns `"undefined"`; for `null`, returns `"null"`; for other types, invokes `toString()`.
To `Boolean`	Evaluates truthy value.
To `Number`	Forced conversion to double-precision floating point.
To `float`	Forced conversion to single-precision floating point.
To `decimal`	Forced conversion to 128-bit decimal number.
To `int`	Forced conversion to 32-bit signed integer.
To `uint`	Forced conversion to 32-bit unsigned uninteger.
To `BigInt`	Forced conversion to an arbitrary range integer.
Record type into equivalent record type of non-uniform field order
From type parameter

Note: interface types inherit Object.

Property lookup

LookupKey

LookupKey is either LocalName(name) or Computed(value).

LookupKey.Value

LookupKey.Value returns:

For LocalName(name), a StringConstant equivalent to name or defer if String is unresolved.
For Computed(value), value.

LookupKey.Type

LookupKey.Type returns:

For LocalName(name), the String type or defer.
For Computed(value), the static type of value or defer.

LookupKey.Double

LookupKey.Double returns:

For LocalName(name), undefined.
For Computed(value), value is NumberConstant(v) ? force convert v to a Number : undefined.

PropertyLookup()

PropertyLookup(base, openNsSet, qual, key as LookupKey, followedByCall as Boolean, fixed as Boolean) takes the following steps in order, where fixed allows forcing access to a fixture property on dynamic types (used by the <?fixed={}?> expression):

If base is invalidation
- Return invalidation
Let localName = key is LocalName(name) ? name : undefined
Let doubleKey = key.Double
If base is a TypeConstant(type)
- base = type
Else if base is a FixtureReferenceValue and base.Property is a type
- base = base.Property
If base is a class
- If localName is undefined or (qual is specified and qual is not a namespace nor a NamespaceConstant)
  - Return StaticDynamicReferenceValue(base, qual, k.Value)
- For each descending class in base hierarchy
  - Defer if class is unresolved.
  - Let r = GetQNameInNsSetOrAnyPublicNs(class static properties, openNsSet, qual, localName)
  - If r != undefined
    - Mark r as used.
    - Let r = r.ResolveAlias()
    - Defer if r property's static type is unresolved.
    - Return r.Wrap()
- Return undefined
If base is an interface
- Return undefined
If base is a value
- Let baseType = static type of base or defer
- If baseType is invalid
  - Return invalid
- baseType = baseType.ResolveAlias()
- If (followedByCall == false and fixed == false) and baseType defines an instance method shock_proxy::get (possibly a multi method)
  - Let foundRegularProperty = false
  - For each shock_proxy::get(k:K):V method
    - If qual != undefined
      - If K == * or K == (Object or defer) or K == (QName or defer) or K ?union contains (QName or defer)
        
        Return KeyValuePairReferenceValue(base, proxy method, qual as a Namespace object, key.Value coerced to (String or defer))
      - Continue loop
    - If key.Value is a (String or defer) value and (K == (QName or defer) or (K ?union does not contain String and K union contains QName))
      - Return KeyValuePairReferenceValue(base, proxy method, undefined, key.Value)
    - If K == * or K == (Object or defer) or K == (String or defer) or K == (QName or defer) or (K ?union contains String or K union contains QName)
      - foundRegularProperty = true
    - If (static type of key.Value or defer) fails on implicit coercion to K
      - Continue loop
    - Return KeyValuePairReferenceValue(base, proxy method, undefined, key.Value implicitly coerced to K)
  - If (static type of key.Value or defer) != (String or defer) or foundRegularProperty
    - Throw a verify error
- Let hasKnownNs = qual == undefined or (qual is a namespace or NamespaceConstant)
- If localName == undefined
  - If doubleKey != undefined and baseType is a tuple
    - Let i = doubleKey coercion to integer
    - If i < 0 or i >= baseType.ElementTypes.Length
      - Throw a verify error
    - Return TupleReferenceValue(base, i)
  - Return DynamicReferenceValue(base, qual, key.Value, followedByCall, fixed)
- If baseType == *
  - Return DynamicReferenceValue(base, qual, key.Value, followedByCall, fixed)
- If baseType is a class
  - For each descending class in baseType hierarchy
    - Defer if class is unresolved
    - Let prop = GetQNameInNsSetOrAnyPublicNs(class prototype properties, openNsSet, qual, localName)
    - If prop != undefined
      - Mark prop as used
      - prop = prop.ResolveAlias()
      - Call prop.Defer() (if about to defer, implementation may report the cause as unresolved expression in a location)
      - If prop is a namespace or NamespaceConstant
        
        Return NamespaceConstant(prop) if prop is a namespace, or otherwise prop as is
      - Return InstanceReferenceValue(base, prop)
  - For implemented interfaces of baseType
    - Lookup method (step required for optional methods)
- Else if baseType is an interface
  - For each descending itrfc in baseType hierarchy
    - Defer if itrfc is unresolved
    - Let prop = GetQNameInNsSetOrAnyPublicNs(itrfc prototype properties, openNsSet, qual, localName)
    - If prop != undefined
      - Mark prop as used
      - prop = prop.ResolveAlias()
      - Call prop.Defer() (if about to defer, implementation may report the cause as unresolved expression in a location)
      - Return InstanceReferenceValue(base, prop)
  - Lookup for the Object instance definitions
- Return undefined.
If base is a package
- If localName is undefined or (qual is specified and qual is not a namespace nor a NamespaceConstant)
  - Throw a verify error
- Let r = undefined
- Let prop = GetQNameInNsSetOrAnyPublicNs(base properties, openNsSet, qual, localName)
- If prop != undefined
  - Mark r as used.
  - prop = prop.ResolveAlias()
  - Call prop.Defer() (if about to defer, implementation may report the cause as unresolved expression in a location)
  - r = prop.Wrap()
- Return r
If base is a type parameter with a Limit(..., eventOf="...", match="type") constraint
- If localName is undefined or (qual is specified)
  - Return undefined.
- If localName = name
  - Return EventNameType(base type parameter).Wrap()
- If localName = type
  - Return EventTypeType(a previously introduced EventNameType).Wrap().
- Return undefined.
Return undefined.

Note: entity.Wrap() wraps entities into values. For instance, wrapping a variable into a property reference, where it belongs to a package, will produce a PackageReferenceValue.

Note: entity.Defer() defers if an entity is unresolved or if a direct compound is unresolved.

InScopeLookup()

InScopeLookup(scope, qual, key as LookupKey, followedByCall as Boolean, fixed as Boolean) takes the following steps in order:

Note: Content lacking.

Packages

A package consists of a ascending domain name, a set of properties and two namespaces, public and internal.

A package com.business.enum is expressed as:

package com.business.enum {
    //
}

Note: One common convention is for packages to use a prefix domain (one of ( com, net, org, me )); alternatively an user may use a prefixless domain name (such as skia rather than com.google.skia). The me prefix is used for personal content and the rest for companies, organizations and groups.

The user defines properties under the package inside the package block, as in:

package f.q {
    public function f() {}
}

Top-level package

The top-level package, which defines global properties, is equivalent to:

package {
    //
}

When a global name is shadowed, the user may use the special global namespace to lookup a global name:

Math
    // or
global::Math

Name shadowing

It is possible to fully qualify a name in an expression using a package and one of its items, shadowing any other variables.

import org.colourful.color.Color;
var com = 0;
trace( org.colourful.color.Color(0x10_00_00) );
trace( Color(0x10_00_00) );

ReadMe

A directory identifying a package relative to a source path may contain a README file (either README or README.md) written as Markdown text, which serves as a means to attach documentation to the package.

Package single import

A package single import is contributed to the lexical scope for the following directive:

import f.q.x;

Package wildcard import

A package wildcard import is aliased for the following directive:

import q = com.business.quantum.*;

Then q may be used as a qualifier to resolve to a name in the com.business.quantum.* package (excluding subpackages).

q::x

For the following directive, the package wildcard import is contributed to the lexical scope:

import com.business.quantum.*;

Source path

A package definition must contain exactly one definition item, and its name must match the source path.
A source file must consist of exactly one package definition.

Namespaces

Names are three-dimensional, consisting of a namespace (the qualifier) and a local name. The :: punctuator is used in qualified identifiers for using a namespace prefix and a local name, as in:

q::n
o.q::n

Namespaces appear as optional access modifiers in annotatable definitions, as in:

special_properties var acc:decimal = 0;

There are reserved namespaces and user namespaces.

Reserved namespaces

Reserved namespaces are created implicitly by the language:

public
internal
protected
private
static protected

They are tied to a parent (such as a package, a class or a scope).

A namespace definition that omits the URI creates an internal namespace:

namespace special_properties;

User namespaces

User namespaces are identified by an URI.

namespace observer_internals = "http://observer.net/internals";

Classes

A class is an inheritable user-defined type that may be used to create objects.

class C1 {
    //
}
const obj = new C1();

Inner namespaces

A class owns three namespaces:

private
protected
static protected

protected and static protected are propagated to the block of subclasses.

ShockDoc comment

A class may be prefixed by a ShockDoc comment.

/** Comment */
class C1 {}

Meta-data

A class may have zero or more meta-data.

[M1]
[M2]
class C1 {}

Inheritance

class A {}
class B extends A {}

Member shadowing

Members from base classes must not be shadowed except for overriding methods.

class C1 {
    function m() {}
}
class C2 extends C1 {
    function m() {} // ERROR!
}

Default inheritance

By default a class, excluding Object, inherits Object. A class can extend at most one class.

Final classes

A final class may not be extended:

final class A {}

class B extends A {} // ERROR!

Implementing interfaces

A class may implement zero or more interfaces:

class C1 implements I1, I2 {
    //
}

Constructor inheritance

If the constructor of a class is not explicitly defined, then it is based on the base class's constructor, using the same signature and initializing the instance with default field values:

class A {
    var x:Number;
    function A(x:Number) {
        this.x = x;
    }
}
class B extends A {
    var y:Number = 10;
}
new B(0);
new B(); // ERROR!

Constructor

The constructor of a class is a special initialization method named as the class itself, as in:

class C1 {
    function C1() {}
}

Super statement

The super statement is used to invoke the constructor from the base class from a subclass constructor.

A constructor must contain the super statement if a class is inherited which consists of a required constructor.

class A {
    function A(x:Number) {}
}
class B extends A {
    function B() {
        super(0);
    }
}

Abstract classes

An abstract class may not be directly instantiated through the new operator, and may define abstract methods. Non abstract subclasses are allowed to be instantiated.

abstract class A {
    abstract function m():void;
}

Static classes

A static class may not be instantiated or inherited, and by convention consists of static properties and methods.

static class MyNamespace {
    public static const VALUE:Number = 10.5;
}

Events

The class, in convention when either extending EventTarget or implementing IEventTarget, may define possibly emitted events through using multiple Event meta-data.

/**
 * Event.
 */
[Event(name="eventName", type="T")]
/**
 * Target.
 */
class A extends EventTarget {}

Static properties

Definitions marked static that appear within the class block are part of the static properties of the class, which are accessed as C.n where C is teh class and n the property name.

Instance properties

Definitions not marked static that appear within the class block are part of the prototype of the class, and are called instance properties.

Enumerations

Enumerations are special classes consisting of zero or more variants.

enum Variant {
    const VARIANT_ONE;
    const VARIANT_TWO = "variantTwo";
    const VARIANT_THREE = [2, "variantThree"];
}

Note: Variable definitions within an enum define static constants which are referred to as variants.

Final

Enumerations are final, so they cannot be extended.

Static

Enumerations are static, so they cannot be instantiated through the new operator.

Type inference

When the inference type in a string literal is an enumeration, the literal may identify a variant by its name.

var val:Variant = "variantOne";

When the inference type in an array literal or object initializer is a flag enumeration, the literal may be used to identify multiple variants.

[Flags]
enum F { const A, B, C }

const m:F = ["a", "b", "c"];
    // or
const m:F = { a: true, b: true, c: true };

Flag enumerations

Flag enumerations differ from regular enumerations by having instances being able to contain zero or more variants.

[Flags]
enum F { const A, B, C }

Flag enumerations may be assigned undefined, null or [] to indicate absence of variants.

All variants

Obtain all variants of a flag enumeration by using the ** expression with the enumeration as the inference type:

var f:F = **;

Internation

Flag enumeration objects are interned so that flags may be compared correctly.

[Flags]
enum E { const A, B, C }

const obj:* = E(["a", "b"]);
trace(obj == E(["a", "b"]));

Customizing the numeric type

Enumerations use the Number type by default to represent the variant values. The user is allowed to change the type to another numeric type through using a meta-data named after that numeric type.

[decimal]
enum E1 {
    const A, B, C;
}

Variant initializer

The initializer of a variant may be expressed in four different forms, or simply be omitted:

StringLiteral
NumericLiteral
[StringLiteral, NumericLiteral]
[NumericLiteral, StringLiteral]

The ArrayLiteral syntax is used to allow specifying both a string and a number.

Variant name

The variant name as declared by the const is determined as follows:

Let r = empty string
If the initializer does not contain a string literal
1. Let orig = binding identifier name
2. r = a screaming snake case (ABC_DEF) to camel case (abcDef) conversion of orig.
Else
1. r = the value of the string literal at the initializer.
If r is already used by another variant's name
1. Throw a verify error
Return r

Variant value

The variant value as declared by the const is determined as follows:

If the enumeration is a flag enumeration 2. Return DecideFlagValue()
Return DecideValue()

DecideValue()

Let r = zero
If the initializer does not contain a numeric literal
1. If there is no previous variant, return 0.
2. Let k = previous variant's value
3. r = k + 1
Else
1. r = the value of the numeric literal at the initializer.
If r is already used by another variant's value
1. Throw a verify error
Return r

DecideFlagValue()

Let r = zero
If the initializer does not contain a numeric literal
1. If there is no previous variant, return 1.
2. Let k = previous variant's value
3. r = k * 2
Else
1. r = the value of the numeric literal at the initializer.
2. If r is not one or a power of two
  1. Throw a verify error
If r is already used by another variant's value
1. Throw a verify error
Return r

Implicitly added methods

For all enumerations

valueOf()

public override function valueOf():T {
    //
}

Returns the numeric value of the enumeration instance, where T is the numeric type.

toString()

public override function toString():String {
    //
}

Returns the name of the enumeration instance. For a flag enumeration, returns the names of the enumeration instance delimited by comma (,) by ascending value order.

For flag enumerations

shock_proxy::has()

shock_proxy function has(v:E):Boolean {
    //
}

Returns a boolean indicating whether the instance contains the specified flags or not, where E is the enumeration itself.

This allows for f in e expressions.

with()

public function with(v:E):E {
    //
}

Returns a new value containing the specified flags, where E is the enumeration itself.

without()

public function without(v:E):E {
    //
}

Returns a new value removing the specified flags, where E is the enumeration itself.

toggled()

public function toggled(v:E):E {
    //
}

Returns a new value toggling the specified flags, where E is the enumeration itself.

Customized methods

Enumerations support customized methods:

enum E {
    const A, B, C;
    function get isA() this == "a";
}

Enumerations are prohibited from using variable definitions for purposes other than defining variants.

Interfaces

Interfaces are user defined, non opaque types that may be implemented by classes through their implements clause.

interface I {
    //
    function m() : void;

    //
    function get x() : Number;
    function set x(value);
}

interface Ia extends I {}

The interface block may only contain function definitions, including regular methods, getters and setters.

Basemost type

An interface is a subtype of Object, although compile-time property lookups do not inherit Object properties.

ShockDoc comment

An interface may be prefixed by a ShockDoc comment.

/** Comment */
interface I {}

Meta-data

An interface may have zero or more meta-data.

[M1]
[M2]
interface I {}

Inheritance

An interface may extend other interfaces through the extends clause.

interface I3 extends I1, I2 {}

Shadowing members

Members from base interfaces must not be shadowed.

interface I1 {
    function m() {}
}
interface I2 extends I1 {
    function m() {} // ERROR!
}

Required methods

When interface methods omit their body, they are classified as required methods.

interface I {
    function m():void;
}

Provided methods

When interface methods contain a body, they are classified as provided methods.

interface I {
    function m() {
        //
    }
}

Method annotations

As annotations, interface methods may have nothing but an access modifier that is allowed to be anything but a direct reserved namespace.

interface I {
    shock_proxy function get(key:String):String;
}

Events

The interface, in convention when implementing IEventTarget, may define possibly emitted events through using multiple Event meta-data.

/**
 * Event.
 */
[Event(name="eventName", type="T")]
/**
 * Target.
 */
interface I extends IEventTarget {}

Variables

A variable may be read-only or writeable, and consists of a type.

var x = 0
const y = 10

ShockDoc comment

A ShockDoc comment can be applied to a variable.

/** Comment */
var x

Meta-data

A variable may have zero or more meta-data.

[M1]
[M2]
var x

Initializer

If the initializer of a variable is a constant, then the variable consists of a constant initializer.

var x = 0

Local shadowing

Re-declaring a variable is allowed inside activation blocks.

var m:* = central.manager;
// more code...
var m = Manager(m);

Virtual variables

Virtual variables consist of either:

a getter and a setter (writable);
a getter (read-only);
a setter (write-only).

A virtual variable's type is determined based on the getter or setter.

function get x():float 10;
function set x(val) {
    //
}

ShockDoc comment

A virtual variable derives ShockDoc comments from its getter or setter.

/** Comment */
function get x():float 10;

Meta-data

A virtual variable collects meta-data from its getter or setter.

[M1]
[M2]
function get x():float 10;

Methods

A method is a function that may be invoked. An instance method is a method defined in a class, enum or interface block which is not marked static.

function m() {}

Getters and setters are methods belonging to a virtual variable:

function get x():decimal 10;
function set x(val) {}

Constructors are methods that implement initialization for a class instance, as in:

class A {
    function A() {}
}

ShockDoc comment

A ShockDoc comment can be applied to a method.

/** Comment */
function m() {}

Meta-data

A method may have zero or more meta-data.

[M1]
[M2]
function m() {}

Final method

Instance methods may have a final modifier, indicating that they are not to overriden by subclasses.

class A {
    final function m() {}
}

Abstract method

Instance methods may have an abstract modifier under an abstract class, indicating that they must be overriden by subclasses.

abstract class A {
    abstract function m():void;
}

Generators

A method is a generator if the yield operator appears at least once in the method's body. A generator is a method that evaluates like an iterator, consumed in pauses of yield operators until it hits a return statement or the end of code. A generator returns a Generator.<T> object.

function g():Number {
    yield 100.5;
}

If a method uses both yield and await, it is considered an iterator of Promise, therefore returning Generator.<Promise.<T>>.

Asynchronous methods

A method is asynchronous if the await operator appears at least once in the method's body. An asynchronous method returns a Promise.<T> object.

function f():void {
    await otherF();
}

If a method uses both yield and await, it is considered an iterator of Promise, therefore returning Generator.<Promise.<T>>.

Multi-methods

A method may be defined more than once with varying signatures, turning into a multi-method. Signatures must differ by the parameter list and not just the result type.

function f():decimal {
    //
}
function f(val:decimal):Chainable {
    //
}

Overriding

An instance method may override a method in a base class through using the override modifier:

override protected function m() {
    //
}

Remarks

A getter must override a getter, and a setter must override a setter.
For a multi method, the override shall match a specific signature.

Overriding rules

A method S may override a method B with the following rules:

S must begin with the same list of parameters as that of B.
If B does not contain a rest parameter
- S may include additional optional parameters and/or a rest parameter.
S must have the same result type of B, or a subtype of the B result type.

Bound methods

Instance methods are bound such that retrieving a method from an instance will return a method tied to the instance.

class A {
    function m():this {
        return this;
    }
}
const o = new A;
const { m } = o
trace(m == o.m); // true
trace(o == m());

Aliases

Aliases are used in different places of the language:

import CT = com.business.coreRT.enum.ContactType;
import q = com.business.quantum.*;
type U = (decimal, String);
namespace special_version;

ShockDoc comment

An alias may be prefixed by a ShockDoc comment.

/** Comment */
type Params = {
    x : decimal,
};

Meta-data

Meta-data are bracketed, arbitrary entries of textual key-value pairs that may be attached to ShockScript definitions. Meta-data are not unique and may appear more than once, as well as their key-value pairs.

[M1]
class A {}

[M1(x="y", z="w")]
class A {}

[M1(y)]
class A {}

Keyless entries are a single identifier (equivalent to a string) or a string literal not accompanied by a key.

Reserved meta-data

Certain meta-data are reserved in certain contexts, such as Event and Limit.

Generics

Classes, interfaces, type aliases and functions may specify type parameters, turning into generic entities. ShockScript implements generic entities using polymorphism.

Note: Array data types of Number, float, decimal, int and uint are specialized so they are represented in a memory efficient way.

class A.<T> {
    // code
}
interface I.<T> {
    // code
}

type Alias.<T> = (decimal, [T]);

function f.<T>():void {
}

Parameter constraints

Type parameters may be attached multiple constraints.

[Limit(T, subtypeOf="A")]
/**
 * Some function.
 */
function f.<T>(o:T) {
    //
}

[Limit(E, eventOf="A", match="type")]
/**
 * Another function.
 */
function f.<E>(type:E.name, value:E.type) {
    //
}

[Limit(E, eventOf="A", match="object")]
/**
 * Yet another function.
 */
function f.<E>(value:E) {
    //
}

“eventOf” constraints

eventOf constraints allow inspecting available events as defined by the Event meta-data in classes and interfaces, including the inherited events and events from the implemented interfaces.

eventOf constraints are allowed to take this as the base type, reflecting the current class's events:

package com.business.coreRT.events {
    /**
     * Event dispatcher.
     */
    public class EventTarget {

        [Limit(E, eventOf="this", match="object")]
        /**
         * Dispatches an event.
         */
        public function emit.<E>(e:E):Boolean {
            //
        }
    }
}

match="type" yields the name-type pair of an event. The .type property of the pair relies on previous introduction of the respective .name somewhere.
match="object" ensures event creation is correct by analyzing the new E(type, ...) expression.

Note: The match="type" constraint contributes a name field that yields the String type, but its purpose is for auto completion in integrated development environments.

Lexical scopes

Internal properties

Name	Description
[[Parent]]	Optional parent scope.
[[OpenNamespaces]]	Open namespace list.
[[Properties]]	The scope properties.
[[Imports]]	The import list.

Import list

The import list may contain package single imports and package wildcard imports.

Scope variants

With scope

The with scope is created by the with statement, causing the wildcard * expression to resolve to the parenthesized object.

with (object.from.somewhere)
    *.x *= 10,
    *.y *= 3;

Added internal properties

Name	Description
[[Object]]	Object used in the `with` statement.

Class scope

Added internal properties

Name	Description
[[Class]]	Class object.

Enum scope

Added internal properties

Name	Description
[[Class]]	Class object.

Interface scope

Added internal properties

Name	Description
[[Interface]]	The interface.

Package scope

Added internal properties

Name	Description
[[Package]]	Package.

Activation

Method bodies create an activation as scope.

Added internal properties

Name	Description
[[This]]	The `this` object.
[[Method]]	Method.

Default lexical scope

The topmost scope from which all scopes inherit is implicitly created by ShockScript.

Imports

The topmost scope imports the top-level package by wildcard. It is allowed to shadow names from the top-level package, in which case, the global alias may be used to access the top-level package.

global

The topmost scope defines a global property, which is an alias to a package wildcard import of the top-level package.

Intl

The topmost scope defines an Intl property, which is an alias to a package wildcard import of the shock.intl package.

Temporal

The topmost scope defines an Temporal property, which is an alias to a package wildcard import of the shock.temporal package.

GlobalReflection

The topmost scope defines an GlobalReflection property, which is an alias to a package wildcard import of the shock.reflection.global package.

Conditional compilation

The NAMESPACE::CONSTANT expression may match a configuration constant used for conditional compilation.

NAMESPACE::CONSTANT {
    //
}

NAMESPACE::CONSTANT var x

The following program uses an inline constant.

trace(NAMESPACE::CONSTANT)

Integrated configuration constants

CONFIG::DEBUG

The CONFIG::DEBUG constant indicates whether or not the program is targetting a debug build.

CONFIG::RELEASE

The CONFIG::RELEASE constant indicates whether or not the program is targetting a release build.

CONFIG::TEST

The CONFIG::TEST constant indicates whether or not the program is compiling for evaluating unit tests.

Unit testing

Basic unit testing may be done by defining functions with the Test meta-data at a package-level.

package com.example.foo.tests {
    // Unit tests
    CONFIG::TEST {
        [Test]
        /**
         * Test foo.
         */
        public function testFoo():void {
            assertEquals(2 + 2, 4);
        }
    }
}

ShockDoc comments

ShockDoc are documentation comments that use the format /** */. Markdown notation is supported in ShockDoc comments.

For each line, the beginning whitespace is stripped, then the * character and a single following white space character are stripped, and the resting characters are the actual line contents.

Line contents may start with a tag (such as @deprecated). Tags may span multiple lines until the next tag appears; tags that do not accept content do not span any more characters.

Code blocks (whose delimiters consist of at least three backticks ```) as expressed in Markdown cause tags to be ignored in the code content, as in:

/**
 * ```plain
 * @deprecated
 * ```
 */

Local images

ShockDoc comments may refer to relative images through the Markdown notation ![image](./path/to/image).

Supported tags

@copy

Copies ShockDoc comment from another definition. Use a #x component to refer to an instance property.

@copy A
@copy A.w
@copy A#x
@copy #x

@default

Default value as an uninterpreted expression.

@default exp

@deprecated

@deprecated [Description]

@example

@example
The following...

@eventparam

Indicates that a record type's property is an event handler. The tag does nothing but move the item to the Events section of the documentation, similiar to how happens with the Event meta-data used in class definitions.

@eventparam

@inheritDoc

Inherits documentation from base class or base class's item.

@inheritDoc

@internal

Internal comment for an item (not included in the generated documentation).

@internal Comment.

@param

@param paramName Description

@private

Hides an item from the generated documentation.

@private

@return

@return Description

@see

Where item maybe an item reference with optional #x instance property, or just an instance property #x.

@see item [Display text]

@throws

@throws ClassName [Description]

Proxies

Methods of the shock_proxy namespace may be implemented in a class or interface for overriding language behavior, known as proxies.

shock_proxy::call()

A static shock_proxy::call() method may be defined with any number of parameters and any result type, overriding the behavior of calling the class object.

shock_proxy static function call():T {}

A multi-method may be used, allowing for multiple call signatures.

shock_proxy::get()

Note: Overriding the property accessor with a possibly String or QName key type (including base types * and Object) will override all names (like .x), except when calling a method (like .m()). In that case, a class is said to be dynamic.

If the user needs to access an instance variable in such a case it is recommended to use a fixed expression as in
<?fixed={object.q::n}?>

shock_proxy function get(key:K):V {
    //
}

shock_proxy::set()

Note: Overriding the property accessor with a possibly String or QName key type (including base types * and Object) will override all names (like .x), except when calling a method (like .m()). In that case, a class is said to be dynamic.

shock_proxy function set(key:K, value:V):void {
    //
}

shock_proxy::delete()

Note: Overriding the property accessor with a possibly String or QName key type (including base types * and Object) will override all names (like .x), except when calling a method (like .m()). In that case, a class is said to be dynamic.

shock_proxy function delete(key:K):Boolean {
    //
}

shock_proxy::has()

Overrides the behavior of the in operator.

shock_proxy function has(key:K):Boolean {
    //
}

shock_proxy::getAttribute()

Overrides the behavior of the .@k accessor.

shock_proxy function getAttribute(key:K):V {
    //
}

shock_proxy::setAttribute()

Overrides the behavior of the .@k = v accessor.

shock_proxy function setAttribute(key:K, value:V):void {
    //
}

shock_proxy::deleteAttribute()

Overrides the behavior of the delete (...).@k accessor.

shock_proxy function deleteAttribute(key:K):Boolean {
    //
}

shock_proxy::filter()

Overrides the behavior of the filter operator (.(test)).

shock_proxy function filter(testFn:function(T):Boolean):E {
    //
}

shock_proxy::descendants()

Overrides the behavior of the descendants operator (..x). The parameter is expected to be typed String or QName.

shock_proxy function descendants(name:QName):E {
    //
}

Lexical conventions

This section defines the lexical grammar of the ShockScript language.

The tokenizer scans one of the following input goal symbols depending on the syntactic context: InputElementDiv, InputElementRegExp, InputElementXMLTag, InputElementXMLPI, InputElementXMLContent.

The following program illustrates how the tokenizer decides which is the input goal symbol to scan:

/(?:)/       ;
a / b        ;
<a>Text</a>  ;

The following table indicates which is the input goal symbol that is scanned for each of the tokens comprising the previous program:

Token	Input goal
/(?:)/	InputElementRegExp
;	InputElementDiv
a	InputElementRegExp
/	InputElementDiv
b	InputElementRegExp
;	InputElementDiv
<	InputElementRegExp
a	InputElementXMLTag
>	InputElementXMLTag
Text	InputElementXMLContent
</	InputElementXMLContent
a	InputElementXMLTag
>	InputElementXMLTag
;	InputElementDiv

The InputElementXMLPI goal symbol must be used when parsing the <?fixed={exp}?> markup.

Syntax

InputElementDiv

WhiteSpace

LineTerminator

Comment

Identifier

ReservedWord

Punctuator

NumericLiteral

StringLiteral

InputElementRegExp

WhiteSpace

LineTerminator

Comment

Identifier

ReservedWord

Punctuator

NumericLiteral

StringLiteral

RegularExpressionLiteral

XMLMarkup

<?fixed={

InputElementXMLTag

XMLName

XMLTagPunctuator

XMLAttributeValue

XMLWhitespace

{

InputElementXMLPI

InputElementXMLContent

XMLMarkup

XMLText

{

Source Characters

Syntax

SourceCharacter

Unicode code point

SourceCharacters

SourceCharacter

SourceCharacters

_opt

White Space

The WhiteSpace token is filtered out by the lexical scanner.

Syntax

WhiteSpace

Line Terminator

The LineTerminator token is filtered out by the lexical scanner, however it may result in a VirtualSemicolon to be inserted.

Syntax

LineTerminator

Comment

The Comment token is filtered out by the lexical scanner, however it propagates any LineTerminator token from its characters.

/*
 * /*
 *  *
 *  */
 */

Syntax

Comment

SingleLineCommentCharacters

MultiLineComment

SingleLineCommentCharacters

SingleLineCommentCharacter

SingleLineCommentCharacters

_opt

SingleLineCommentCharacter

LineTerminator

SourceCharacter

MultiLineComment

MultiLineCommentCharacters

_opt

MultiLineCommentCharacters

SourceCharacters

MultiLineComment

MultiLineCommentCharacters

SourceCharacters

MultiLineCommentCharacters

MultiLineComment

Virtual Semicolon

The VirtualSemicolon nonterminal matches an automatically inserted semicolon, known as a virtual semicolon.

Virtual semicolons are inserted in the following occasions:

After a right-curly character }
Before a LineTerminator

Identifier

The Identifier symbol is similiar to that from the ECMA-262 third edition, but with support for scalar Unicode escapes.

Syntax

Identifier

IdentifierName

ReservedWord

ContextKeyword

IdentifierName

IdentifierStart

IdentifierName

IdentifierPart

IdentifierStart

UnicodeLetter

UnicodeEscapeSequence

IdentifierPart

UnicodeLetter

UnicodeCombiningMark

UnicodeConnectorPunctuation

UnicodeDigit

UnicodeEscapeSequence

UnicodeLetter

UnicodeDigit

Unicode decimal digit number (“Nd”)

UnicodeCombiningMark

UnicodeConnectorPunctuation

Unicode connector punctuation (“Pc”)

Keywords

ReservedWord includes the following reserved words:

as
do
if
in
is

for
new
not
try
use
var

case
else
null
this
true
void
with

await
break
catch
class
const
false
super
throw
while
yield

delete
import
public
return
switch
typeof

default
extends
finally
package
private

continue
function
internal

interface
protected

implements

ContextKeyword is one of the following in certain syntactic contexts:

get
set

each
enum
type

Embed
final

native
static

abstract
override

namespace

Punctuator

Punctuator includes one of the following:

::  @
.  ..  ...
(  )  [  ]  {  }
:  ;  ,
?  !  =
?.
<  <=
>  >=
==  ===
!=  !==
+  -  *  %  **
++  --
<<  >>  >>>
&  ^  |  ~
&&  ^^  ||  ??

The @ punctuator must not be followed by a single quote ' or a double quote character ".

Punctuator includes CompoundAssignmentPunctuator. CompoundAssignmentPunctuator is one of the following:

+=  -=  *=  %=  **=
<<=  >>=  >>>=  &=  ^=  |=
&&=  ^^=  ||=
??=

Numeric Literal

NumericLiteral is similiar to NumericLiteral from the ECMA-262 third edition, with support for binary literals and underscore separators:

0b1011
1_000

Syntax

NumericLiteral

DecimalLiteral

IdentifierStart

DecimalDigit

HexIntegerLiteral

IdentifierStart

DecimalDigit

BinIntegerLiteral

IdentifierStart

DecimalDigit

DecimalLiteral

DecimalIntegerLiteral

UnderscoreDecimalDigits

_opt

ExponentPart

_opt

UnderscoreDecimalDigits

ExponentPart

_opt

DecimalIntegerLiteral

ExponentPart

_opt

DecimalIntegerLiteral

NonZeroDigit

UnderscoreDecimalDigits

_opt

DecimalDigits

DecimalDigit

_{1,}

UnderscoreDecimalDigits

DecimalDigits

UnderscoreDecimalDigits

DecimalDigits

DecimalDigit

NonZeroDigit

ExponentPart

ExponentIndicator

SignedInteger

ExponentIndicator

SignedInteger

UnderscoreDecimalDigits

HexIntegerLiteral

UnderscoreHexDigits

HexDigit

UnderscoreHexDigits

HexDigit

_{1,}

UnderscoreDecimalDigits

HexDigit

_{1,}

BinIntegerLiteral

UnderscoreBinDigits

BinDigit

UnderscoreBinDigits

BinDigit

_{1,}

UnderscoreDecimalDigits

BinDigit

_{1,}

Regular Expression Literal

RegularExpressionLiteral is similiar to RegularExpressionLiteral from the ECMA-262 third edition, with support for line breaks.

Syntax

RegularExpressionLiteral

RegularExpressionBody

RegularExpressionFlags

RegularExpressionBody

RegularExpressionFirstChar

RegularExpressionChars

RegularExpressionChar

RegularExpressionFirstChar

SourceCharacter

BackslashSequence

RegularExpressionChar

SourceCharacter

BackslashSequence

SourceCharacter

RegularExpressionFlags

IdentifierPart

String Literal

StringLiteral is similiar to the StringLiteral symbol from the ECMA-262 third edition. The following additional features are included:

Scalar UnicodeEscapeSequence using the \u{...} form
Triple string literals
Raw string literals using the @ prefix

Triple string literals use either """ or ''' as delimiter and may span multiple lines. The contents of triple string literals are indentation-based, as can be observed in the following program:

const text = """
    foo
    bar
    """
text == "foo\nbar"

Triple string literals are processed as follows:

The first empty line is ignored.
The base indentation of a triple string literal is that of the last string line.

Both regular and triple string literals accept the @ prefix, designating raw string literals. Raw string literals contain no escape sequences.

const text = @"""
    x\y
    """

Escape sequences are described by the following table:

Escape	Description
\'	U+27 single-quote
\"	U+22 double-quote
\\	U+5C backslash character
\b	U+08 backspace character
\f	U+0C form feed character
\n	U+0A line feed character
\r	U+0D carriage return character
\t	U+09 tab character
\v	U+0B vertical tab character
\0	U+00 character
\xHH	Contributes an Unicode code point value
\uHHHH	Contributes an Unicode code point value
\u{...}	Contributes an Unicode code point value
\ followed by LineTerminator	Contributes nothing

Syntax

StringLiteral

"""

DoubleStringCharacter

_{0,}

'''

SingleStringCharacter

_{0,}

"""

TripleDoubleStringCharacter

_{0,}

"""

'''

TripleSingleStringCharacter

_{0,}

'''

RawStringLiteral

"""

DoubleStringRawCharacter

_{0,}

'''

SingleStringRawCharacter

_{0,}

@"""

TripleDoubleStringRawCharacter

_{0,}

"""

@'''

TripleSingleStringRawCharacter

_{0,}

'''

DoubleStringCharacter

SourceCharacter

LineTerminator

EscapeSequence

SingleStringCharacter

SourceCharacter

LineTerminator

EscapeSequence

DoubleStringRawCharacter

SourceCharacter

LineTerminator

SingleStringRawCharacter

SourceCharacter

LineTerminator

TripleDoubleStringCharacter

"""

SourceCharacter

LineTerminator

EscapeSequence

LineTerminator

TripleSingleStringCharacter

'''

SourceCharacter

LineTerminator

EscapeSequence

LineTerminator

TripleDoubleStringRawCharacter

"""

SourceCharacter

LineTerminator

TripleSingleStringRawCharacter

'''

SourceCharacter

LineTerminator

Escape Sequences

Syntax

EscapeSequence

CharacterEscapeSequence

DecimalDigit

LineTerminator

HexEscapeSequence

UnicodeEscapeSequence

CharacterEscapeSequence

SingleEscapeCharacter

NonEscapeCharacter

SingleEscapeCharacter

NonEscapeCharacter

SourceCharacter

EscapeCharacter

LineTerminator

EscapeCharacter

SingleEscapeCharacter

DecimalDigit

HexEscapeSequence

HexDigit

UnicodeEscapeSequence

HexDigit

_{4}

{

HexDigit

_{1,}

}

XML

This section defines nonterminals used in the lexical grammar as part of the XML capabilities of the ShockScript language.

If a XMLMarkup, XMLAttributeValue or XMLText contains a LineTerminator after parsed, it contributes such LineTerminator to the lexical scanner.

Syntax

XMLMarkup

XMLComment

XMLCDATA

XMLPI

XMLWhitespaceCharacter

XMLWhitespace

XMLWhitespaceCharacter

XMLWhitespace

XMLWhitespaceCharacter

XMLText

SourceCharacters

{

XMLName

XMLNameStart

XMLName

XMLNamePart

XMLNameStart

UnicodeLetter

XMLNamePart

UnicodeLetter

UnicodeDigit

XMLComment

<!--

XMLCommentCharacters

_opt

-->

XMLCommentCharacters

SourceCharacters

-->

XMLCDATA

<![CDATA[

XMLCDATACharacters

]]>

XMLCDATACharacters

SourceCharacters

]]>

XMLPI

XMLPICharacters

_opt

XMLPICharacters

SourceCharacters

XMLAttributeValue

XMLDoubleStringCharacters

_opt

XMLSingleStringCharacters

_opt

XMLDoubleStringCharacters

SourceCharacters

XMLSingleStringCharacters

SourceCharacters

XMLTagPunctuator

ShockScript: Expressions

The syntactic grammar for expressions declares the β superscript, which denotes a pair of definitions: allowIn and noIn.

Identifiers

Syntax

x
*
q::x
q::[k]     ;
(q)::x     ;
(q)::[k]   ;
@x
@[k]
@q::x
@q::[k]
@(q)::x
@(q)::[k]

PropertyIdentifier

Identifier

IdentifierName

Qualifier

PropertyIdentifier

ReservedNamespace

public

private

protected

internal

SimpleQualifiedIdentifier

PropertyIdentifier

Qualifier

PropertyIdentifier

Qualifier

Brackets

ExpressionQualifiedIdentifier

ParenExpression

PropertyIdentifier

ParenExpression

Brackets

NonAttributeQualifiedIdentifier

SimpleQualifiedIdentifier

ExpressionQualifiedIdentifier

QualifiedIdentifier

Brackets

NonAttributeQualifiedIdentifier

Primary expressions

Syntax

PrimaryExpression

NullLiteral

BooleanLiteral

NumericLiteral

StringLiteral

ThisLiteral

AllLiteral

RegularExpressionLiteral

QualifiedIdentifier

XMLLiteral

FixedExpression

ParenListExpression

ArrayLiteral

ObjectLiteral

EmbedExpression

Null literal

Syntax

NullLiteral

null

This literal

Syntax

ThisLiteral

this

All literal

Syntax

**

AllLiteral

Semantics

The all literal returns a value of a Flags enumeration filled with the all flags from that Flags enumeration. The context type must be a Flags enumeration.

Boolean literal

Syntax

BooleanLiteral

true

false

Numeric literal

Syntax

10
10.0
.0
10e5
1e+9
1e-9
0b1011
0xFF
10_000

String literal

Syntax

"shockscript"

Triple string literals span multiple lines and are indentation-aware:

(
    """
    shockscript, nicely beauty
    scripting.
    """
) == "shockscript, nicely beauty\nscripting."

Regular expression literal

Syntax

/(?:)/gi

XML literal

Syntax

XMLLiteral

XMLMarkup

XMLElement

XMLElementContent

XMLElement

XMLTagContent

XMLWhitespace

_opt

XMLTagContent

XMLWhitespace

_opt

XMLElementContent

XMLTagName

XMLWhitespace

_opt

XMLTagContent

XMLTagName

XMLAttributes

XMLTagName

{

AssignmentExpression

^allowIn

}

XMLName

XMLAttributes

XMLWhitespace

{

AssignmentExpression

^allowIn

}

XMLAttribute

XMLAttributes

XMLAttribute

XMLWhitespace

XMLName

XMLWhitespace

_opt

XMLWhitespace

_opt

XMLWhitespace

XMLName

XMLWhitespace

_opt

XMLWhitespace

_opt

{

AssignmentExpression

^allowIn

}

XMLWhitespace

XMLName

XMLWhitespace

_opt

XMLWhitespace

_opt

Block

XMLWhitespace

XMLName

XMLWhitespace

_opt

XMLWhitespace

_opt

XMLAttributeValue

XMLElementContent

{

AssignmentExpression

^allowIn

}

XMLElementContent

XMLMarkup

XMLElementContent

XMLText

XMLElementContent

XMLElement

XMLElementContent

Array literal

Syntax

["shock", "script"]

ArrayLiteral

[

Elision

_opt

]

[

ElementList

]

[

ElementList

Elision

_opt

]

Elision

ElementList

Elision

_opt

AssignmentExpression

^allowIn

Elision

_opt

LiteralRest

ElementList

Elision

_opt

AssignmentExpression

^allowIn

ElementList

Elision

_opt

LiteralRest

Object literal

Syntax

ObjectLiteral

{

FieldList

}

FieldList

NonEmptyFieldList

LiteralField

LiteralRest

NonEmptyFieldList

LiteralField

NonEmptyFieldList

LiteralRest

...

AssignmentExpression

^allowIn

LiteralField

FieldName

AssignmentExpression

^allowIn

NonAttributeQualifiedIdentifier

FieldName

NonAttributeQualifiedIdentifier

Brackets

StringLiteral

NumericLiteral

Embed expression

Syntax

Embed("flower.webp")

// UTF-8 text
Embed("data.txt", "text/plain")

// ByteArray
Embed("data.bin", "application/octet-stream")

EmbedExpression

Embed (

MetadataEntryList

_opt

)

Semantics

The default form of the embed expression specifying solely a path is implementation-defined, but always returns a String representing an URL.

The form that specifies a path followed by a "text/plain" option will embed the referenced file at the program's static memory as an UTF-8 encoded text, returning the String data type.

The form that specifies a path followed by a "application/octet-stream" option will embed the referenced file at the program's static memory as an octet stream, returning the ByteArray data type.

Fixed expression

Syntax

<?fixed={x}?>

FixedExpression

<?fixed={

ListExpression

^allowIn

}

Semantics

Deactivates lookup of dynamic properties (implemented through a shock_proxy proxy such as shock_proxy::get(k) where k includes String or QName) in the enclosed expression.

Note: This is necessary in rare cases where, for example, a class implements its own dynamic properties which may collide with its prototype. In such cases, instance variables are not accessible unless the user uses the fixed expression <?fixed={exp}?>. In the case of this, the fixed expression is not necessary as in-scope lookup always uses fixed name lookup.

The fixed name lookup effect is propagated:

From parenthesized expressions to the inner expression
From dot operator to base expression
From brackets operator to base expression

Parenthesized expressions

Syntax

(x)

ParenExpression

(

AssignmentExpression

^allowIn

)

ParenListExpression

ParenExpression

(

ListExpression

^allowIn

AssignmentExpression

^allowIn

)

Super expression

Syntax

SuperExpression

super

Arguments

Postfix expressions

Syntax

PostfixExpression

FullPostfixExpression

ShortNewExpression

FullPostfixExpression

PrimaryExpression

FullNewExpression

FullPostfixExpression

PropertyOperator

SuperExpression

PropertyOperator

FullPostfixExpression

NonNull

FullPostfixExpression

Arguments

FullPostfixExpression

TypeArguments

FullPostfixExpression

QueryOperator

FullPostfixExpression

OptionalChaining

NonNull

OptionalChaining

QualifiedIdentifier

Brackets

Arguments

OptionalChaining

PropertyOperator

OptionalChaining

NonNull

OptionalChaining

Arguments

OptionalChaining

TypeArguments

OptionalChaining

QueryOperator

OptionalChaining

Property accessors

Syntax

PropertyOperator

QualifiedIdentifier

Brackets

[

ListExpression

^allowIn

]

Query operators

Syntax

QueryOperator

QualifiedIdentifier

(

ListExpression

^allowIn

)

Descendants operator

o..x

Semantics

The descendants operator o..x looks at o for the shock_proxy::descendants() method and returns the result of invoking that method with the given identifier key.

Filter operator

o.(*.name.startsWith("A"))

Semantics

The filter operator o.(...) looks at o for the shock_proxy::filter() method and creates a wildcard * binding inside the parenthesized expression that represents the element being tested. The parenthesized expression must return a Boolean and represents an activation.

Call expressions

Syntax

Arguments

(

)

(

ListExpression

^allowIn

)

ArgumentList

^allowIn

AssignmentExpression

^β

ArgumentList

^β

AssignmentExpression

^β

New expressions

Syntax

FullNewExpression

new

FullNewSubexpression

Arguments

FullNewSubexpression

PrimaryExpression

FullNewExpression

FullNewSubexpression

PropertyOperator

SuperExpression

PropertyOperator

ShortNewExpression

new

ShortNewSubexpression

FullNewSubexpression

ShortNewExpression

Unary expressions

Syntax

UnaryExpression

PostfixExpression

delete

PostfixExpression

void

UnaryExpression

await

UnaryExpression

typeof

UnaryExpression

PostfixExpression

UnaryExpression

Binary expressions

The binary operators are left-associative, excluding the following cases:

The exponentiation operator ** is right-associative.

The short circuit operators (||, ^^) have the lowest precedence and the exponentiation operator (**) has the greatest precedence.

Exponentiation expressions

Syntax

ExponentiationExpression

UnaryExpression

ExponentiationExpression

Multiplicative expressions

Syntax

MultiplicativeExpression

ExponentiationExpression

MultiplicativeExpression

ExponentiationExpression

MultiplicativeExpression

ExponentiationExpression

MultiplicativeExpression

ExponentiationExpression

Additive expressions

Syntax

AdditiveExpression

MultiplicativeExpression

AdditiveExpression

MultiplicativeExpression

AdditiveExpression

MultiplicativeExpression

Shift expressions

Syntax

ShiftExpression

AdditiveExpression

ShiftExpression

AdditiveExpression

ShiftExpression

AdditiveExpression

ShiftExpression

>>>

AdditiveExpression

Relational expressions

Syntax

RelationalExpression

^β

ShiftExpression

RelationalExpression

^β

ShiftExpression

RelationalExpression

^β

ShiftExpression

RelationalExpression

^β

ShiftExpression

RelationalExpression

^β

ShiftExpression

RelationalExpression

^β

ShiftExpression

RelationalExpression

^β

ShiftExpression

RelationalExpression

^β

is not

ShiftExpression

RelationalExpression

^β

ShiftExpression

RelationalExpression

^β

not in

ShiftExpression

Equality expressions

Syntax

EqualityExpression

^β

RelationalExpression

^β

EqualityExpression

^β

RelationalExpression

^β

EqualityExpression

^β

RelationalExpression

^β

EqualityExpression

^β

===

RelationalExpression

^β

EqualityExpression

^β

!==

RelationalExpression

^β

Bitwise expressions

Syntax

BitwiseAndExpression

^β

EqualityExpression

^β

BitwiseAndExpression

^β

EqualityExpression

^β

BitwiseXorExpression

^allowIn

BitwiseAndExpression

^β

BitwiseXorExpression

^β

BitwiseAndExpression

^β

BitwiseOrExpression

^allowIn

BitwiseXorExpression

^β

BitwiseOrExpression

^β

BitwiseXorExpression

^β

Logical expressions

Syntax

LogicalAndExpression

^β

BitwiseOrExpression

^β

LogicalAndExpression

^β

BitwiseOrExpression

^β

LogicalXorExpression

^allowIn

LogicalAndExpression

^β

LogicalXorExpression

^β

LogicalAndExpression

^β

LogicalOrExpression

^allowIn

LogicalXorExpression

^β

LogicalOrExpression

^β

LogicalXorExpression

^β

Coalesce expression

Syntax

CoalesceExpression

^β

CoalesceExpressionHead

^β

BitwiseOrExpression

^β

CoalesceExpressionHead

^β

CoalesceExpression

^β

BitwiseOrExpression

^β

Short circuit expressions

Syntax

ShortCircuitExpression

^β

LogicalOrExpression

^β

CoalesceExpression

^β

Conditional expressions

Syntax

ConditionalExpression

^β

ShortCircuitExpression

^β

ShortCircuitExpression

^β

AssignmentExpression

^β

AssignmentExpression

^β

Non assignment expressions

Syntax

NonAssignmentExpression

^β

ShortCircuitExpression

^β

yield

NonAssignmentExpression

^β

FunctionExpression

^β

ShortCircuitExpression

^β

NonAssignmentExpression

^β

NonAssignmentExpression

^β

Assignment expressions

Syntax

AssignmentExpression

^β

ConditionalExpression

^β

yield

AssignmentExpression

^β

FunctionExpression

^β

AssignmentLeftHandSide

AssignmentExpression

^β

PostfixExpression

CompoundAssignmentPunctuator

AssignmentExpression

^β

PostfixExpression

/= AssignmentExpression^β

AssignmentLeftHandSide

ArrayPattern

ObjectPattern

PostfixExpression

ArrayLiteral

ObjectLiteral

Function expression

Syntax

FunctionExpression

^β

function

FunctionCommon

^β

function

IdentifierName

FunctionCommon

^β

List expressions

Syntax

ListExpression

^β

AssignmentExpression

^β

ListExpression

^β

AssignmentExpression

^β

ShockScript: Type expressions

Syntax

TypeExpression

NonPrefixedTypeExpression

TypeExpressionList

TypeExpression

TypeExpressionList

TypeExpression

NonPrefixedTypeExpression

this

void

null

(

QualifiedIdentifier

(

TypeExpression

)

(

TypeExpression

TypeExpressionList

)

TupleTypeExpression

RecordTypeExpression

FunctionTypeExpression

NonPrefixedTypeExpression

PropertyOperator

NonPrefixedTypeExpression

QueryOperator

NonPrefixedTypeExpression

TypeArguments

NonPrefixedTypeExpression

NonNull

NonPrefixedTypeExpression

TupleTypeExpression

[

TypeExpression

]

[

TypeExpression

TypeExpressionList

]

[

TypeExpression

TypeExpressionList

]

RecordTypeExpression

{}

{

RecordTypeItemList

}

RecordTypeItemList

RecordTypeField

RecordTypeItemList

...

TypeExpression

RecordTypeField

NonAttributeQualifiedIdentifier

TypeExpression

FunctionTypeExpression

function

(

)

TypeExpression

function

(

FunctionTypeParameterList

)

TypeExpression

FunctionTypeParameterList

FunctionTypeParameter

FunctionTypeParameterList

FunctionTypeParameter

...

TypeExpression

_opt

TypeExpression

TypeArguments

TypeArgumentsList

GenericGreaterThan

TypeArgumentsList

TypeExpression

TypeArgumentsList

TypeExpression

ShockScript: Patterns

Destructuring patterns may be used in a number of contexts, including variable bindings, try..catch clauses, switch type cases and assignment left-hand sides.

Where applicable, expressions are disambiguated into destructuring patterns, in which case any incompatible or illegal expression results in a syntax error; for example, an expression is disambiguated in a pattern in an assignment whose left-hand side starts with a bracket [ or a brace {.

Syntax

Pattern

Identifier

IdentifierName

ArrayPattern

ObjectPattern

TypedPattern

Pattern

TypeExpression

Array pattern

Syntax

ArrayPattern

[]

[

ArrayPatternItemList

]

ArrayPatternItemList

Pattern

ArrayPatternItemList

...

Pattern

Object pattern

Syntax

ObjectPattern

{}

{

ObjectPatternFieldList

}

ObjectPatternFieldList

ObjectPatternField

ObjectPatternFieldList

ObjectPatternField

FieldName

Pattern

NonAttributeQualifiedIdentifier

ShockScript: Statements

The ω superscript used throughout the specification translates to one of { abbrev, noShortIf, full }.

Syntax

Statement

^ω

SuperStatement

Semicolon

^ω

Block

IfStatement

^ω

SwitchStatement

DoStatement

Semicolon

^ω

WhileStatement

^ω

ForStatement

^ω

WithStatement

^ω

ContinueStatement

Semicolon

^ω

BreakStatement

Semicolon

^ω

ReturnStatement

Semicolon

^ω

ThrowStatement

Semicolon

^ω

TryStatement

ExpressionStatement

Semicolon

^ω

LabeledStatement

^ω

Substatement

^ω

EmptyStatement

Statement

^ω

Substatements

SubstatementsPrefix

Substatement

^abbrev

SubstatementsPrefix

Substatement

^full

Semicolon

^abbrev

;

VirtualSemicolon

Semicolon

^noShortIf

Semicolon

^abbrev

Semicolon

^full

;

VirtualSemicolon

Empty statement

Syntax

EmptyStatement

;

Expression statement

Syntax

ExpressionStatement

function

{

ListExpression

^allowIn

Super statement

Syntax

SuperStatement

super

Arguments

Block statement

Syntax

Block

{

Directives

}

Labeled statement

Syntax

LabeledStatement

^ω

Identifier

Substatement

^ω

If statement

Syntax

IfStatement

^abbrev

ParenListExpression

Substatement

^abbrev

ParenListExpression

Substatement

^noShortIf

else

Substatement

^abbrev

IfStatement

^full

ParenListExpression

Substatement

^full

ParenListExpression

Substatement

^noShortIf

else

Substatement

^full

IfStatement

^noShortIf

ParenListExpression

Substatement

^noShortIf

else

Substatement

^noShortIf

Switch statements

The switch statement is similiar to that of Java. Unlike in Java, the switch statement does not include fallthroughs.

switch (v) {
    case 0:
    case 1:
        trace("zero or one");
    default:
        trace("other");
}

The switch type statement is used to match the type of a discriminant value.

switch type (v) {
    case (d : Number) {
        // double
    }
    default {
        // no matching case
    }
}

Syntax

SwitchStatement

switch

ParenListExpression

{

CaseElements

^abbrev

}

switch

type

ParenListExpression

{

TypeCaseElements

}

CaseElements

^ω

CaseElement

^ω

CaseElements

^full

CaseElement

^ω

CaseElement

^ω

CaseLabel

_{1,}

CaseDirectives

^ω

CaseLabel

case

ListExpression

^allowIn

default :

CaseDirectives

^ω

Directive

^ω

CaseDirectives

^full

Directive

^ω

TypeCaseElements

TypeCaseElement

TypeCaseElements

TypeCaseElement

case (

TypedPattern

)

Block

default

Block

Do statement

Syntax

DoStatement

Substatement

^abbrev

while

ParenListExpression

While statement

Syntax

WhileStatement

^ω

while

ParenListExpression

Substatement

^ω

For statements

The for..in statement is used to iterate the keys of an object.

for (const key in map) {
    trace(key)
}

The for each statement is used to iterate the values of an object.

for each (const value in array) {
    trace(value)
}

Syntax

ForStatement

^ω

for (

ForInitializer

;

ListExpression

^allowIn

_opt

;

ListExpression

^allowIn

_opt

)

Substatement

^ω

for (

ForInBinding

ListExpression

^allowIn

)

Substatement

^ω

for

each (

ForInBinding

ListExpression

^allowIn

)

Substatement

^ω

ForInitializer

ListExpression

^noIn

VariableDefinition

^noIn

ForInBinding

PostfixExpression

VariableDefinitionKind

VariableBinding

^noIn

Continue statement

Syntax

ContinueStatement

continue

Identifier

Break statement

Syntax

BreakStatement

break

Identifier

With statement

The with statement is used to declare a * binding to the statement's scope. The * binding holds the value of the parenthesized expression.

with (o) {
    *.x += 10;
    *.y += 5;
}

Syntax

WithStatement

^ω

with

ParenListExpression

Substatement

^ω

Return statement

Syntax

ReturnStatement

return

ListExpression

^allowIn

Throw statement

Syntax

ThrowStatement

throw

ListExpression

^allowIn

Try statement

Syntax

TryStatement

try

Block

CatchClauses

try

Block

CatchClauses

_opt

finally

Block

CatchClauses

CatchClause

CatchClauses

CatchClause

catch (

TypedPattern

)

Block

ShockScript: Directives

Syntax

Directive

^ω

EmptyStatement

Statement

^ω

ConfigurationConstant

_opt

Attributes

_opt

AnnotatableDirective

^ω

ConfigurationConstant

Block

ImportDirective

Semicolon

^ω

UseDirective

Semicolon

^ω

AnnotatableDirective

^ω

NamespaceDefinition

Semicolon

^ω

VariableDefinition

^allowIn

Semicolon

^ω

FunctionDefinition

ClassDefinition

EnumDefinition

InterfaceDefinition

TypeDefinition

Semicolon

^ω

Directives

DirectivesPrefix

Directive

^abbrev

DirectivesPrefix

Directive

^full

ConfigurationConstant

Identifier

IdentifierName

Attributes

Attributes are in the sequence of meta-data followed by modifiers. A parser shall disambiguate expressions into attributes as applicable.

Syntax

Attributes

Attribute

AttributeLineBreakRestriction

AttributeCombination

AttributeLineBreakRestriction

AttributeCombination

Attribute

AttributeLineBreakRestriction

Attributes

BlockAttributes

Metadata

BlockAttributes

Metadata

AttributeLineBreakRestriction

IdentifierName

Attribute

Metadata

UserAttribute

ReservedNamespace

final

native

static

abstract

override

UserAttribute

Identifier

UserAttribute

IdentifierName

Metadata

MetadataPreRestriction

[

MetadataForm

]

MetadataPreRestriction

[

MetadataForm

MetadataTrailingComma

]

MetadataPreRestriction

Metadata

Attributes

Metadata

IdentifierName

Attributes

MetadataTrailingComma

Metadata

Attributes

BlockAttributes

MetadataForm

MetadataName

()

MetadataName

(

MetadataEntryList

)

MetadataName

Identifier

IdentifierName

MetadataEntryList

MetadataEntry

MetadataEntryList

MetadataEntry

MetadataName

StringLiteral

MetadataName

StringLiteral

Import directive

Syntax

ImportDirective

import

PackageName

. *

import

PackageName

IdentifierName

import

Identifier

PackageName

. *

import

Identifier

PackageName

IdentifierName

Use directive

The use namespace directive is used to contribute a namespace to the open namespace list of the enclosing scope.

use namespace ns1

Syntax

UseDirective

use namespace

ListExpression

^allowIn

ShockScript: Definitions

Namespace definition

The namespace definition may be primarily used to define a namespace that may be used for protecting or versioning other definitions and XML data processing.

namespace ns1
namespace ns2 = "http://example.com/secret/2015"

In addition, the namespace definition may also be used to define aliases to a package wildcard import, as in:

// com.inexistentninja.kunai.*
namespace kunai = "com.inexistentninja.kunai";

// an alias to the top-level package.
// users can just use `global` if it doesn't conflict
// with their names.
namespace shock_global = global;

Syntax

NamespaceDefinition

namespace

IdentifierName

namespace

IdentifierName

AssignmentExpression

^allowIn

Semantics

A URI namespace contains at least a colon; namespaces assigned a string literal without a colon will result into an alias to a package wildcard import.

Variable definition

Syntax

VariableDefinition

^β

VariableDefinitionKind

VariableBindingList

^β

VariableDefinitionKind

var

const

VariableBindingList

^β

VariableBinding

^β

VariableBindingList

^β

VariableBinding

^β

VariableBinding

^β

TypedDestructuring

VariableInitialization

^β

VariableInitialization

^β

AssignmentExpression

^β

Function definition

Syntax

FunctionDefinition

function

FunctionName

TypeParameters

_opt

FunctionCommon

^allowIn

Function name

Syntax

FunctionName

IdentifierName

get

IdentifierName

set

IdentifierName

FunctionName is used inside FunctionDefinition.

function f(): void {}
function get x(): Number (impl.x)
function set x(v: Number): void { impl.x = v }

TypeParameters may not appear in a function definition defining a getter, setter or constructor.

Function body

Syntax

function f():Number 10

function f():void {
    // code
}

FunctionCommon

^β

FunctionSignature

{

AssignmentExpression

^β

FunctionSignature

Block

Function signature

Syntax

FunctionSignature

(

Parameters

)

ResultType

TypeExpression

Parameter list

Syntax

Parameters

NonemptyParameters

Parameter

NonemptyParameters

RestParameter

Parameter

TypedPattern

AssignmentExpression

^allowIn

RestParameter

...

TypedPattern

Class definition

Syntax

Nested classes are not allowed; classes are only allowed in package blocks and top-level region.

ClassDefinition

class

IdentifierName

TypeParameters

_opt

Inheritance

Block

TypeParameters

. <

TypeParameterList

GenericGreaterThan

TypeParameterList

TypeParameter

TypeParameterList

TypeParameter

Identifier

Class inheritance

Syntax

Inheritance

extends

TypeExpression

implements

TypeExpressionList

extends

TypeExpression

implements

TypeExpressionList

Enum definition

Syntax

Nested enumerations are not allowed; enumerations are only allowed in package blocks and top-level region.

EnumDefinition

enum

IdentifierName

Block

Interface definition

Syntax

Nested interfaces are not allowed; interfaces are only allowed in package blocks and top-level region.

The interface block must only contain function definitions.

InterfaceDefinition

interface

IdentifierName

TypeParameters

_opt

ExtendsList

Block

Interface inheritance

Syntax

ExtendsList

extends

TypeExpressionList

Type definition

A type definition is used to define an alias to an existing type.

Syntax

type M = Map.<Number, Number>

Type definitions are only allowed in package blocks and top-level region.

TypeDefinition

type

IdentifierName

TypeParameters

_opt

TypeExpression

Package definition

Syntax

PackageDefinition

package

PackageName

_opt

Block

A PackageDefinition may be used in a Program before any Directive that is not a PackageDefinition is used.

Package name

Syntax

PackageName

Identifier

PackageName

IdentifierName

Program definition

Syntax

Program

Directives

PackageDefinition

Program

ShockScript Language Specification