QuadooScript

Download QuadooScript for Windows!

• QuadooScript Self-Installer (32-Bit)
• QuadooScript Self-Installer (64-Bit)
• QuadooScript Binaries (32-Bit)
• QuadooScript Binaries (64-Bit)

About QuadooScript

QuadooScript is a dynamically typed, high-level scripting language that tightly integrates into Windows applications and processes.  It has an easy-to-use syntax that will immediately be understood by anyone familiar with VBScript or JavaScript, or even anyone with a background with C.

The QuadooScript compiler and virtual machine are implemented using native C++ directly above Win32.  QuadooScript was designed and developed to be the definitive native Win32-based scripting language for Windows.

Why Choose QuadooScript?

If you're already using Windows, then you may choose to use QuadooScript if...

• You have a background in C, and you want a high-level scripting language with similar syntax.
• You want to parse and manipulate JSON data using a high-level scripting language.
• You want to write automation scripts in an environment similar to VBScript but with more modern features.
• You want to use a scripting language that is lighter weight than Python, or perhaps you simply don't like Python's syntax.
• You want to build a website (or back-end web services) for Classic ASP but want a larger feature set than what VBScript or JScript provided, including JSON requests and WebSockets support.
• You want to write batch/shell scripts with something like PowerShell but without the .NET overhead.
• You want to extend your native Windows application with an embedded scripting language that was built with native Windows development in mind.

Contents

• Getting Started
• Installing QuadooScript
• QuadooScript on Discord
• Syntax
• Values
• Operators
• Arrays
• Maps
• Functions
• Control Flow
• Variables
• Classes
• Operator Overloading
• Interfaces
• Fibers
• Intrinsics
• Error Handling
• Decorators
• Internal Objects
• JSON
• Host Methods
• Automation
• Windowed Environment
• Embedding API
• Native Objects
• ActiveScript and ASP
• WebSockets
• Delayed Timer Callbacks
• Web Services
• Scripts as Modules
• Compile to Executable
• Database Plug-in
• WinHttp Plug-in
• Basic Cryptography
• Capturing From Webcam

Getting Started

QuadooScript can be used in five different ways:

• As a stand-alone console application (QVM.exe)
• As an external script engine in a Common Gateway Interface (CGI) environment (via QVM.exe)
• As a host for scripts in a windowed environment (WQVM.exe)
• In an ActiveScript environment (ActiveQuadoo.dll)
• Embedded (QuadooVM.dll and, optionally, QuadooParser.dll)

Ultimately, no matter how QuadooScript is used, both QuadooParser.dll and QuadooVM.dll will be involved, although scripts can be compiled separately so that QuadooParser.dll is only used if a script needs to compile another script at run-time.  Embedded scripts can be pre-compiled so that the embedding host has no need to take a dependency on QuadooParser.dll.  Scripts can also be pre-compiled into executables.

QVM.exe is the stand-alone console application, and it supports several command line parameters:

• <first argument>
  The first command line argument always specifies the name of the script, unless QVM.exe is running in CGI mode.
• contenttype [content type]
  - The HTTP content type can be specified as a command line argument for debugging.
• query [query string]
  - The HTTP query string can be specified as a command line argument for debugging.
• cookies [cookie string]
  - The HTTP cookies can be specified as a command line argument for debugging.
• form [file path]
  - The HTTP form data can be specified using a path to a separate file containing the form data.  The format for the form data depends on the content type.
• usecgi [true/false]
  - Use this option to disable CGI mode (default is disabled).
• sandbox
  - Enables sandbox mode.  The Host, Request, and Response objects are not added to the global namespace of the VM.  The input, print and println intrinsics may still be used.
• m:name <module path>
  - Loads the specified module and assigns it to the global namespace under the provided name.  This is the only way to load external modules when using sandbox mode.
• args
  - All remaining command line arguments are passed to the script.

When not in CGI mode, the first command line argument specifies the script, which can also be a pre-compiled script if the the file has the .QBC extension.  All other script files are sent through the script parser, regardless of file extension (the preferred extension is .QUADOO).  When using CGI mode, the script file (either pre-compiled or script text) is obtained from the PATH_TRANSLATED environment variable.  Also, when using CGI mode, the content type, query string, and cookies are read from environment variables while the form data is read from the standard input handle.

When using WQVM.exe, only the -args parameter is understood.  WQVM.exe attempts to run a script's WinMain() function.  A script can define this function either as having no parameters or as having two parameters.  In the latter case, these are the strCmdLine and nCmdShow parameters, which are propagated to the script from the host's own WinMain() function.

When using ActiveQuadoo.dll in an ASP environment, the .ASP extension should still be used for server pages using QuadooScript.

Hello, Quadoo!

Before going further into the syntax, let's get the proverbial "Hello, World!" sample covered!

This is all that's needed to write text to the console.  Of course, QuadooScript can also be used in environments that do not write to consoles, but at least now you have seen one of the most basic programs.

Quadoo Studio

There is a basic IDE available for QuadooScript called Quadoo Studio.  It provides keyword highlighting and makes it easier to edit and test scripts for QVM.exe, WQVM.exe, and as web services via ActiveQuadoo.dll.

• Quadoo Studio (32-Bit)
• Quadoo Studio (64-Bit)

Installing QuadooScript

QuadooScript can be used to run scripts without installing it to any specific location or registering it with the system.

However, there are benefits to registering QuadooScript with the system, such as associating the .quadoo file extension with QVM.exe through the shell.

To perform a full installation of QuadooScript, start by creating a folder such as C:\Program Files (x86)\QuadooScript or C:\Program Files\QuadooScript and extracting everything from the 32-bit or 64-bit QuadooScript package to that folder.  From that folder, run QuadooInstaller.exe.  If successful, QuadooScript will be fully installed on the system, and it will appear in the system's list of installed programs.  QuadooScript also uninstalls itself using QuadooInstaller.exe, which can be invoked using the system's installed program list.

QuadooScript on Discord

QuadooScript has a group on Discord.  Follow this link to join the community.

There are channels specifically for:

• General Usage
• Web Development
• Embedding
• Using and Creating Modules

Syntax

QuadooScript's syntax is designed to be familiar to people coming from C-like languages while being a bit simpler and more streamlined.

Scripts can be stored in either plain text files with a .QUADOO extension or pre-compiled with a .QBC extension.  The syntax is easily parsed using a hand-written look-ahead Recursive Descent Parser (RDP).  Expressions are parsed using Pratt parser techniques.

Comments

Comments work in QuadooScript the same as in C and C++.  /* and */ omit the enclosed text from being parsed, and // causes all remaining text on the line to be ignored.

Reserved Words

The following are reserved keywords in QuadooScript:

Identifiers

Identifiers are used to name variables, functions, classes, namespaces, enums, and labels.  Identifiers are case sensitive and may not begin with numbers.  Underscores are permitted.

Line Endings

Statements in QuadooScript end with a semicolon.  Blocks of code do not need trailing semicolons, but class and enum definitions do require a semicolon at the end, while namespace definitions do not.

Blocks

Like C and C++, QuadooScript uses curly braces to define blocks of code.  A block of code can be used anywhere a statement is allowed, such as in control flow statements.  Function bodies are also blocks but can be written as a single statement without curly braces.

Namespaces

Namespaces provide a simple way to separate groups of functions, classes, and other namespaces by adding the namespace's name as part of the path required to access anything within that namespace by anything outside of it.  A dot is used to navigate between the components of a namespace path.

Enumerations

Enumeration values work similarly in QuadooScript as they do in C and C++, except that the name of the enumeration must be used to reference the values.

Values

Values are the built-in atomic object types that all other objects are composed of.  They can be created through literal values in script and expressions that evaluate to a value.  All simple values are immutable: once created, they do not change.  The number 3 is always the number 3.  The string "frozen" can never have its character array modified in place.  Objects, arrays, maps, JSON objects, and JSON arrays can all have their contents changed.

Booleans

A Boolean value in QuadooScript is represented by one of two values, true or false.  The literal keywords true and false are used to create a Boolean value.

Numbers

QuadooScript can manage numeric values using five different types:

• 32-bit integers
• 64-bit integers
• 32-bit floating point
• 64-bit floating point
• Four decimal place currency

At compile-time, QuadooScript automatically determines whether an integral literal is 32-bit or 64-bit.

In the example above, x is assigned a 32-bit value, while y is assigned a 64-bit value.  32-bit floating point values can be created with literals that are followed by an 'f' character.

In the example above, x is assigned a 64-bit double value, while y is assigned a 32-bit floating point value.

Currency values are 64-bit integers with four lossless decimal places.

Integers can be defined using three formats:

• Base 10
• Base 16 or Hexadecimal - numbers are prefixed with 0x
• Base 2 or Binary - numbers are prefixed with 0b

Strings

A string in QuadooScript is internally represented by a wide-string RSTRING value.  String literals are represented in script as zero or more characters enclosed in quotations.

QuadooScript supports escape sequences just like in C and C++.

Strings in QuadooScript cannot be modified, but array subscript syntax can be used to read from them just like in C.

In this example, nFirstChar would be set equal to the ASCII value of 'Q'.

QuadooScript accepts escaped character values in strings using the \uhhhh and \Uhhhhhhhh sequences where h denotes a hexadecimal digit.

When running QVM.exe under the Windows Terminal application, this is the output:

When working with large Unicode characters, there are differences between indexing a string directly as compared to using the asc and chr intrinsics.  For example:

Reading the first element directly returns exactly that element.  In this case, the value printed would be 55357.  The asc intrinsic understands the large Unicode values and will look for the rest of the value in the next element.  In this example, asc would return 128512.  That same value can be turned back into a string of two elements with chr(128512).

Literal Strings

QuadooScript has an additional way to define strings enclosed within #[ and ]# tags.  No escape sequences or other translations are considered when literal strings are parsed.  Line breaks are also preserved.  Literal strings can be used to include large blocks of text that contain quotation marks, such as JSON text, for example.

Null

QuadooScript has a special null value that serves as the default value of any variable that is otherwise uninitialized.  If you call a method that doesn't return anything and get its returned value, you get null back.  The null value evaluates to false when tested by an equality operator.

Void

QuadooScript has a special void variable type whose purpose is to hold pointers to opaque objects that scripts may need to pass between native modules and custom script hosts.

For example, a window handle in WQVM.exe is held in scripts as a void value.  Other hosts and native modules may manage some of their resources with void values too.

Scripts generally won't interact directly with these values, but they can be converted to strings and integers using casts.

void values can be used in equality tests just like other value types.  They can also be compared against each other.

Operators

QuadooScript supports the following operations on or between variables:

Arrays

Arrays in QuadooScript work similarly to arrays in other scripting languages, although all arrays in QuadooScript are dynamic array objects on the heap.  There are five ways to create an array in script syntax:

