This document is a work in progress
Please note: Updates for this document can be found at:
The dustyscript site
Dustyscript 1.0
Language notes as of the 6-27-03 (Post-1.0.RCB-CVS) release


Briefly, there are five ways to test the current Dustyscript set of commands.

  • Place your code in a text file, and then run (in "bin" dir) "java dscript.StatementProcessor FILENAME"
  • Run (from "bin" dir) "java dscript.ConsoleDusty" and type it in interactively.
  • Run (from "bin" dir) "java dscript.VisualShell" and type it in a Frame inter-actively
  • Place code in text file, and run (in 'bin') "java dscript.VisualShell FILENAME"

    • OR..finally...
  • Run (from "bin" dir) "java dscript.dde.DustyDevEnv" and use the Dustyscript IDE

    • Instructions (and/or language rules) are as follows:

    Variable 'types'
    string (equivalent to a Java String)
    decimal (equivalent to a Java double)
    integer (equivalent to a Java long)-literals between " "
    character (equivalent to a Java char)-literals between ' '

    Special variable type: anyvar
    anyvar
    ***this var type is a generic, to allow a little more flexibility
    example:
    action someaction takes anyvar a, gives ~ {/*decide what to do*/};

    Comments
    /* your comments go here and are ignored */

    Assignment 'operators'
    vartype varname is value;
    varname is now value;
    declare vartype varname;

  • this creates a variable with no value to be re-assigned
  • 'vartype' can be plural, and then it is a group

    • value can be the ask operator, or any combination of already assigned variables or literals..

    'String' operations...
    integer varname is location of string-value in string-value (optional: starting at integer-value;
    varname is now location of string-value in string-value (optional: starting at integer-value;
    stringvarname:integervalue

  • represents a single character at location 'integervalue' in the string

    • stringvarname:size
  • represents the length (in characters) of the string
  • this means that the 'string' type behaves like a group of characters

    • stringvarname:integer is now character;
  • The string var will change the character at the location specified by the 'integer' to 'character'

    • Removing a variable
    destroy varname;
    remove varname;

  • **Handle with extreme care!

    • Special 'assignment'::Array-like type called 'Group'
    group varname contains integer-value vartype-plural;

    this creates a group(array) called varname with integer-value members
    vartype-plural would be "integers", "strings", "decimals", "yes_nos"

    Each member is initialized as follows:
    varname:integer-value is now value;
    or
    varname:integer-value is now ask;

    'group' works OK with count
    group can be passed to and from actions

    Group operations
    grow groupname by integer;
    shrink groupname by integer;
    groupname:size ((an integer representing the size))
    groupname:last
    **this represents the last member of the group**

    ***Groups can contain Groups***

    The copies commands
    vartype varname copies value
    varname copies value

  • value can be a variable or literal

    Special 'group' capabilities

  • support added for [ ] indexing in groups.
  • The square brackets [ ] can contain any integer 'statement', such as:
    mygroup[myint + 1] is now ... ;
    mygroup[myAction using var1, var2, var3] is now ... ;
    **'myAction' must, naturally, give an integer
    **The following expression "mygroup[myint++]" will not work

    Console out/in operators
    say varname;
    say literal;
    say literal + varname + ....;
    ***outputs to the console***
    vartype varname is ask;
    varname is now ask; /*when var is already assigned*/
    ask for vartype varname;
    ask for varname; /*when var is already assigned*/
    ***assigns the input to varname***

    'Mathematical' operators
    +, plus for addition and string-concat.
    -, minus for subtraction(mathematical).
    *, times, multiplied by for multiplication (**special)
    /, over, divided by for division (**special)

  • multiplication and division:wrap all complex math in parentheses:
    vartype varname is (math expression);
  • Also, wrap any math in ( ) for comparator functions
    if (2+1) is equal to (1+2) {say "Associative";};

    Special operator(s)
    pause for integer-literal seconds;
    pause for integer-literal minutes;
    pause for integer-variable seconds|minutes

    count from integer through integer {..code block};
    count using name-for-var from integer through integer {..code block};

    Action prototyping
    action action-name takes var-type var-name, ...., gives vartype
    {Method body**};
    ** gives either is a var-type, or ~ for void.
    ** the action-body must end (inside) with a give statement:
    give return-var;
    give return-literal;
    give ~; /*optional*/
    ** a 'give' in the action-body skips to the last give statement in the action**

  • actions can have the same action-name as long as their return type or args-types are different
  • actions can take and give using the 'thing-type' name rather than just thing, such as:
    action action-name takes thing-type varname gives other-thing-type {/*BODY*/};
  • An action will match the type through all of its ancestors, from specific to general
  • An action will match on interfaces (see below) as well

    • Assignment using an action
    vartype varname is action-name using arguments;
    ie "integer i is add using 1, 2;"

    Compound action statements
    vartype varname is action-name using args + ..... + action-name using args;
    varname is now action-name using args + ..... + action-name using args;
    say action-name using args + ..... + action-name using args;

  • args is short for arguments
  • action-name must have a return value (not ~)

    Control-flow::special:: (Works for 'count' and 'as_long_as')
    break;
    **breaks to outside of a loop
    next;
    **skips the current loop-code, and re-evaluates

    Comparator statements
    if value comparator value {Block of Code};
    if value comparator value {Block of Code} else {Block of Code};
    if (value comparator value) {Block of Code};
    if (value comparator value) {Block of Code} else {Block of Code};

    Comparator Loops
    as long as value comparator value {Block of Code};
    as long as (value comparator value) {Block of Code};
    **See "break" and "skip" above for control-flow**

    * 'value' refers to a varname or literal... 'comparator' refers to a comparator phrase or symbol from the list below

    (new)More complex comparator statements
    keyword (value comparator value comparator .. value) {Code-block};

  • where 'keyword' refers to either 'if' or 'as long as'
  • if you have multiple levels of complex comparisons, wrap the entire expression in ()
    example: if (yes & no) | yes should be if ((yes & no) | yes) for proper evaluation

    Comparators (list)

  • newest
    & , && , and /*if this is true and that is true*/
    | , || , or /*if this is true or that is true*/
  • older
    == , is equal to
    != , is not equal to , does not equal
    > , is greater than
    >= , is greater than or equal to
    < , is less than
    <= , is less than or equal to
    contains /*this is for strings mainly*/
    does not contain /*this is for strings mainly*/

    Special Comparators (list)
    is a , is an , used in conjunction with a var-type
    is not a , is not an , used in conjunction with a var-type
    examples:
    if somevar is a decimal {/*do something*/};
    if somevar is not a string {/*do something*/};

    Including another Dustyscript program file
    use FILENAME;
    **this will load and run FILENAME, retaining all actions and variables assigned
    (like a C 'include' or Java 'import')

    File operations within a Dustyscript program
    load string-var from string-value;
    save string-value to string-value;

  • the last 'value' always represents the filename
  • files stored in ./users/data

    "Threads"(multi-tasking) in Dustyscript
    run separately {Code Block};
    do separately {Code Block};
    thread {Code Block};
    ***any of the above will run the block of code in a separate "thread"***
    thread as varname {/*code block*/};
    **creates a variable of type "thread"... the following can be done with this var**
    hibernate varname;
    sleep varname;
    **pause this thread until it is woken up
    awaken varname;
    **wake up a paused thread, will resume where it left off
    kill varname;
    **entirely stop this thread
    resurrect varname;
    restart varname;
    **restart this thread from the beginning

    The 'thing' type
    thing type thingtype-name {Block of code};
    thing thingtype-name {Block of Code};

  • 'block of code' needs to contain one action with the thingtype-name that gives ~
  • the above is called a 'constructor'

    Creating a 'thing' from a thing-type
    create thingtype varname using ...args... ;

    Accessing a thing's actions
  • demonstrated using a non-assignment action

    • thingname.action-name using ...args...;

    Descending from, or inheriting actions from, another Thing
    thing type thing-type-name extends predefined-thingtype{code-block};
    thing type thing-type-name descends from predefined-thingtype{code-block};
    thing type thing-type-name is a child of predefined-thingtype{code-block};

    Advanced "Thing-Type" issues: Interfaces and 'allow'

  • An interface is something which specifies what actions a thing that 'implements' it will have
  • There is no body to the actions defined
  • All 'args' and 'gives' types must match explicitly:
    **An action which takes a "MyThingType" defined in an interface will not be considered matched
    by an action in the implementor that takes Thing
    Examples:
    interface Example {
    action add takes integer i, integer j gives integer;
    };
    thing MyThing implements Example {
    action MyThing takes ~ gives ~ {};
    action add takes integer one, integer two gives integer {integer three is one + two ; give three;};
    };
  • A thing can implement any number of interfaces
  • Things are assumed to implement the interfaces implemented by the thing they extend
  • The following is acceptable:
    thing MyThing extends MyOtherThing implements InterfaceOne, InterfaceTwo, InterfaceThree
    {**BODY**};
  • A special keyword allow is provided for circular definitions.. where, for example:
    thing 'one' has an action that takes a 'two', and thing 'two' has an action that takes a 'one'.
    allow word_one, word_two, word_three;
  • 'word_one', 'word_two' and 'word_three' will now be treated as defined for the purpose of action/thing creation
  • Even though it is not acceptable to "extend" a thing that is not yet defined,
    you can 'implement' such an interface and you can use either an undefined thing-type or interface to create an action
  • A thing can reference its own type in one of its actions

    • 'Referring to' vs. 'Copying' a thing
    thing thingname refers to other-thingname;
    thing thingname is other-thingname;

  • thingname is another way to get at other-thingname
  • changes to one will affect the other

    • thing thingname copies other-thingname;
  • thingname is a copy of other-thingname
  • changes made to one will NOT affect the other


    • A 'Thing' referring to itself
    me
    this
  • example: "someThing.someAction using me;"


    • Checking a 'thing' type, and 'thing' comparisons
    if thing-var is type thing-type {Code Block};
  • the "is type" comparator works with interfaces (new, above) as well
    • comparisons using ==, != , is identical to
  • equality of things is when they are the same 'thing' with different variable names
  • is identical to compares things deeply, and if they are equivalent, is true
  • use the same basic 'if' structure to check these:
  • if value comparator value {Block of Code} else {Block of Code};


    • Global blocks (Within things)
    global {/*code block*/};
    ***this creates a set of actions and variables that are accessible from the ThingType, without creating a Thing of that type.
  • Variables created this way are shared by all things of this type
  • Variables created this way are shared by all descendants (Unless changed by the descendant)
  • Variables and Actions created this way can only be changed (over-ridden) by ones inside of a global block, or they will fail

    email Dave if you need help!

    Highly complicated: JavaConnector interface

    JavaConnector
    initialize varname;
    connect varname to "package.classname";
    hook "action-name" to varname;
    send string-value to varname;
    send string-value to varname using ARGS ... ;
    send javaconnector-var to varname;
    send javaconnector-var to varname using ARGS ... ;
    sendvar regular-var to varname;
    sendvar regular-var to varname using ARGS ... ;
    getvar regular-var to varname;
    getvar regular-var to varname using ARGS ... ;

    **There exists a demonstration of javaconnector: a "widget" library**
    I will try to write some documentation for this shortly

    Debugging features
    dump;
    dump to dump-value;
  • dump-value can be "std_out", "error", "debug", or "java_err_out"

    • profile varname;
    profile varname to dump-value;
    profile action-name;
    profile action-name to dump-value;
    profile thing-type;
    profile thing-type to dump-value;
    benchmark using decimal-varname {/*code-block*/};
    ***if 'decimal-varname' is unassigned, it will be a decimal.
    ***if 'decimal-varname' is assigned, it needs to be a decimal.
    ***the result is a decimal representing seconds elapsed while running the code-block

    Attempt code-blocks
    attempt the following {Block of Code} and if it fails {Block of Code};
    try {Block of Code} catch {Block of Code};

  • If the entire statement inside the first code-block doesn't run, the second block runs

    • fail;
    fail with value;
  • to force a fail.

    • the mistake
  • dustyscript assigned error-code (see below)

    • what went wrong
  • represents the value assigned by a 'fail with' within the 'and if it fails' block
  • pseudo-code example follows:


    • attempt the following
    {
    do something
    do something else
    if some_status_is_bad {fail;};
    do another something
    finish this statement off
    }
    and if it fails
    {
    do something as a backup
    };

    Error catching with attempt blocks

  • Wrapping any statement in an 'attempt':'and..' block causes automatic error-catching
  • Dustyscript will assign 'the mistake' as one (or more) of the below 'error codes'
  • Dustyscript will assign 'what went wrong' as what would have been its error output
  • This automatic error catching is not a substitute for good programming!

    • The automatic 'attempt block' error codes
    SAY
    ASK
    ASSIGN
    COUNT
    IF

  • 'if' or 'as long as'
    IF-BLOCK
  • as yet unused, I think
    ACTION
    THING-TYPE
  • when creating a new 'thing type'
    THING
  • when creating a thing from a 'thing type'
    JAVA-CONNECTOR
  • any operations relating to the JavaConnector type


    Any questions, whatsoever, on javaconnector, things, complex 'if' statements, profiles, attempt, or any other Dustyscript feature should be posed to:
    The Dustyscript List

    The ConsoleDusty functions
    :q for quit
    :load>{filename} to load source
    :save>{filename} to save source
    :clear clears variable table, and source
    :code lists already executed statements
    :quiet turns non-error debugging off (or on, depending on current state)
    :l Lists the variables, and their values
    :run runs source in memory
    :r resets variable table, leaves source intact
    :? lists help
    :benchmark turns StatementProcessor's benchmark on (or off)

    Basic rules

  • Dustyscript requires a ; at the end of statements.
  • Bracketed statements should be followed with a ;
  • Re-assignment must be done with is now
  • Dustyscript does not accept a " character within ""

    • Sample "HelloWorld", Dustyscript style
    say "HelloWorld";

    Sample Dustyscript program
    say "Hello, World.";
    say "Who are you?";
    string s is ask;
    say "Hello, "+s+", how are you doing?";
    string a is ask;
    say "Wow, "+s+", I am glad you are doing "+a;
    say "Thanks for playing!";


    Special thanks to:
    Stephen Kolaroff (for JEPlite), William Alber(for optimization) and Stephen Blackheath(for mentoring)


    Please direct any questions or comments to Dave
    ~Xiarcel