a0 is defined as a dynamic array without any slots initially allocated.  a1 has 10 slots initially allocated.  a2 is assigned a new array without any slots, while a3 is assigned a new array with 23 slots available.  a4 is assigned a new array sized to the data in the C-style data set.

Array Length

An array's length is retrieved using the len function.  Using the variables from above, len(a4) would return 6.

Getting and Setting Values

Array values are indexed using square brackets.

Inline Arrays

Array initialization lists can be defined inline and used as expressions.

In this example, 4 is assigned to v.

Array Methods

• Remove(n) - Removes slot n from the array.
• InsertAt(item, n) - Inserts item at index n.
• Append(item) - Appends item to the end of the array.
• Splice(nInsertAt, cRemove, aData) - Inserts the data held by aData beginning at position nInsertAt.  If cRemove is greater than zero, then that number of slots are removed from the array being modified (or are overwritten with data from aData).  aData can be either a regular array or a JSON array.
• Slice(nBegin [, nEnd]) - Returns a new array beginning with nBegin that runs through (but excluding) nEnd.  If only one argument is passed to Slice(), then the array's length is used.
• GetValue(n) - Returns the item at index n.
• SetValue(n, item) - Sets item into index n.
• Clear() - Removes all items from the array.
• Compact() - Reduces an array's allocation to match how many elements it is holding.
• Sort(oCallback) - Sorts the contents of the array by calling oCallback (function delegate or lambda) to compare the items.

Example of sorting an array:

Maps

A map in QuadooScript is an associative array.  It holds a set of entries, each of which maps a key to a value.

QuadooScript supports maps with these key types:

• Strings
• 32-bit integers
• 64-bit integers

A map is dynamically created using this syntax:

All three maps can associate keys with any type of value, but m0 only stores string keys, m1 only stores 32-bit integers for keys, and m2 only stores 64-bit integers for keys.

Map Length

A map's length is retrieved using the len() function.

Getting and Setting Values

Map keys and values are retrieved using this syntax:

Maps using string keys also support syntax like this:

Map Methods

• Has(key) - Returns true if the map contains key.  Returns false is the map does not contain key.
• Remove(key) - Removes the pair matching key or throws an exception.
• Find(key) - Returns the items specified by key or throws an exception.
• GetKey(n) - Returns the key at slot n.  An exception is thrown if the index is invalid.
• Add(key, item) - Adds or updates the value at key.
• MultiAdd(key, item) - Adds the item if they key hasn't already been used.  If it has, then an array is used to contain all items under the key.
• GetValue(n) - Returns the item at index n.
• SetValue(n, item) - Sets item into index n.
• Clear() - Removes all items from the map.

Functions

Functions in QuadooScript begin with the "function" keyword, followed by the function's name and finally a list of function parameters.  A function can either explicitly return a value, or the compiler will insert a "return null" instruction at the end of the function.

Execution in a script always begins with the main function.

QuadooScript allows functions to be called directly by name or by using indirect references (like a function pointer).  For example:

Function references can only be created on static functions.

Most functions in QuadooScript will only return one value using the return keyword, but function arguments that are local variables can be passed by reference to functions, allowing the called function to pass data back to the caller through the function parameters.

Partial Functions

QuadooScript allows functions to be constructed incrementally throughout the source files that are compiled together.

Internally, at the parsing level, the partial functions are stitched together into a single function.  The first partial function defines the parameters, if any.  Later extensions to the partial function must either redefine the same parameter list or omit the list.  For example:

Lambda Functions

QuadooScript supports lambda functions using the new keyword.

NOTE: The Host object is part of QVM.exe and ActiveQuadoo.dll, rather than part of the language itself.

In this example, a lambda function is created and assigned to oTest.  When it runs, it also creates another lambda function and assigns it to oInner.  Also, when the second lambda is created, it inherits the value of x from the first lambda.

Internally, a lambda function is an object, and inherited values are stored as member variables on that object.

QuadooScript also allows lambda functions to name the function.

While this syntax does create a lambda function that can be called anonymously, since the function is named, it can also be called by name.

Arrow Functions

QuadooScript supports an alternative syntax for lambda functions known as arrow functions.

An arrow function is defined by the presence of the => operator.  The function parameter list is on the left, and the function body, which may be a single expression, is on the right side.  If an arrow function receives only one argument, then its parameter's name does not need to be enclosed in parentheses.  If the arrow function has no parameters, or more than one parameter, then a pair of parentheses must be used.

Arrow function definitions are expressions and can be used anywhere an expression would be accepted, including as an argument to another function.

Tail Call Optimization

QuadooScript can optimize tail calls for functions and non-virtual class methods.  The optimization replaces the calling function's stack frame with the called function's stack frame.  This means the stack will not grow recursively.  This optimization is only considered when a return statement's expression is an eligible function call (global function, static method, or non-virtual class method from the same class).

Control Flow

Control flow is used to determine which chunks of code are executed and how many times.  Branching statements and expressions decide whether or not to execute some code and looping ones execute something more than once.

Truth

All control flow is based on deciding whether or not to do something.  This decision depends on some expression's value.

• The value false evaluates to false.
• The value null evaluates to false.
• 0, 0.0f, 0.0, and $0.0 evaluate to false.
• All other values evaluate to true.

To test whether strings, arrays, and maps are empty, you can use the isempty() intrinsic function.  isempty() returns true for null and empty strings, arrays, and maps.  It returns false for strings, arrays, and maps that have at least one element.  For all other values, an exception is thrown.

If Statements

The simplest branching statement, if lets you conditionally skip a chunk of code.  It looks like this:

That evaluates the parenthesized expression after if.  If it's true, then the statement after the condition is evaluated.  Otherwise it is skipped.  Instead of a statement, a block may be used:

An else branch can also be included.  It will be executed if the condition is false:

And, of course, it can take a block too:

Logical Operators

The && operator evaluates the left-side expression first.  If it is true, only then is the right-side expression evaluated.  Otherwise, the right-side expression is never evaluated.

The || operator evaluates the left-side expression first.  If it is true, the right-side expression is not evaluated.  The right-side expression is only evaluated when the left-side expression is false.

The Conditional Operator ? :

The conditional operator works just like in C and C++.

Do/While Statements

Like C and C++, the distinction is when the expression is evaluated.  A do loop always executes the loop code at least once, but a while loop may not execute its loop code at all.

For Statements

The for loop works similarly in QuadooScript as it does in C.  Three code fragments, separated by semicolons, are expected.  The first fragment is an initializer, which can either be an assignment or a variable declaration.  The second fragment is the expression for continuing the loop.  The third segment is an expression to be executed at the end of each loop iteration.

Any or all of the three code segments may be empty.  For example, infinite loops may be expressed with this syntax:

Break Statements

The break statement works the same as in C and C++.  Put a break statement in a loop to immediately jump from that point to just outside the loop.

goto

The goto keyword can be used to jump to a label (a word followed by a colon) that is in the same scope or in a parent scope.  The script cannot jump into child scopes using the goto keyword.

Variables

Variables are named slots for storing values.  New variables are declared using this syntax:

Like JavaScript, but unlike VBScript, variables can be declared and initialized on the same line.

In the example above, variable x's value is null.

QuadooScript also allows variables to be declared and initialized using the value types.  For example:

Since QuadooScript is a dynamically typed language, these "types" are meaningless if other values are later assigned to these variables.  However, without explicitly initializing them in script, the default values of each type are automatically assigned at compile-time since the types are specified.  Therefore, values a, b, and c are automatically initialized to 0, instead of null.  Variable d is initialized to a 64-bit value of 0, and so on.

Type Casting

The value types can also be used to cast a variable of one type into another type.  For example:

Scope

A local variable in QuadooScript always exists until the end of the block in which it was defined.  Static variables can be referenced from other scopes of code.  For either, QuadooScript searches up the scope stack to find a variable.

Assignment

After a variable has been declared, you can assign to it using =:

An assignment walks up the scope stack to find where the named variable is declared.

When used in a larger expression, an assignment expression evaluates to the assigned value.

External Variables

The extern keyword can be used to create a variable (at the scope where it's used) that loads an external object having the same name.  For example:

After this line of code, a variable called Host can be used that is loaded with an external object called Host.  It's always more performant to load from a variable than to look up a named object.

Variable Types

A variable's type can be retrieved using the typeof intrinsic.

The type can be checked against a predefined set of enumeration values:

• QVType.Null
• QVType.Bool
• QVType.Int
• QVType.Long
• QVType.Float
• QVType.Double
• QVType.Currency
• QVType.String
• QVType.Array
• QVType.Map
• QVType.Object
• QVType.JSONArray
• QVType.JSONObject
• QVType.Ref
• QVType.Void

Classes

Classes work in QuadooScript about the same as they do in VBScript, except they use syntax that is more like C++.

Classes are defined using the class keyword.

Class Lifetime Management

Class instances are created by using the new keyword.

Class instances are reference counted, although this detail is invisible to a QuadooScript programmer.  When a variable holding a class instance goes out of scope, the class instance's reference count is decremented.  When a class's reference count reaches zero, the class's destructor (if any) runs, and then the instance is removed from memory.

Constructors and Destructors

Classes in QuadooScript can optionally have a constructor and/or a destructor.  The constructor is a special class method that runs as part of the object's creation.  Likewise, the destructor is a special class method that runs just before the object is deleted from memory.  Both constructors and destructors have the same name of the class, but the destructor's name is prepended with a tilde character.

QuadooScript allows classes to have multiple constructors as long as each constructor has a unique number of parameters.

The example class above can be instantiated using any of its three constructors.

Member variables

Any variable declared in a class but outside any class method becomes a member variable.  Class member variables can be made static using the static keyword.

Static class member variables can be accessed from outside the class, but non-static class member variables are only accessible to non-static class methods unless they're marked with the property keyword (see below).

Class Methods

All class methods are publicly available.

Class methods can also be static.  Static class methods can be accessed by treating the name of the class as a namespace.

Properties

QuadooScript supports special syntax for exposing properties on objects.

QuadooScript also supports indexed properties for classes.

A property can simultaneously support both regular and indexed getters and setters.

Properties can also be accessed dynamically using the get and set keywords in expressions.  Using the example class from above, then the properties can also be accessed as follows:

Properties can be created automatically from member variables by marking them with the "property" keyword.

When this is done, the proprty can be accessed externally by the same name as the member variable.

this

A class method can reference its own class member variables using the this keyword.  A class instance can also pass a reference to itself to another function by passing this as an expression.

Inheritance

QuadooScript classes support single class inheritance.  This means that a class can inherit members and methods from another class.  However, a class cannot simultaneously inherit from two base classes.

If a base class defines a constructor that has parameters, then a super class must also provide a constructor that calls the base class constructor.  However, the super class constructor's signature does not have to match the base class constructor.

Virtual Methods

Methods on classes can be marked virtual or pure virtual.  Methods marked with the "virtual" keyword are called by name, instead of by ordinal, so that super classes can override base class behaviors.  Pure virtual methods are like virtual methods but are unimplemented in base classes and must be implemented in super classes.

In the example above, the CAnimal base class defines a GetType() method but leaves the implementation to the super class CGiraffe.

Method Delegates

Just as global functions can be wrapped into objects, non-static class methods can also be assigned as objects.  In this case, they are called method delegates.

In the example above, delegates are created for two non-static class methods.  Once created, they're callable just like global function references.  Internally, they maintain an object reference and the code pointer for the class method.  When invoked, the code pointer is updated directly without doing a name lookup.

Virtual class methods may be assigned as delegates, but pure virtual methods may not.  This is because a specific function is picked at compile-time.  In the above example, a path to a method in a base class picks the base class method, even if it had an override in the subclass.

Class method delegates may only be assigned from non-static class methods of the class for which the delegates are being created.  This allows both the class's this pointer to be available as well as type information for ensuring valid delegates are being created.

delete

QuadooScript supports a delete keyword that works on classes (objects), arrays, maps, JSON objects, and JSON arrays.

When using delete on a QuadooScript class, the class's delete handler function is called.  In the example above, when the DeleteMore() method is compiled, QuadooScript knows it's being compiled as a class method, so when it sees delete "more" without a left-hand expression, it pushes this onto the stack so that the calling object's delete handler is invoked.

The delete keyword can be used as an expression.  It returns true if successful or false if unsuccessful.

When using delete on an array, the index is specified, and that index is removed from the array.  When used on a map or JSON object, the named member is removed.

Default Properties and Methods

QuadooScript classes can specify a member variable for receiving unhandled methods and properties.

In this example, an unhandled property access will be forwarded to the m_oProps member, and an unhandled method call will be forwarded to the m_oMethods member.  In each case, the member is expected to be an object.  Any other data type will result in a runtime exception.

Operator Overloading

QuadooScript supports basic operator overloading for classes.  Just like C++, the overloaded operators are defined using the operator keyword.

In the example above, the neg operator is invoked when applying a unary negation to the object, and the dup operator is invoked when applying the post-increment operator (the original object must be duplicated before it can be "incremented").

Most operators will perform some kind of operation and return a new object, leaving the original object unmodified.  The unary increment and decrement operators modify the original object and also return a new object.

Interfaces

QuadooScript supports interfaces, similar to those in C++, for defining abstract coding interfaces.  Classes inherit from interfaces and must implement the interface methods before they can be instantiated.  Interfaces can also inherit from other interfaces, and classes and interfaces can inherit from multiple interfaces.

To define an interface, the interface keyword is used.

The methods of an interface must be defined as pure virtual, like they would be in C++.

The full benefit to using QuadooScript interfaces is derived when embedding the VM into a larger application because the interfaces provide a fast mechanism for the host to call script methods.  The IQuadooObject interface has a GetInterface() method that queries the object for the specified interface.  The name of the interface is the same name that is used in the script.  If a requested interface is found, it is returned to the caller as an IQuadooInterface object.

The native IQuadooInterface interface has two methods:

• Invoke - Calls the script method by its ordinal.
• ResolveMethod - Resolves a method's ordinal from its name.

Method ordinals begin from zero.  Interfaces that have base interfaces always include the base interface methods first, in the order in which they're defined in script.  A code generator could simultaneously define interface definitions for QuadooScript and constants for native code.  At run-time, a larger application embedding the QuadooScript VM could retrieve interfaces from objects and call methods using code-generated constants.  In this way, no name lookups would ever be necessary.

Interfaces may also be called by scripts, giving scripts a fast way to call into native objects.  Using the sample interface above, the following shows how a script could call interface methods (on either a native or script-based interface):

While the above example works, it is important to remember that a name lookup must occur for every interface method call.  For situations where it would make sense to resolve the name once and use the ordinal for every call (such as in a loop), there is also a way to obtain an object wrapping a specific interface method:

When the method is referenced like a property (no parentheses), a new object wrapping that interface method is returned.  When the returned object is invoked like a nameless method, the interface method's cached ordinal is used to make the method call.

While this syntax works for both native and script-based interfaces, it will usually be less expensive for scripts to call methods on script-based objects directly rather than by using their implemented interfaces.  However, this syntax is the only way for scripts to call interface methods on native objects (assuming the interface methods aren't also exposed through the IQuadooObject implementation).

Fibers

Fibers are like coroutines, which can be thought of as cooperatively scheduled threads.  Fibers wrap either a global function or a lambda, and they have separate call stacks from the caller.  Code that is running within a fiber can yield control back to the caller by suspending itself.  A fiber remembers its state (call stack and instruction pointer) until the fiber is called again.  At that point, the fiber resumes running immediately after the original yield call.  When the last function running within a fiber exits, the fiber's call stack is deallocated.

In this example, a fiber is created using a lambda.  In the do loop, the fiber is started on the first iteration of the loop.  Subsequent iterations resume the fiber.  With each call to the fiber, the fiber runs until it calls the yield() intrinsic.  The fiber returns a JSON object through the yield() intrinsic, and the caller retrieves the value as the return value from the fiber.

Fibers support these properties:

• Active - Returns true if the fiber is allocated, false if it is not allocated.
• Running - Returns true if the fiber is running, false if it is not.

When a fiber's last running function exits, the fiber's call stack is deallocated.  If the fiber is called again, it is restarted, and a new call stack is created.

Yielding and Resuming

The yield() intrinsic can be used with or without a single argument.  If an argument is passed, then the caller receives the value.  When calling the fiber to resume it, either no arguments can be passed, or a single argument can be passed.  If one argument is passed, then the yield() call in the fiber returns the passed value.

Intrinsics

QuadooScript has a number of built-in instructions that appear as functions in script but are actually their own double byte-code instructions.  One byte-code instruction specifies the INTRINSIC (value 0xFE) instruction, while the second byte-code instruction specifies which intrinsic to execute.

Error Handling

QuadooScript exposes runtime errors to the script as exceptions.  QuadooScript supports exceptions using syntax that is similar to C++.

Scripts can also catch the error code from the exception.

The script can also use the throw keyword to generate an exception or to re-throw a caught exception.

The exception itself is an object that exposes information about the exception.  The Value property returns the value that was thrown.  The following properties are available:

• IP - This is the instruction pointer for the instruction that threw the exception.
• File - This is the name of the script file (if available) that threw the exception.
• Line - This is the line number from the original sources that threw the exception.
• Value - This is the value that was thrown by the script.

Exception objects also support a ToString() method that returns a human-readable string containing all the information about the exception.

QuadooScript supports an additional way to catch and handle exceptions using the catch keyword that returns a caught exception to the caller.

In the example above, catch is used as an inline expression, and its return value is the exception object (or null if there is no exception).  Program execution continues without any jumping to separate exception handlers.  If the exception is not needed at all, then the return value may be discarded immediately:

Decorators

QuadooScript supports function decorators for modifying the behaviors of functions using the @ operator.  When a decorator is specified, the original function is compiled under a modified name, and a new function is generated with the original function name.  The generated function passes a delegate of the original code to the decorator function.

When the Test() function is called, the decorator function receives a delegate to the original code.  Decorators always receive a delegate parameter, but the rest of the parameter list must match the parameter list of the function being decorated.  This could be zero or more parameters (in addition to the delegate parameter, which is always at the beginning).

Decorators can also be used with class methods.

Internal Objects

The QuadooScript VM has several internal objects.

Array

Arrays are a native variable type that have the following methods:

• Remove
• InsertAt
• Append
• Splice
• Slice
• GetValue
• SetValue
• Clear

Binary

The binary object is used to manage a blob of binary data.  Internally, the binary object implements the ILockableStream interface, so the data isn't meant to be extended.  The data could come from a file or from an external object, for example.  Several methods are available to support data extraction:

• ToBase64
• ToByteArray
• ReadString
• ReadUTF8
• ReadANSI
• ReadByte
• ReadInt16
• ReadInt32
• Clone

The binary object has two read/write properties:

• ContentType
• FileName

The binary object has a read-only property called Size that returns the length, in bytes, of the managed binary data.  The binary object also has one indexed property called Data.  This property also allows the binary data to be modified in-place.

Date

The date object is used to manage a date/time value.  It has the following methods:

• AddYears
• AddMonths
• AddDays
• AddHours
• AddMinutes
• AddSeconds
• AddMilliseconds
• ToLocalTime
• ToSystemTime
• ToString
• To12Hour
• To12HourTime
• ToISO8601
• ToDouble
• GetTimeUntil
• GetTimeUntilMS

The following properties are available:

• Value
• Year
• Month
• Day
• Hour
• Minute
• Second
• Millisecond
• DayOfWeek (Read-Only)

The date object supports the default value mechanism.  Invoking the default value is the same as calling ToString().

Event

The event object is a wrapper around the OS event.  It is created using the event() intrinsic function, which requires two arguments: name (null is allowed) and a manual reset boolean.  The following methos are supported:

• Set() - Sets the event.
• Reset() - Resets the event.
• Wait(msTimeout) - Waits on the event.  Returns true when the event becomes set.  Returns false if the timeout occurs.  The timeout argument is optional.
• Pulse() - Pulses the event.

An event instance can be passed to the wait() and waitall() intrinsic functions.

Event Source

The event source object manages event subscriptions.  It has the following methods:

• Fire (variable argument list)
• Subscribe
• Unsubscribe
• Clear
• SetMethod
• ClearMethod

The arguments passed to Fire() are passed to the subscribed sinks.  Zero or more arguments may be passed.  If any other method name is called, that method name is used as the method to call into the subscribed objects.  Normal objects, global functions, and lambdas may be used as sinks.

Fiber

Fibers are objects that maintain their own call stacks and can be suspended and resumed.  They have two properties:

• Active
• Running

Map

Maps are a native variable type that have the following methods:

• Has
• Remove
• Find
• GetKey
• Add
• GetValue
• SetValue
• Clear

Mutex

Mutex objects have the following methods:

• Acquire
• Release

Mutex objects also have one read/write property: Owned.

StringBuilder

StringBuilder objects have the following methods:

• Append(vData)
• AppendChar(ch)
• AppendChar(ch, cch)
• AppendOffset(strSource, idxSourceStart)
• AppendOffset(strSource, idxSourceStart, cchCopy)
• AppendJoin(oData, strSeparator)
• Insert(idxInsert, strInsert)
• Clear()
• CopyTo(strSource, idxCopyTo)
• ToString()
• TruncateLeft(cchLeft)
• TruncateRight(cchRight)
• Substring(idxStart, cchRun)
• Set(ch, idxStart, cchSet)
• Reverse()
• FormatString(strFormatString, ...) - Formats into the builder using the format string and variable argument list and returns a new string from the builder.
• Format(strFormatString, ...) - Formats into the builder using the format string and variable argument list and returns the builder object for method chaining.
• Find(strText) - Returns the index of the first occurrence of strText or -1 if not found.
• FindR(strText) - Returns the index of the last occurrence of strText or -1 if not found.

The following properties are available:

• Length (Read-Only)
• Capacity

StringList

StringList objects have the following methods:

• IndexOf
• Add
• Insert
• Remove
• Join
• Copy
• Compare
• Clone
• Clear
• Compact

The following properties are available:

• Count (Read-Only)
• Strings - Returns the array view of the string list

JSON

QuadooScript supports JSON natively.  In fact, JSON functionality is one of QuadooScript's biggest strengths, and one of the primary motivations for creating QuadooScript was to integrate the JSON library into a scripting environment.

JSON objects and JSON arrays are primitives in QuadooScript.  Fields of JSON objects can be referenced just like fields of regular QuadooScript objects, and JSON array elements can be referenced just like regular QuadooScript arrays.  Strings, Booleans, and integers are passed directly in and out of JSON objects and JSON arrays without any conversion necessary.  The string objects used by QuadooScript are the same string objects used by the JSON library.

The following JSON functions are supported:

• JSONParse(json_text) - Parses the provided JSON text and returns a native value, which can also be a JSON object or JSON array.
• JSONGetObject(root, path, ensure_exists) - Retrieves the object from the root object, given the provided path, and optionally creates the object if it doesn't already exist.
• JSONGetValue(root, path) - Retrieves any value from the root object, given the path to the value.
• JSONSetValue(root, path, value) - Sets the specified value into the root object, given the path to the new value.
• JSONRemoveValue(root, path) - Removes and returns the value from the root object, given the path to the value to be removed.
• JSONCreateObject() - Creates and returns a new JSON object.
• JSONMergeObject(target, source) - Merges the source object into the target object.
• JSONAddFromObject(target_object, target_field, source_object, source_field [, options]) - Copies a value from the source JSON object to the target JSON object, without translation between JSON and QuadooScript types.  The optional "options" parameter defaults to required (optional is 1), allows null (not null is 2), and overwrite existing (no overwrite is 4).
• JSONClone(value, deep_clone) - Clones the JSON value as a shallow or deep copy.
• JSONFormat(json_text) - Reformats the provided JSON text using line breaks and indentation.

JSON objects support the following methods:

• Has(name) - Returns true if the named item exists, false if not.
• Remove(name) - Removes the named item from the object.
• Find(name) - Returns the named item from the object.  If the named item is not in the object, then null is returned.
• FindThrow(name) - Like Find() but throws an exception if the named item is not in the object.
• GetKey(index) - Returns the name of the item at the provided index.
• GetValue(index) - Returns the indexed item from the object.
• SetValue(index, v) - Sets item v into the provided index.
• Add(name, v) - Adds item v to the object with the provided name.

JSON arrays support the following methods:

• Remove(index) - Removes the index item from the array.
• Find(field, value) - Finds the item in the array where the named field has the provided value.  The items in the array must be objects.  If found, the index is returned.  Otherwise, -1 is returned.
• Find(value) - Finds the value in the array.  If found, the index is returned.  Otherwise, -1 is returned.
• FindThrow() - Like Find() (either parameter list) but throws an exception if the item isn't found.
• FindObject(field, value) - Finds the item in the array where the named field has the provided value.  The items in the array must be objects.  If found, the object is returned.  Otherwise, null is returned.
• FindObjectThrow(field, value) - Like FindObject() but throws an exception is the item isn't found.
• GetValue(index) - Returns the indexed item from the array.
• SetValue(index, v) - Sets item v into the provided index.
• InsertAt(v, index) - Inserts item v to the new index.  Existing items at and beyond that index are pushed one index further into the array.
• Append(v) - Appends item v to the end of the array.
• Clear() - Removes all items from the array.
• Compact() - Reduces an array's allocation to match how many elements it is holding.
• Sort(oCallback) - Sorts the contents of the array by calling oCallback (function delegate or lambda) to compare the items.

Finding a JSON Object in a JSON Array

The following example demonstrates two ways to find a JSON object from within a JSON array.

Finding an object using a JSON path

JSON paths can be used to find specific objects buried within deep JSON data trees.

In this example, the value 45 will be printed.  The JSON path parser uses the same token set as the main JSON parser, so it still uses square brackets to denote arrays, and it uses colons to separate fields.  Arrays can be referenced using either an absolute index or a name and value pair.

More information on using the path parsing APIs is on the JSON page.

The cryptography section includes an example of using JSON to build and validate JSON Web Tokens.

Host Methods

While not technically part of the QuadooScript language itself, QVM.exe adds a Host object into the global namespace to let scripts interact with the external environment and file system.  These are the methods available on the Host object:

• Args() - Returns the command line argument array.
• Args(n) - Returns argument n from the command line argument array.
• ReadArg(n, vDefault) - Returns argument n or vDefault if n would have been an invalid index.
• FindParam(strParam) - Returns the argument index of strParam from the argument list or 0 if not found.
• FindParamValue(strParam) - Returns the next argument following strParam, if found, from the argument list.  Throws an exception on error.
• OpenStdInPipe() - Returns a pipe opened on STD_INPUT_HANDLE.
• OpenStdOutPipe() - Returns a pipe opened on STD_OUTPUT_HANDLE.
• OpenStdErrorPipe() - Returns a pipe opened on STD_ERROR_HANDLE.
• Write(strText) - Writes strText (converts to CP_ACP first) to STD_OUTPUT_HANDLE.
• WriteLn(strText) - Does the same as Write() but adds "\r\n" to the output stream.
• WriteTextFile(strText, strFile) - Writes strText (converts to CP_UTF8 first) to strFile.  The UTF-8 BOM is written first.
• WriteBinaryFile(oData, strFile) - Writes the file data (needs to be a file object) contained by oData to strFile.
• WriteAsciiFile(strText, strFile) - Writes strText (converts to CP_ACP first) to strFile.  No BOM is written.
• ReadTextFile(strFile) - Reads strFile as a text file and returns the text.  Conversions from ASCII and UTF-8 are supported.
• ReadBinaryFile(strFile) - Reads strFile as a binary file and returns a binary file object.
• GetEnv(strName) - Reads the environment variable specified as strName or returns an empty string.
• SetEnv(strName, strValue) - Writes the environment variable and provided string data.
• MapPath(strPath) - Creates an absolute path using strPath as a relative path from the script's path (non-CGI mode) or using the "PATH_INFO" environment variable (CGI mode).
• OpenFolder() - Returns a folder object that is equivalent to calling OpenFolder(MapPath("/")).
• OpenFolder(strPath) - Returns a folder object for strPath.
• OpenResources(vModule) - Returns a resources object for vModule, which can be either a string path or null for the current process module.
• OpenLineReader(strPath) - Returns a line reader object for reading lines from the text file specified by strPath.
• Find(strQuery) - Returns a query object for the file path query specified.  Throws an exception if there are no files or folders to return.
• FindChanges(strPath, fWatchSubtree, nNotifyFilter) - Returns a file/folder change notification object.  The wait() function can be used on the returned object.
• CreateProcess(strFile, strCmdLine) - Returns a process object if a process can be created using strFile and strCmdLine.
• CreateProcess(strFile, strCmdLine, strCurrentFolder) - Returns a process object using the specified current folder.
• CreateProcess(strFile, strCmdLine, oInput, oOutput, oError) - Returns a process object using custom redirection pipes.
• CreateProcess(strFile, strCmdLine, strCurrentFolder, oInput, oOutput, oError) - Returns a process object using a specified current folder and custom redirection pipes.
• CreateObject(strName) - Returns a native IQuadooObject (if available) or a wrapped ActiveX control (supporting IDispatch) using COM.  The object has to be registered under strName in the registry.
• CreatePipe() - Returns an anonymous, bidirectional pipe object.
• CreateWriteFileAsPipe(strFile) - Opens strFile for writing and wraps it in a pipe object.
• CreateReadFileAsPipe(strFile) - Opens strFile for reading and wraps it in a pipe object.
• CreateBinary([strFileName,] vBytes) - If vBytes is an integer, then creates an empty binary object with a size of (int)vBytes bytes or, if vBytes is a string, then converts the string to UTF-8 and returns the data as a binary object.  Optionally, the object can also be initialized with a file name.
• ParseDate(strDate) - Attempts to read a date and/or time in "m/d/y h:m:s" format and return a date object.  If null is passed, then an empty date object is returned.
• ParseDate(nDate) - Returns a date object from a 64-bit integer value.
• ParseDate(dblDate) - Returns a date object from a 64-bit floating-point value.
• FileFromBase64(strFile, strBase64) - Decodes strBase64 and returns a binary file (with the name set to strFile) object from the decoded text.
• FileFromBase64Url(strFile, strBase64Url) - Decodes strBase64Url and returns a binary file (with the name set to strFile) object from the decoded text.
• FileFromHex(strFile, strHex) - Decodes strHex and returns a binary file (with the name set to strFile) object from the decoded text.
• FileFromByteArray(strFile, aData) - Treats aData as an array of bytes and returns a binary file (with the name set to strFile) object from the byte data.
• ResolvePath(strBase, strRelative) - Returns an absolute path built by combining strRelative with strBase.
• LoadQuadoo(strModule [, strClassGuid]) - Loads either an external object (a DLL that implements CreateObject()) or a pre-compiled QuadooScript (.QBC) file.
• GetActiveObject(strName) - Returns a wrapped ActiveX control (supporting IDispatch) using COM.  The object has to be registered under strName in the ROT.
• GetComponent(strComponent) - Returns a wrapped ActiveX control (supporting IDispatch) using COM.  The object created is provided by an ActiveX component described by the strComponent parameter.  This method is equivalent to VBScript's GetObject method.
• EnableCOM() - Enables COM inside of QVM.exe so that CreateObject() and GetActiveObject() can be used.  COM is unloaded automatically when the script ends.
• Compile(strFileRef, strScriptText, fPermissive, oBinaryRef) - Compiles the provided script text and returns the compiled QBC through the last parameter, which must be a ref variable.
• RegisterServer(strModule) - Registers the specified module with COM by calling its DllRegisterServer() method.
• UnregisterServer(strModule) - Unregisters the specified module with COM by calling its DllUnregisterServer() method.
• FileAppend(vData, strFile [, nCodePage]) - Appends vData (either a string or binary object) to strFile.  Uses nCodePage for strings.
• FileSearch(strName, [strSearchPath, cLevelsToRemove, ] fSearchPaths) - Searches the given path, including the system paths, for strName.  Parents of strSearchPath are searched based on the value of cLevelsToRemove.

The Host object also supports these properties:

• CurrentDirectory - Gets or sets the current directory of the script engine's process space.
• ConsoleTitle - Gets or sets the console window's title.
• NativeModule - Returns the path to the VM running the script.
• Args - Returns the array of arguments that were passed to the script.
• CodePage - Gets or sets the console's code page.
• WindowsDir - Returns the primary directory for the Windows installation.
• SystemDir - Returns the system directory for the Windows installation.

Script Directory vs. Current Directory

When working with QVM.exe or WQVM.exe, a script has access to the Host.CurrentDirectory property.  This property directly uses GetCurrentDirectory() and SetCurrentDirectory for managing the current working directory.  To open a folder object with the current working directory, a script would do this:

The current directory depends on the environment when the script is started, but the script's directory where the script itself resides is always the same.

The code above opens the same folder regardless of the current directory.

Find File Object

These methods are available:

• Next() - Returns true/false based on whether there was another file/folder.
• OpenFolder() - Returns a folder object for the current item if it's a folder.  If it's not a folder, then an exception is thrown.

These properties are available:

• Name
• Size
• IsFile
• IsFolder
• IsReadOnly
• Creation
• LastWrite
• Path
• Ext
• FullPath

Folder Object

These methods are available:

• ToString()
• Remove()
• AvailableSpace()
• TotalSize()
• TotalAvailable()
• Empty()
• CreateFolder(strRelativePath)
• MoveTo(oTargetFolder)
• MoveTo(strTargetFolder)
• DeleteFolder(strRelativePath)
• DeleteFile(strRelativeFile)
• OpenFolder(strRelativePath)
• Find(strRelativePath)
• IsFolder(strRelativePath)
• IsFile(strRelativePath)
• GetPathOf(strRelativePath)
• GetAttributes(strRelativePath)
• GetFileSize(strRelativePath)
• CopyFile(strRelativePath, strTargetPath)
• CopyHardLink(strRelativePath, strTargetPath)
• MoveFile(strRelativePath, strTargetPath)
• ReplaceFile(strRelativeExistingPath, strTargetPath)
• SetAttributes(strRelativePath, nAttributes)
• GetFileTime(strRelativePath, ref oCreation, ref oLastAccess, ref oLastWrite)
• SetFileTime(strRelativePath, oCreation, oLastAccess, oLastWrite)

The folder object also supports a read/write Path property.  When setting the property, the path must be an existing folder.

Resources

The Host.OpenResources(vModule) method returns a resources object for the specified module.  This object allows the script to query for and to load embedded resources from the executable module file.

• Load(vName, vType) - Returns a binary object containing the resource data.
• EnumTypes() - Returns an array of the enumerated resource types.
• EnumNames(vType) - Returns a JSON array of objects, each containing the name and type of the enumerated resources.

The vName and vType variables can specify either a string or an integer.  Enumerated names and types can also be either strings or integers.

Running System Commands

While there is no equivalent to the system() function in QVM.exe, its functionality can be recreated in a variety of ways depending on the behaviors needed.

The following can be used to run a system command with a specified starting directory and to wait for the command to complete:

If the system command's return value is desired, the following may be sufficient:

In both examples, the caller may set the strStartDirectory parameter to null if the starting directory is not important.

Automation

Given everything that exists on the Host object, you shouldn't be surprised to learn that QuadooScript is a great language choice for building automation scripts such as build scripts and packaging scripts.  Instead of writing batch files, for example, QuadooScript can be used as a scripting alternative.  A QuadooScript installation is substantially smaller than Python too.  Finally, unless you have requirements that specifically depend on the .NET framework, then QuadooScript could also be a better choice than PowerShell.

There are a variety of ways that "DOS" (system) commands can be invoked using QuadooScript (from QVM.exe or WQVM.exe).  In addition to the ShellCmd() and ShellCmdResult() examples from the system commands section, other reusable functions can be constructed to launch (and wait for) external utilities.

The previous examples create processes that attach to the same pipes used by the calling process.  Of course, it's also possible to attach custom pipes to a child process.

There is also nothing stopping QuadooScript from providing a custom pipe to a child process as its output pipe and then reading the output from a child process.  In that case, a script would read from the pipe using the Read(cbBytes) method.

The QuadooScript package contains a simple module for handling ZIP files.  Scripts that need to build ZIP files can use the QSZIP.dll module to write files into ZIP files.

The 32-bit and 64-bit QuadooScript packages are built by an automation script.

Windowed Environment

Whereas QVM.exe operates in console mode, WQVM.exe runs in a windowed environment.  When WQVM.exe runs, Windows internally calls its WinMain() function.  In turn, a script's WinMain function is also called.  However, if WinMain() does not exist, then a script's main() function is called instead.

A script can define WinMain() in one of two ways:

Host Object

Like in the console version, WQVM.exe also provides a Host object.  However, not all methods are available, and some methods are unique to the windowed environment.

Under WQVM.exe, the following Host methods are unavailable: OpenStdInPipe(), OpenStdOutPipe(), and OpenStdErrorPipe().  The ConsoleTitle and CodePage properties are also unavailable.

Five methods are unique to the WQVM.exe Host object:

• MessageBox(hwnd, strText, strCaption, nType)
• MessageBeep(nType)
• Quit(nValue)
• Execute(hwnd, strOperation, strFile, strParameters, strDirectory, nShowCmd)
• CreateMessagePump()
• ShellLink(strPath, strStartDir, strArgs, strLinkFile, strIcon, idxIcon, nCmdShow, strDesc)

The Quit() method posts WM_QUIT with the provided value to the message queue.

The Execute() method is a thin wrapper for the ShellExecute() function in Windows.

Two properties are unique to the WQVM.exe Host object:

• Windows - Returns an interface for the windowed environment of Windows
• Pump - Returns the active message pump object or null if there isn't one

Windows Object

The Host.Windows property has these methods:

• EnumWindows()
• EnumChildWindows(hwnd)
• EnumThreadWindows(idThread)
• SendMessage(hwnd, nMsg, wParam, lParam)
• SendMouseWheel(x, y, oData)
• SendMouseDown(x, y, oData)
• SendMouseUp(x, y, oData)
• SendMouseMove(x, y, oData)
• SendKeyDown(nKey)
• SendKeyUp(nKey)
• SendCopyData(hwnd, nData, vData) - vData must either be a string or be a binary data object
• PostMessage(hwnd, nMsg, wParam, lParam)
• FindWindow(strClass, strName)
• GetWindowText(hwnd)
• GetWindowClass(hwnd)
• GetFocus()
• GetForegroundWindow()
• GetCapture()
• GetWindowRect()
• GetDesktopWindow()
• GetCursorPos()
• GetScreenSize()
• SetFocus(hwnd)
• SetForegroundWindow(hwnd)
• SetCursorPos(x, y)
• IsWindow(hwnd)
• IsWindowVisible(hwnd)
• IsZoomed(hwnd)
• IsIconic(hwnd)
• FromPoint(x, y)

Message Pump

WQVM.exe provides a standard message pump object, via Host.CreateMessagePump(), for QuadooScript scripts running in a windowed environment.  It has the following methods:

• Run()
• End([nValue])
• AddHandler(oHandler)
• RemoveHandler(oHandler)

The message pump object also has a Task property that can set (or cleared by passing null) a task object that runs a callback method when there are no messages being pumped.  Reading the property simply returns true/false based on whether there is a task set.

The Run() method runs the message pump either until WM_QUIT is received or until End() is called.  The value passed to End() or received with WM_QUIT is returned to the original caller.  When Run() is called, that message pump becomes the active message pump, and it can also be accessed using the Host.Pump property.  There is only one active message pump.  If another message pump becomes active, then it remembers the previously active message pump and reactivates it when the current message pump exits.

Tasks and message handlers are both designed to be implemented by native code but can be passed to the message pump by scripts as QuadooScript objects.  The message handlers decide whether the messages should still be passed onto the remaining handlers and ultimately to the translation and dispatch part of the pump.  Native code could implement message handlers using IsDialogMessage(), using accelerators, or with any other message handling logic.  A message handler returns TRUE to prevent additional processing of the message.

WQVM.exe does not provide window creation or GUI elements beyond the message box.  QuadooScript plug-ins should be used to provide additional graphical and windowing functionality.  However, plug-ins are encouraged to leverage the standard message pump using the published interfaces from WQVMInterfaces.h.

If a native plug-in wants finer control of the message pump, then it should implement its own loop, but it can still leverage the standard message pump object by implementing the IQVMMessagePumpController interface.  When the native plug-in's code calls IQVMMessagePump::UseController() to set itself as the pump's controller, then the standard message pump still becomes the active pump, and its End() method may still be used to set the result and notify the message pump's controller that it should exit.  Additionally, a controller's custom message pump can also leverage the standard message pump's handlers by calling IQVMMessagePump::ProcessMessages().  Messages are processed either until the queue is empty or until WM_QUIT is received, at which point the method also returns E_ABORT.  Finally, a plug-in can also invoke the standard message pump object's task, if there is one, by calling IQVMMessagePump::RunTask().

Embedding QuadooScript in Other Applications

It is very easy to include QuadooScript in another application.  The first step is to decide whether the application should include pre-compiled byte-code or compile the script on startup.  QuadooParser.dll includes a single API for parsing and compiling script text (or script files) into a binary byte-code stream.

If you do not have an implementation of ISequentialStream available, then you can use QuadooScript's default implementation:

Once byte-code is ready to be executed, an application calls the QVMCreateLoader() method from QuadooVM.dll.

Now the application calls methods from the IQuadooInstanceLoader interface.

The application now calls AddInstance() with the script's file path and the byte-code in a stream.

Once the AddInstance() method returns, the byte-code has been registered and can be loaded into a new VM.  To create a new VM instance, the application calls LoadVM() and passes the name of the script and the stack size.  LoadVM() returns a new VM instance that is ready to execute byte-code.

(See QuadooVM.h for the full set of interface definitions.)

Before running byte-code functions, the application can expose functionality in any of three ways:

• Register global objects with the VM.
• Register global functions with the VM.
• Attach a system call target to the VM.

The first option will be familiar to anyone who's worked with the IDispatch interface.  The application creates its global objects (derived from the IQuadooObject interface) and adds them to the VM's global namespace using the AddGlobal() function.

The second option involves implementing the IQuadooFunction interface and adding objects of this type using the AddGlobalFunction() method.  These objects have only a single method, Invoke(), which also receives the name of the function being called, so it is possible to use one instance to support multiple exposed functions.  These functions are called at the global scope since they have no associated object, from the script's perspective.

The third option involves implementing the IQuadooSysCallTarget interface and attaching an instance using the SetSysCallTarget() method.  This is the lightest weight and most performant way to expose external functionality to scripts.  Like IQuadooFunction, IQuadooSysCallTarget also just has a single Invoke() method.  Instead of a method name, Invoke() receives the system call number, which was either compiled directly into the bytecode through the SYSCALL_STATIC instruction or acquired at runtime from a variable passed to the SYSCALL_DYNAMIC instruction.  The instruction emitted depends on whether a literal is used with the "syscall" function keyword.  If the external system call returns E_PENDING, then the VM immediately exits and sets the script's running state to suspended.

Another way to expose external data to scripts is through the IExternalScriptSite interface.  Names exposed through that interface appear as properties of the global scope.  For example, from the ASP environment, the Response and Session objects are exposed using the IExternalScriptSite interface.

Once the globals are loaded, the application should call RunConstructor() to run the script's global construction code.  This initializes the script's global variables.

After the global constructor completes, the application is now free to call any other function it wishes to call from the byte-code.  An application uses FindFunction() to look up the function index for a function and RunFunction() to call that function.  When RunFunction() returns, the byte-code function has finished running.

Before unloading the VM, the application should call the Unload() method on the VM.  This ensures that everything is properly freed from the VM's byte-code stack.

Input and Output

QuadooScript provides three intrinsic functions for reading input and writing output.  For QVM.exe, the input intrinsic reads from stdin, and both print and println write to stdout.  However, QuadooScript's VM (QuadooVM.dll) doesn't know anything about input and output streams.  Instead, even input, print, and println are controlled using the exposed embedding API.

Input is implemented using the IQuadooInputSource interface, and output is implemented using the IQuadooPrintTarget interface.  Both interfaces are implemented by QVM.exe.

The ActiveQuadoo.dll host also implements both interfaces, but it sends output to the Active Script environment's Response object, and its input source can be either request variables in the ASP environment or the standard input stream for other Active Script environments.

Custom embedding hosts are also free to implement their own behaviors for these intrinsic functions so that their scripts can manipulate input and output that is appropriate for those environments.

Sample Code

The following is a quick sample for running a script from a C++ program:

There is a CStatus class used for handling callbacks during the compilation phase.  It can be implemented with empty methods:

In the example above, a printing target is attached with a fake IUnknown implementation, mainly because its lifetime doesn't need to extend beyond that stack frame.  Production code should use reference counting.

Finally, the example above makes calls to a PrintException() function when exceptions have occurred.

Note that this example is using wprintf() to output information to the console.  This might not even be correct for a console application, depending on the selected character set.  Regardless, host applications that run with a GUI or as a back-end server will need to use reporting mechanisms that are appropriate for their environments.

Native Objects

On its own, QuadooScript is just a programming language.  It doesn't know how to access the network or read from databases.  Even with the Host object, QuadooScript has limited file system support.  Also, as a byte-code language running on a virtual machine, code written in QuadooScript will never be as fast as native code.  Therefore, there will always be reasons why it will make sense to provide external functionality to QuadooScript from C++ (or any language that can implement QuadooScript's interfaces).

The QuadooScript package already contains multiple external native modules, including the WinHttp and Cryptographic modules.  As a developer using QuadooScript, you may find that you want to write your own native modules that your scripts can call.

To be clear, QuadooScript itself doesn't know anything about ActiveX or the mechanisms involved with loading external modules.  Creating a module that can be loaded by Host.CreateObject() or by Host.LoadQuadoo() only applies to environments that include the Host object, such as QVM.exe, WQVM.exe, and ActiveQuadoo.dll.  QuadooScript itself (i.e. QuadooVM.dll) only knows about IQuadooObject without regard for how the object was loaded.

Creating a Native QuadooScript Module

Creating a native QuadooScript module is easy, but it requires some overhead to be implemented.  A native module for QuadooScript is basically the same as any other ActiveX control that exposes IDispatch objects.  To be usable by QuadooScript, the module must expose objects implementing IQuadooObject.  A module could expose IDispatch too if it wanted to be compatible with ActiveScript environments.

The first step to creating a module is to create a C++ project for a dynamic link library.  At the very least, the project will need to expose DllGetClassObject() using a module definition file (or equivalent mechanism).

A QuadooScript module's class factory should support at least two class IDs, even if they both create the same object.  For example:

The standard CLSID_QuadooObject class ID (defined in QuadooObject.inc) is used to load a module without it being registered with the operating system.  Host.LoadQuadoo() loads unregistered modules using only its file system path.  For other environments, including ActiveScript (using ActiveQuadoo.dll), it may be necessary to register the module with the system and load it by its registered name using COM (i.e. via CLSIDFromString() and CoCreateInstance()).  In that case, the module must also expose its module-specific class ID associated with its component reference.

By convention, a native module typically has its DllGetClassObject() function and other module-specific overhead defined in a file called DLLMain.cpp.  The class factory code is included by DLLMain.cpp.  A developer using ATL or another framework might have a similar or different structure.

The class factory will support the creation of an object that implements IQuadooObject.  This will be the main object for the module.  In the example above, CQSWinHttp is the class instantiated whenever either CLSID_QSWinHttp or CLSID_QuadooObject is requested.  To be loaded natively by QuadooScript, the object must implement IQuadooObject.  If VBScript loads the same object, it will query for IDispatch.  An object could implement both interfaces for maximum compatibility.  In QuadooScript's case, if the object only supports IDispatch, then QuadooScript will provide an adapter for the object.

If a native module loaded through COM wants to participate in dynamic unloading, it must expose the DllCanUnloadNow() function.  Every object created by the module, except for the class factory object, must manage an object counter.  This is typically done from the constructor and destructor of every object that implements IQuadooObject in the module.  For example:

These DLLAddRef() and DLLRelease() functions simply increment and decrement a counter, respectively.  If the module was loaded by COM (using Host.CreateObject() from script), then the module's DllCanUnloadNow() function will be called periodically (by COM) to determine whether the module can safely be unloaded.  If this function is not already defined by your framework, then it might be defined like this:

DLL registration and unregistration rely on implementing and exposing the standard DllRegisterServer() and DllUnregisterServer() functions from your module, respectively.  If Host.CreateObject() fails to load an object, it is often because either the name isn't correctly associated to a class ID or the class ID is not correctly registered with the module's file path.

Optional Class Factory and Registration Support

Three optional functions are available from SimbeyCore.dll to simplify the implementation of class factories and DLL registration:

Three macros (used in the CQSWinHttp example above) for implementing the class factory are defined like this:

As you would guess, CQSWinHttp defines (through inheritance) a static method called QueryCreateIID():

If your implementation has a compatible structure with a static method (or global function) having the same signature as the QueryCreateIID() method, then you may want to consider using the ScCreateClassFactory() function to simplify your code.

Registration and unregistration rely upon each module defining a module-specific class that inherits from a CDLLServer class.  DLLMain.cpp always instantiates a global instance of a subclass of that class.

The last line in DLLMain.cpp instantiates the module-specific subclass of CDLLServer:

All of this is optional if you are using ATL or another framework that provides equivalent class factory and module registration functionality.

Sample Module Project

There is a sample module project available on GitHub that can be used as a template for creating a new external native module for QuadooScript.

The sample module can be used from script as follows:

ActiveScript and ASP

Included in the QuadooScript package is a file called ActiveQuadoo.dll.  This is a version of QVM.exe that can be loaded by an ActiveScript host, such as CScript.exe, WScript.exe, or by ASP.dll (using IIS).

When loaded by an ActiveScript host, the output routines (Host.Write(), Host.WriteLn(), Host.BinaryWrite(), print(), and println()) are redirected through the host.  In the case of CScript.exe, output will appear on the console, but with WScript.exe output will appear in popup message boxes.  When used from the ASP environment of IIS, output is sent to the web browser!

For a web page to use QuadooScript, it must tell the ASP environment that it is written in QuadooScript by placing the following declaration at the top of the web page:

Alternatively, the ASP environment can be configured to use QuadooScript by default.

When using QuadooScript outside the ASP environment, the #include "" directive can be used to include other QuadooScript files.  In the ASP environment, files are included using special ASP syntax:

That still inserts the specified file's text into the page at that location, but ASP will automatically remap line numbers for error logs when exceptions occur.

Unlike other scripting languages, QuadooScript does not allow executable statements (other than variable declarations) at the global scope.  Therefore, all text blocks must be typed within functions.  After declaring QuadooScript as the page's language, the remainder of the page will be wrapped within <% and %> markers.  Free text would then be placed within %> and <% markers.  Just like with a script running under QVM.exe, execution begins with the main() function.

QuadooScript never sees free text blocks or the text that they contain.  The ASP environment converts those blocks into Response.WriteBlock() calls.  The Response object is provided by the ASP environment at runtime.

The ASP environment is somewhat language agnostic and doesn't know what kind of language syntax will ultimately be used, but it assumes that Response.WriteBlock() will be valid syntax.  Fortunately, that is valid QuadooScript syntax, with one issue.  The ASP environment does not emit a semicolon at the end of the statement.  Normally, this would be a syntax error for QuadooScript.  However, when used within the ActiveScript framework, parsing is done slightly differently, and semicolons at the end of statements become optional.

Since so much of an ASP page will involve calling methods on the host's Response object, it would be a good idea to declare the Response object upfront using extern.

If you intend to use ASP's Session object, then it could be declared as well.

While you could also declare the Request object, you might want to use a special version of the Request object that is built into ActiveQuadoo.dll.

This works only if form variables have not been accessed yet.  The returned Request object will now parse the form variables instead of ASP's object.  The benefit is that ActiveQuadoo's object can handle both uploaded file data (multipart/form-data) and JSON data (application/json) in addition to normal form data (application/x-www-form-urlencoded).  There are also a few convenience methods available that make it easy to route the page request to handlers based on form variables.

The following is an example of a web page that uses QuadooScript:

When using ActiveQuadoo.dll in the ASP environment, the Host object exposes an indexed ServerVariables property that can be used for reading the content type and other values before deciding how to process the request.  The indexed Host.ServerVariables property is available even without using Host.ParseFiles().

Request Properties

There are three collections (map objects) on the Request object that can be retrieved directly as exposed properties:

• Form
• Cookies
• Files

Since those properties return maps, all methods available to maps can be used with those objects.

When files are uploaded, each file's name is accessible using Request.Form["file_upload_field"].  The file data is exposed as a binary data object from Request.Files["file_upload_field"].  The binary data object also exposes the file's name.

Uploaded files can be enumerated using the following code:

Normal form variables can also be retrieved using this syntax: Request["form_variable_name"].

Server variables are retrieved using the indexed ServerVariables property.

If there is a query string that's different from the form, its variables can be retrieved using the indexed QueryString property.  The query string, if available, can also be returned as a string using the QueryString property.  The cookies can also be returned as text using the CookieText property.

The Request object also exposes ContentType, UserAgent, and Browser properties.

Request Methods

The Request object supports several methods for simplifying common operations like checking for form variables and making decisions based on form variables.

• Has(strName) - Returns true if the form contains the specified variable name.
• HasInvoke(strName, fnCallback) - Calls fnCallback with the value of strName if it exists, then returns true.  Otherwise, false is returned.
• GetFormVariables() - Returns the form variables as a string.
• ReplaceFormVariables(strForm) - Replaces the form variables with the provided form string.  This method fails if there are uploaded files.
• OptFind(strName, vDefault) - Returns the form value specified by strName or vDefault is the name doesn't exist in the form.
• Select(oPage, aVariables, strPrefix) - Calls methods on oPage based on whether the form contains a name from the array, then returns true.  Returns false if none of the names were found in the form.

The Request.Select() method allows easy routing based on the form.  Form buttons with names can be used to select a different code path into an object managing the web page, for example.  If nothing matches the contents of the array, then a default code path can be taken.

The following example would select a different code path based on the form:

The third parameter is an optional prefix.  If specified, the method name expected to be called has the prefix value added.  The form variables do not contain the prefix in their names.

Writing Binary Data

When sending binary data, such as a file, back to the client, an ASP script can send data through the standard Response.BinaryWrite() method.  QuadooScript's ActiveQuadoo.dll module also supports a convenience method for sending large data buffers as smaller chunks with optional Flush() calls when ASP page buffering is enabled.

The Host.BinaryWrite() method performs the following actions:

1. ASP's Response.Buffer property is read to determine whether buffering is enabled.
2. The large binary data is fragmented into 2MB chunks to be sent separately to Response.BinaryWrite().
3. The 2MB SAFEARRAY is allocated once and reused until the remaining data is smaller than 2MB.
4. If buffering is enabled, and if there is still data remaining to be sent, then Response.Flush() is called.
5. If buffering is not enabled, then 2MB chunks are sent without any Response.Flush() calls.

The default size for the "Response Buffering Limit" setting in ASP is 4MB.  When using Host.BinaryWrite() with buffering enabled, there is no need to increase the buffering limit.

Page Transfers

When using ActiveQuadoo's Request object, the Host.Transfer(Session, Server, strPage [, strForm]) method can be used to transfer control to a different page.  The Session and Server objects must be passed to the method because, internally, Server.Transfer() is ultimately used to transfer, and all the rules and conditions of that method apply.

The benefit to using Host.Transfer() is that this method will also collect data and pass it through the Session object to be retrieved by the target page.

1. The form data will be collected and attached to session variable TransferForm.
2. The server variable SCRIPT_NAME will be set as session variable ReturnPage.
3. Session variable Transferred will be set to true.

If the target page wants to continue using the transferred form, then it should use Host.ParseFiles(Session) to collect the form data.  If the target page wants to preserve the form data, then it should exclude the Session data from the call.

This model can be used to transfer control to a login page whenever credentials expire.  If credentials are successfully entered, then control can be passed back to the original page (using Server.Transfer()) without any loss of data or extra coding.  The original page might not even realize that a page transfer occurred.

In the login model that has been described, it is important to note that the login page would use ASP's Server.Transfer() method to return control to the original page, instead of using Host.Transfer().  This is because once the user has entered credentials on the login page, control needs to be returned to the original page without overriding the transferred page data that's already in the Session object.  ASP's Server.Transfer() method merely transfers control to the new page without changing any other session data.

JSON Requests

ActiveQuadoo.dll handles incoming JSON requests natively.  If the content type of the request is application/json, then ActiveQuadoo.dll parses the request data as UTF-8 JSON text.  The JSON data is accessible by reading the Request.JSON property.

In addition to the JSON property, if the parsed JSON data is a JSON object, then the top-level fields of the JSON object are copied to the field map so that they can be accessed as if they had been set by a regular query string.  Some scripts may handle either requests using query strings or requests using JSON data, without knowing or caring about the type of request.

As an example, if the script receives this JSON data:

The script could then use Request["type"] and Request["samples"] to access the data fields, in addition to using Request.JSON to access the original JSON object.

Custom Requests

You may have noticed that application/xml does not have native support by QuadooScript.  To be fair, classic ASP didn't handle XML requests either (and also didn't handle JSON requests).  There may be other content types that a script might want to handle, and QuadooScript couldn't possibly know about all of them.

If a script is intended to receive custom request types (including XML), then it must call Request.LoadData(oHandler) before anything attempts to read field data from the Request object.  Care must be taken to design the code flow so that the Request object is created, and then LoadData() is called before any field data is accessed.

In the sample above, a script class called CParser is instantiated and passed to LoadData() immediately after creating the Request object.  The script class's ParseData() method is called with three parameters: the binary data object holding the request data, the field map, and the files map.

The script's ParseData() method should check the data object's ContentType for types it understands.  If it understands the content type and successfully parses the data, it should return true.  If the data is not handled, it should return false.

If the script understands and handles the binary data, it has the opportunity to write some field data into the mapFields map object.  If the custom binary data contains files, they can also be added to the mapFiles map object.

Character Sets and Multipart Form Data

ActiveQuadoo.dll recognizes the special _charset_ form field when parsing multipart/form-data forms.  For example:

When the hidden _charset_ form field is included as shown above, the web browser automatically fills the field's value with the name of the character set selected by the browser.  ActiveQuadoo.dll begins parsing the form with the ISO 8859-1 character set but switches to a different character set when the parser encounters the _charset_ form field.  The field itself is not included in the form variable set that is visible to the script.

Global.asa

QuadooScript can also be used to implement a website's Global.asa file.  For example:

Each time ASP runs the Global.asa script, first the global constructor is called, followed by the main() function, which must be present but can be empty.  Finally, ASP calls one of the other global functions, whose names must be:

• Application_OnStart
• Application_OnEnd
• Session_OnStart
• Session_OnEnd

When the Application_OnStart() and Application_OnEnd() functions are called, the Session object is unavailable, but, in the example above, it is still defined globally using the extern Session catch syntax.  This syntax ensures that the global constructor does not throw an exception if the object cannot be retrieved.

WebSockets

In addition to serving ASP requests from IIS, ActiveQuadoo.dll can also handle WebSocket requests using QuadooScript.

• Setup
• Creating a WebSockets Script
• Socket Groups
• Controlling WebSocket Handlers

Setup

The first step to using the WebSocket handler is registering ActiveQuadoo.dll as an HTTP request handler.  The standard APPCMD.EXE IIS utility should be used to register ActiveQuadoo.dll.  Next, verify that the following three XML fragments are configured in the applicationHost.config file:

Creating a WebSockets Script

After registering ActiveQuadoo.dll for handling WebSockets, then a script file with the .qws extension can be invoked as a WebSocket handler.  The following script could be used to test the system:

In the WebSocket environment, the Host object has all the base methods and properties available plus five additional methods specific to WebSockets.

• Send(vData) - Sends either a string or binary object to the client.
• Close(nStatus, strReason) - Sends the provided status and reason text and closes the connection.
• SetHeader(strName, strValue) - Sends a header name and value to the client but should only be used during the websocket() call.
• Output(strDebug) - Sends text to the debug output.
• Post(nSocket, oJSONObject) - Sends a JSON object to the WebSocket handler identified by nSocket.

As you can see from the example script, a new WebSocket handler is instantiated when the websocket() function is called.  The script instantiates a new class that inherits from the IWebSocket interface, which has three methods:

• OnOpen() - Called once after the headers have been flushed to the client, used for sending initiation messages to the client.
• OnPacket(vPacket) - Called whenever a packet has been received.  The vPacket will either be a string or a binary object.
• OnClose(nStatus, strReason) - Called after receiving a close event from the client.

Every WebSockets script must define and implement the IWebSocket interface, and it can be copied from here.

For the earlier example, JavaScript can connect using this code:

Socket Groups

By default, WebSocket handlers are islands within an IIS worker process.  WebSocket handlers are not normally aware of each other.  However, if a handler also inherits from the ISocketGroup interface, then handlers may communicate asynchronously with each other.

To implement a WebSocket handler that joins the socket group, the handler must inherit from both interfaces:

When the WebSocket handler is registered with the socket group, its OnRegister() method is called with its socket number.  The OnRegister() method will be called after the handler's OnOpen method is called.

When other WebSocket handlers are added to the group, their socket numbers are passed to each handler's OnJoin() method.  When handlers are disconnected, each other handler's OnRemove() method is called.

A WebSocket handler can send a JSON object to another handler by calling the Host.Post() method:

There is no return value from the Post() call because the call is made asynchronously, but the call will throw an exception if there are problems posting the message.  The target WebSocket will receive the message to its OnMessage() method.  Only JSON objects are allowed to be sent between WebSocket handlers.  The JSON object should not be modified further after sending it because the receiving handler may begin reading from it immediately on another thread.

WebSocket handlers registered with the socket group may query the Host object for the following properties:

• GroupSocket - Returns the socket number of the current WebSocket handler.
• Sockets - Returns a JSON array of all the registered socket numbers.

Controlling WebSocket Handlers

WebSocket handlers can effectively "register" for notification callbacks from external systems by passing their Host object to that external system.  When that external system receives such a call containing the Host object, then that system should query the object for the IWebSocketsInterface interface.

Once another system has the IWebSocketsInterface interface pointer, then it can query the script for custom interfaces, make protected interface calls into the script, or send JSON objects or binary data directly to the client.

The following example demonstrates creating an object in the script handler's OnOpen() method and then registering itself for callbacks.

When the other object's Register() method is called, it will query for the IWebSocketsInterface object and then retrieve a callback interface using the GetInterface() method.  Both the hypothetical Register() method and callback interface represent a contract defined by the developers of those parts.  ActiveQuadoo.dll has no interest in the designs of the callback system once it provides the Host object to the other system.

For a simple notification system, the callback interface could have just one method.

For this example, the external system would use GetInterface() to query for the IMyNotification interface.  In most cases, it would make sense to cache the interface and its callback method index.  When the external system needs to make the callback, it must always call the interface using the ProtectedCall() method, which protects the script call using an internal critical section.  Also for this example, it's important to note that the external system could pass its data directly to the client using the SendToClient() method.

Since the external system must deal with C++ interfaces, either C++ or a language compatible with C++ interfaces must be used to implement the IQuadooObject object that receives the script's Host object and queries it for IWebSocketsInterface.

Delayed Timer Callbacks

The ASP and WebSockets hosts contain two methods for managing delayed timer callbacks.

• StartTimer(strTimerName, msTimeout, vData) - Starts a timer using the provided name, timeout (milliseconds), and JSON data.
• StopTimer(strTimerName) - Attempts to stop a timer using the provided name, throws an exception if the timer can't be stopped.

Timer callbacks are registered under arbitrary names, along with a timeout in milliseconds, and any kind of JSON data (i.e. null, a string, a JSON array, or a JSON object).  If a timer with the same name is already registered, then the JSON data is added to an array that will eventually be passed to the timer callback when it fires.

The timer callback function that will be called is TimerMain(), which is defined in the same script that registers the timer.

Notice that the required parameter is actually a JSON array.

Each call to Host.StartTimer() adds JSON data to the array that is passed to TimerMain() when the timer fires.

The TimerMain() function can also be defined with two parameters to receive the timer's name.

The Host.StopTimer() can be used to stop a registered timer.  If successful, it returns the array of JSON data that would have been passed to the timer callback.

Timer Host/VM Environment

When registering a timer callback, QuadooScript keeps a reference to the compiled byte-code of the calling script and reuses it for the timer callback later.  The timer itself is registered with the Windows thread pool, and when it fires the callback runs from an arbitrary thread pool worker thread.

When the TimerMain() function is called, the script is no longer running under the original host.  In fact, the script is running in a new VM instance too.  Timer callbacks may run seconds, minutes, or hours after the original script completed, and there is no longer any connection to either the ASP or WebSockets connections.

The Host object for a timer callback still supports the common Host methods, but it does not support the ASP or WebSockets specific methods.  However, the timer callback's Host object still supports the StartTimer() and StopTimer() methods.

When writing a script that includes timer callbacks, some considerations must be made to avoid invoking objects that may not exist from the global scope.  For example, while Request and Session can still be defined using extern, remember that they will be null when running in a timer callback.

Calling Host.ParseFiles() from the global scope does still work (it returns null) when running as a timer callback.

Another consideration for timer callbacks is limited functionality for resolving virtual paths.  When running under ASP and WebSockets, virtual paths can be resolved by the underlying IIS system.  When a timer callback runs, it no longer has the ASP or WebSockets connections, so it is limited in its ability to resolve relative file system paths.  Only the root "/" path is mapped and cached for the timer callback.  If a timer callback knows that it will need to resolve other paths, then it should resolve relative paths before registering a timer and include that information in the JSON data.

Web Services

QuadooScript is a great choice for creating web services in the classic ASP environment.

The following script could be used as a template for creating web services that handle JSON requests and return JSON responses.

This model makes it easy to add additional "actions" by simply adding new methods that begin with an underscore.  These methods are called automatically via the use of the invoke() call, but only methods beginning with an underscore are directly callable externally.

In this example, a JSON response can easily be returned using the WritePageJSON() function, and errors can be returned using the WriteJSONError() function.  Any unhandled errors are always returned using the catch handler in the main() function.

Scripts as Modules

Just as Host.LoadQuadoo() can be used to load native modules, it can also load external script files as modules to be used by the calling script.  These scripts can be either plain text script files or pre-compiled QBC files.

To load an external script as a module, it must implement a CreateObject() function.  This function is called internally by the Host.LoadQuadoo() call and should return some kind of object that can be used by the caller.

The calling script would then load the above script as a module and call the MyMethod() method.

Scripts can also be pre-compiled into QBC files, which can then be loaded with a Host.LoadQuadoo() call.

An optional value can be passed through the Host.LoadQuadoo() call to be used in the object creation process.

The optional value, when provided, is passed to the script module's CreateObject() function as its vParam parameter.  If no value is provided, then vParam receives a null value.

Compile to Executable

Scripts and pre-compiled QBC files can also be embedded into a single executable file.

Optional command line arguments for CompileQuadoo.exe:

• -i Specifies an ICO file for the generated executable.
• -t Specifies the template binary for the executable (QVMT.BIN is used by default).
• -a If present, all text after this option is copied into the new executable to be used as the base command line text passed to the embedded script.

The generated executable contains the compiled script and optionally the icon and any provided command line arguments.  Additional command line arguments provided when launching the executable are simply appended to the embedded command line arguments.

If the embedded command line arguments do not already contain the -args parameter, then it is added before adding additional command line arguments passed to the executable when launched.  This means that while embedded command line arguments can alter the behavior of the host, command line arguments passed to the executable are only script-level arguments, and -args does not need to be explicitly passed to the generated executable by the user.

The above diagram was generated using a QuadooScript wrapper for the Pikchr library.

Database Plug-in

The QuadooScript package contains a basic database module that can connect to Microsoft Access files and to SQLite database files.  The first step is to load the module:

The next steps are to connect to a database file and then open a session.

Once a session object has been created, statements can be executed, and queries can be performed using the same objects for either Access or SQLite.

There are two ways to execute a query using the QuadooScript database module.

Database transactions may also be used from the session object.

When using a SQLite connection, it is also possible to execute INSERT and UPDATE statements with blobs.

WinHttp Plug-in

Since so much of what developers need to do involves making web calls, it makes sense to include a WinHttp plug-in in the QuadooScript package.  The QSWinHttp.dll plug-in makes it easy to send and receive data from web endpoints.

Alternatively, if QSWinHttp.dll is registered and needs to be opened in a COM environment (e.g. ASP), then it would be loaded like this:

Server objects may also be opened with a user name and password.

The server object's OpenRequest() method expects seven arguments:

1. strVerb
2. strResource
3. strReferrer
4. vAcceptTypes - Can be null, a string, or an array of strings
5. nFlags
6. strHeaders - Can be null or a string
7. vBody - Can be null, a string, a binary object, or a JSON object

If the response is binary data, then the ToBinary() method should be used.

Response headers can be obtained by accessing the Headers property, but a specific header can be retrieved using the GetHeader() method.

POST Requests

To make a POST request, set the verb to POST in the OpenRequest() call.  The Content-Type header should be specified, and form variables will be sent for the request body.

If the request is uploading files, then the multipart/form-data content type should be used.

Secure Sessions

To use a secure session, the WINHTTP_FLAG_SECURE flag should be passed to the OpenRequest() method, and 443 should be specified for the port in the Connect() call.

Security Options

Before opening a request, security options can be set for ignoring certificate issues, including enabling the use of self-signed certificates on servers.

Basic Cryptography

The QuadooScript package contains a module called QSCrypto.dll.  While not a comprehensive cryptographic library, it does provide some useful functions for hashing and verifying signed messages.

CryptProtect and CryptUnprotect

One of the simpler pair of operations supported by the QuadooScript cryptographic module is "protecting" and "unprotecting" data.  A binary data object can be "protected" (encrypted) and then later "unprotected" (decrypted) using Windows cryptography.

These protection routines are useful for storing sensitive data, such as passwords, in configuration settings.  If the Win32 flag CRYPTPROTECT_LOCAL_MACHINE (an integer of value 4) is passed through the nFlags parameter, then the protected data can be retrieved by any user on the same computer that protected the data.

To further simplify the calls, the data description text could have instead been set to null for CryptProtect() and entirely omitted for the CryptUnprotect call.  The oPassword parameter could also have been set to null.

Signing and Verifying Signatures

The QuadooScript cryptographic module wraps several CryptoAPI functions, and the following sample (split into segments) demonstrates using them to sign and verify signatures.  Private and public keys are also generated, exported, and imported.

The first block defines constants for the APIs and loads the module.

The next segment creates a cryptographic context, generates a private key, hashes a file, signs the hash, and exports the public and private keys.

A common use case for cryptography is verifying a file's authenticity by checking its signed hash using the signer's public key.

The final segment of this sample also demonstrates loading the exported private key back into a new cryptographic context and using it to verify the file's signature.

Hashing Passwords and Deriving Keys

The previous sample generated a random key.  In the following sample, a password hash is used to derive a cryptographic key, which is then used to encrypt and decrypt data.

JSON Web Tokens

The following example demonstrates creating and validating JSON Web Tokens (JWTs).

This code could be adapted to create and validate JWTs in web-based environments.

The output from running TestJWT() should look like this:

In the example, the Hmac-SHA256 (HS256) algorithm is used to sign and verify the JWT.  More information about JWTs can be found here.

When making a request to an endpoint that expects a JWT, the token will probably be sent through the Authorization header.  For example: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9. eyJzdWIiOiJ3ZWJzaXRlX3Rva2VuIiwibmFtZSI6InF1YWRvbyIsImlhdCI6IjIwMjEtMDMtMjhUMjI6NDk6MjUuODQzIn0. -6N-UL-h9R-nggu1QohwX3l3yjsNZF9t8rvPfIsb3wI

Elliptic Curves

The QSCrypto.dll module can be used to perform basic operations with elliptic curves using the SECP256K1 algorithm.

The elliptic curve can be used to sign 32 bytes of data, such as a 32-byte (256 bit) Hmac SHA256 hash.

To verify a signature, call the key's Verify() method with the hash and the signature.  If false is returned, then either the data or the signature has been modified.

Only the public key is needed to verify a signature.  The public key can be extracted from the private key.  Signature verification using the public key works the same as it does using a full private/public key pair.

It is also valid to pass the signature in binary DER form to the Verify() method.

Generating Keys for Elliptic Curves

Keys for Elliptic Curves can be generated from 32-byte (256 bit) blocks of data.  A script can generate these entirely by itself, or a script can generate 32 bytes of random data using the GenRandom() method.

Not all random data can be used as a key for Elliptic Curve.  There is a 1/2¹²⁸ chance that the private key is invalid.  Before using the key, it must be checked for validity.

ECDH Shared Keys

Given two private keys, a shared key can be generated using Elliptic Curve Diffie-Hellman (ECDH) by combining the other key's public key with your private key.

If oKeyA and oKeyB each hold a private key, then the shared ECDH key can be computed by combining its private key with the other key's public key.  The resulting shared key can then be used for symmetric-key encryption.

One possibility for using an ECDH shared key would be to load it into an AES key for encryption and decryption.

AES Encryptors/Decryptors

If AES is needed in an environment where the Windows cryptographic library has limited functionality, the reference AES can be used instead.

The example above works because ECDH keys are 32 bytes, and 256-bit AES requires a 32 byte key.  192-bit AES requires a 24 byte key, and 128-bit AES requires a 16-bit key.  An MD5 hash would be compatible with 128-bit AES.

Cryptographic Entropy

In some environments, such as the ASP environment, it may not be possible to use GenRandom() to generate an Elliptic Curve key.  In those situations, it may be possible to use the GetEntropy() method instead, as it does not rely upon a cryptographic context object.

This method of key generation may not be suitable for a production environment, but it may be sufficient for generating keys in a testing environment.

Blockchain Example

There is enough cryptography in the library to support several blockchain concepts.  Click here to see the blockchain example script.

Bitcoin and Ethereum Addresses

Using QuadooScript's cryptographic library, Bitcoin and Ethereum addresses can be generated and formatted in script.

Using QuadooScript and its cryptographic library to format Bitcoin addresses:

Using QuadooScript and its cryptographic library to format Ethereum addresses:

Capturing From Webcam

The QuadooScript package contains a QSDS.DLL module that allows scripts to read video frames from webcams.  Internally, this is accomplished using DirectShow.

The first steps are to enable COM, load QSDS.DLL, and enumerate and select the webcam (or other compatible video input device) for video capture.

Once the desired device has been located, then it can be opened for video capture.  In this example, the MSE24() method is used to compare two video frames using the Mean Squared Error algorithm.

The calls to DisconnectPins() and DestroyGraph() are needed to release circular references between the internal objects.