Quark Documentation
Release 0.2.8
Datawire
February 19, 2016
Contents
1
Quark Quick Start
3
2
Quark Installation and Configuration Guide
5
3
Quark Language Reference
11
4
Indices and tables
53
5
Document Version
55
i
ii
Quark Documentation, Release 0.2.8
Available documentation:
Contents
1
Quark Documentation, Release 0.2.8
2
Contents
CHAPTER 1
Quark Quick Start
This page provides an overview of the basic installation requirements and process, basic compile commands, and the
Quark language. If you have successfully run and understood any of the examples, you can probably skip this Quick
Start.
1.1 Installation and Configuration
This section provides an overview of the prerequisites, installation, and compilation process for Quark meant to get
you started. Some features and target output languages have additional requirements. For full installation and documentation instructions, see the Quark Installation and Configuration Guide.
1.1.1 Prerequisites
Quark requires a modern Linux distribution or Mac OS X. It has been successfully tested on the following:
• Mac OS 10.10 (Yosemite)
• Mac OS 10.11 (El Capitan)
• Ubuntu 14.04 (Trusty)
• Fedora 22
Quark also requires the following:
• Python 2.7+
• pip
1.1.2 Installation
To install Quark, run the following command:
pip install datawire-quark
1.1.3 Compiling Quark Files
The Quark compiler can perform four distinct functions: generating code in one or more target languages, compiling
and running the generated code, generating HTML documentation based on annotations in the code, and generating
distribution packages for one or more target languages.
3
Quark Documentation, Release 0.2.8
The simplest command generates code in all supported target languages in default output directories. It is:
quark compile <files>
where <files> is a space-separated list of the Quark files to compile.
This will output code in a subdirectory of your base quark directory (given the name of the first file in the <files> list)
and put generated Java, Javascript, and Python code in java, js, and py subdirectories.
To generate installable versions of the examples or of your own code in all of the supported languages, use the package
command as follows:
quark package <files>
where <files> is a space-separated list of the Quark files to compile.
This does everything the compile command does but also builds the code in each language, generates documentation
for each language, and creates installable packages. See the Compilation page of the Quark Installation and Configuration Guide for specific details on where the output artifacts are placed underneath each language’s subdirectory.
1.2 Quark Language Basics
Quark is a language designed primarily for facilitating microservice communication pathways.
Quark uses many of the standard elements of object-oriented programming languages including packages, interfaces,
classes, methods, properties, functions, variables, annotations, operators, and keywords. It includes inheritance, operator overloading, and method overriding capabilities.
Quark code is stored in text files with a .q file extension.
See the Quark Language Reference for more specifics about language structure and language elements.
1.3 Next Steps
The Quark Examples Repository (located in the examples subdirectory of the quark github repository) includes a wide
variety of examples illustrating both simple language features and full end-to-end service implementations.
Please read the Quark Installation and Configuration Guide for more detailed information about installation, configuration, compilation, packaging, and documentation generation.
The Quark Language Reference provides information about how to code in Quark and specifics about individual
language elements including keywords, operators, functions, data types, and annotations.
The Quark Issues List provides a list of known issues - please feel free to add new issues or feature requests as you
start to use Quark.
1.4 Document Version
Quark Quick Start 0.2.8-1
4
Chapter 1. Quark Quick Start
CHAPTER 2
Quark Installation and Configuration Guide
2.1 Installation
This document walks you through the system, application, and tooling requirements for using Quark as well as the
actual installation process.
2.1.1 Prerequisites
Quark has basic requirements that all users must meet as well as requirements specific to particular output languages.
Basic Requirements
Quark requires a modern Linux distribution or Mac OS X. It has been successfully tested on the following:
• Mac OS 10.10 (Yosemite)
• Mac OS 10.11 (El Capitan)
• Ubuntu 14.04 (Trusty)
• Fedora 22
Quark also requires the following:
• Python 2.7+
• pip
• tar
Java Requirements
You must have Java installed to use any Java code generated by Quark. Quark has been successfully tested with Java
7 and Java 8.
To compile and run the generated code directly from Quark you must also have Maven installed. Quark has been
successfully tested with Maven 3.1 and Maven 3.3.x. Maven is not required if you wish to use the generated .java files
manually either directly or within an IDE.
To use the documentation or package generation feature of Quark with Java, you must also have Maven installed.
Quark has been successfully tested with Maven 3.1 and Maven 3.3.x.
5
Quark Documentation, Release 0.2.8
Note: Javadoc comments will be generated in the source files as part of the code generation process. You may manually
run Javadoc on those files to generate HTML documentation without Maven installed.
Python Requirements
There are no additional requirements to use Python code generated by Quark.
Javascript Requirements
You must have Node.js installed to use any Javascript code generated by Quark. Quark has been successfully tested
with Node 4.2.1 and is expected to work with any 4.x version of Node.
2.1.2 Installation
To install Quark, run the following command:
pip install datawire-quark
Quark also includes core runtimes for each supported language and several runtime integrations that allow
communication-related features of Quark to work in various languages and frameworks. More information about
the runtime integrations and how to install them can be found on the next page of this documentation. The Python
version of the core runtime is automatically installed by the base Quark installation above and the Java version will be
installed automatically when needed, but you may need to manually install the Javascript core runtime if you aren’t
using the node runtime integration (if you are, it will be automatically installed when the node runtime integration is
installed). To install the Javascript core runtime directly, run the following command:
npm install datawire-quark-core
2.2 Integrations
Quark defines a variety of integration types that use communication protocols that differ for different languages and
frameworks. These types are defined like interfaces with just method signatures; you must use a specific runtime
integration matching your development environment to get a working method; these integrations contain code specific
to each environment and how it manages communications.
You do not need to install a runtime integration if you are not using any integration types in your code.
Quark supports four runtime integrations:
• datawire-quark-netty for Java and Netty
• datawire-quark-twisted for Python and Twisted
• datawire-quark-threaded for Python
• datawire-quark-node for Javascript and Node.js
These runtime integrations are installable through the normal install mechanism for your language of choice - pip for
Python, npm for Javascript, and maven for Java (The Java integrations are pulled from Maven Central automatically as
needed by the code you generate and compile and do not require manual installation). Any dependencies are automatically installed when you install the runtime integration so there is no need to worry about prerequisites beyond those
needed for download. Once you’ve installed the appropriate runtime integration or integrations for your development
environment, the integration types should be fully functional and work just like any other data types in Quark.
To install the datawire-quark-twisted runtime integration run the following command:
6
Chapter 2. Quark Installation and Configuration Guide
Quark Documentation, Release 0.2.8
pip install datawire-quark-twisted
To install the datawire-quark-threaded runtime integration run the following command:
pip install datawire-quark-threaded
To install the datawire-quark-node runtime integration run the following command:
npm install datawire-quark-node
2.3 Compilation
The Quark compiler can perform four distinct functions: generating code in one or more target languages, compiling
and running the generated code, generating HTML documentation based on annotations in the code, and generating
distribution packages for one or more target languages. These are ordered tasks; each requires that the previous task
was performed as a prerequisite. To make this easier to manage, the command to run each task automatically runs the
previous tasks in the chain before running the requested task.
2.3.1 Syntax
The general syntax for the Quark compiler is:
quark command options files
where command indicates which of the supported actions Quark should run, options is a space-separated list of options
(which may be omitted if the default options are acceptable), and files is a space-separated list of files to perform the
specified action on.
Note: The command and the options may appear in any order (the command may even be supplied between different
options) but the files must be listed at the end after both the command and all of the options.
2.3.2 Commands
Quark supports four commands, each corresponding to one of the supported actions. They are:
• compile
• build
• doc
• package
Compile
The Quark compile command is used to generate code in one or more target languages. In addition to code, it also
creates some supporting files including a Quark runtime file, documentation source files (if needed for the target
languages), and package definition files (if needed for the target languages).
Quark supports two compilation modes: generating code for all target languages (used by default) or generating code
for one or more specific target languages.
2.3. Compilation
7
Quark Documentation, Release 0.2.8
Build
The Quark build command generates code in one or more target languages (runs the compile command) then compiles
and runs that code.
Doc
The Quark doc command generates code in one or more target languages, compiles and runs that code (runs the build
command), then generates HTML versions of the documentation based on the source files and comments generated
during the compilation process.
Separate documentation is generated for each target language as follows:
Language
Java
Javascript
Python
Source Format
Javadoc
README.md
restructured text (rST)
Output Location
base/target/site/apidocs/index.html
base/README.html
base/build/sphinx/html/index.html
where base is the code output directory for the relevant target language.
Note: The documentation generation process also copies README.md to the Javascript documentation output directory.
Package
The Quark package command generates code in one or more target languages, compiles and runs that code, generates
HTML versions of the documentation (runs the doc command), then creates language-specific packages that can be
distributed to client developers.
Separate packages are generated for each target language as follows:
Language
Java
Javascript
Python
Package Format
Jar
npm
pip
Output Location
base/target/test-version.jar
base/package.tgz
base/dist/package-version-py2-none-any.whl
where base is the code output directory for the relevant target language, package is the name of the first package
encountered within the supplied Quark code starting from the start of the first file in the list of files, and version is the
value of the first @version annotation encountered within the supplied Quark code starting from the start of the first
file in the list of files. If no @version annotation is encountered, the default 0.0.1 version number is used.
2.3.3 Command Options
Quark supports a variety of options that provide additional instructions to the compiler while it runs commands. These
options all act upon the compile step to control how target code is generated. However, because the execution of all of
the commands starts with compilation, the options are valid with any Quark command.
Quark includes a minimal set of defaults that will generate and output code in a subdirectory of your base quark
directory (given the name of the first file in the list of files) and put generated Java, Javascript, and Python code in java,
js, and py subdirectories. If this is the desired behavior, no options are needed.
The available options come in sets that either act upon all languages or act upon compilation in a specific language.
You may mix and match these options; it is perfectly valid to direct the compiler to generate all languages and use the
defaults for some languages and explicit options for others.
8
Chapter 2. Quark Installation and Configuration Guide
Quark Documentation, Release 0.2.8
Options Applying to All Languages
The following options control generating code for all languages:
Command
–all
Description
Indicates code should be generated in all
supported languages
Indicates the base directory for generated
files
Indicates the base directory for generated
files
Outputs everything to the current directory
-o directory
–output
directory
–in-place
Default Behavior
Used if no language-specific options are supplied
Name of the first file in the list of files
Name of the first file in the list of files
Use the current directory for all output. Overrides
all other settings.
Note: Directory names based on file names do not include .q
Java Options
The following options control generating code in Java:
Command
–java
–java-out
Description
Default Behavior
generate Java code and related
files
location for generated code.
Java code is generated
java subdirectory under directory with name of the first file in the
list of files
Note: Directory names based on file names do not include .q
Javascript Options
The following options control generating code in Javascript:
Command
–javascript
–javascriptout
Description
generate Javascript code and
related files
location for generated code.
Default Behavior
Javascript code is generated
js subdirectory under directory with name of the first file in
the list of files
Note: Directory names based on file names do not include .q
Python Options
The following options control generating code in Python:
Command
–python
–pythonout
Description
Default Behavior
generate Python code and
related files
location for generated code.
Python code is generated
py subdirectory under directory with name of the first file in the
list of files
Note: Directory names based on file names do not include .q
2.3. Compilation
9
Quark Documentation, Release 0.2.8
2.3.4 Other Options
Quark supports two top-level options that are independent of compiler commands: help and version
Help
The help option prints a compiler options cheat sheet to stdout.
Syntax
quark –help
or
quark -H
or
quark -h
Version
The version option prints the current version of Quark to stdout.
Syntax
quark –version
2.4 More Information
For further information about Quark, see the following:
• The Quark Language Reference focuses on the language elements of Quark and provides some context around
how the language is structured as well as reference documentation for specific language elements.
• The Quark Examples Repository includes a wide variety of examples illustrating both simple language features
and full end-to-end service implementations.
• The Quark Issues List provides a list of known issues - please feel free to add new issues or feature requests as
you start to use Quark.
If you have not already read it, the Quark README provides a more general overview of Quark’s features.
2.5 Document Version
Quark Installation and Configuration Guide 0.2.8-1
10
Chapter 2. Quark Installation and Configuration Guide
CHAPTER 3
Quark Language Reference
3.1 Introduction
Quark lets you define and implement rich (micro)service APIs that work with your existing application frameworks.
Quark lets you:
• Rapidly prototype and iterate service APIs
• Build service APIs with rich protocol semantics
• Support multiple programming languages and application frameworks
In addition to developing and implementing APIs, Quark also offers a packaging service for each of its component
languages, allowing easy distribution and advertising of service availability to potential users. Quark also generates
API documentation for your libraries in standard formats for each language (when they exist) including Javadoc for
Java and Sphinx for Python.
This document focuses on the language elements of Quark and provides some context around how the language is
structured as well as reference documentation for specific language elements.
3.2 Core Concepts
Quark is a Turing-complete language designed primarily for facilitating microservice communication pathways although it is not limited to this function.
3.2.1 Language Structure
Quark uses many of the standard elements of object-oriented programming languages including packages, interfaces,
classes, methods, properties, functions, variables, annotations, operators, and keywords. It includes inheritance, operator overloading, and method overriding capabilities.
Quark may be used to write libraries or applications. Applications must contain a single top-level main() function
containing the executions structure for the application; this function may reference code from any defined class or
package within the application.
Files
Quark code is stored in text files with a .q file extension. Unlike some languages, Quark is not tied to any specific file
structure and code may be split among as many files as desired provided an entire library or application is compiled
11
Quark Documentation, Release 0.2.8
together. Packages may be defined across multiple files or in multiple locations across the same file and, if desired,
an entire library or application could be defined in a single .q file. However, the set of files comprising an application
may only have one main() function declaration.
Packages
Packages are defined using the package keyword and provide namespaces for class and function definitions. Packages
cannot directly contain variables or runnable code; only classes, functions, and other packages are allowed. Packages
are optional, but provide an easy mechanism for organizing code so that related elements can be grouped together.
They also allow code to be referenced from anywhere within a library or application.
As mentioned above, packages can be nested. Classes and functions directly inside a top-level package must use
nested package name when referencing classes or functions defined inside a nested package but the members of the
nested package have direct access to classes and functions in the top-level package without needing to specify their
package name.
Classes and functions defined outside of a package belong to a default, unnamed root package. This package is
logically identical to any named package. Named packages are nested inside this root package so classes and functions
in the root package may be referenced inside any package directly without specifying a package name.
Classes
Classes are defined using the class keyword and provide a template for a specific type of object. Classes can contain
properties to store data and methods to provide actions that can be performed on that data. Quark classes cannot be
nested and do not support static properties or methods.
Properties
Properties are typed variables meant to store a specific piece of data within an object. Properties are declared within
the class definition and may be given default values. Properties defined within a specific class may be accessed and
manipulated within the methods of that class.
Methods
Methods typically define actions that can be taken on data within an object. Methods may require input parameters
(which are typed) and may return a value (also typed). Methods are defined as follows:
returnType methodName ( parameters ) { codeToExecute
}
where returnType is the type of the return value (void if no value is returned), methodName is the name of the method,
parameters is a comma-separated list of parameter type and parameter name pairs, and codeToExecute is the code
executed by the method.
Methods can directly access any properties defined within the same class as well as methods defined in other classes
using dot syntax references to those methods. Quark does not support static or class methods; all methods are invoked
on a specific object.
self
Quark uses self to reference the current object inside method definitions. In particular, the value of a property of the
current object is referenced as self.propertyName.
12
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
Abstractness
Quark does not support explicitly declaring abstract classes or methods using a keyword. Instead, just define method
signatures without a corresponding body component. Doing so will automatically make both that method and the class
containing it abstract. Trying to instantiate such a class directly will result in an error.
Note: Quark is not currently throwing an error in this case. See linkIssue54 for more information.
Constructors
Constructors are methods called when an object is instantiated. Every instantiable class has a default constructor with
no parameters defined for it automatically, but additional constructors that accept initial values for properties defined
within the class may be added to any class.
Functions
Functions typically define actions that can be taken outside of the context of a specific class. Functions may require
input parameters (which are typed) and may return a value (also typed). Functions do not act on specific objects unless
those objects are passed in as input parameters. Functions may belong to a package or be defined as part of the default
unnamed package. They are defined as follows:
returnType functionName ( parameters ) { codeToExecute
}
where returnType is the type of the return value (void if no value is returned), functionName is the name of the
function, parameters is a comma-separated list of parameter type and parameter name pairs, and codeToExecute is the
code executed by the function.
Interfaces
Interfaces define a group of default methods and method signatures that can be used and defined in other classes.
Interfaces cannot contain properties and may not be directly instantiated in any way. They are essentially template code
ensuring that a library or application implements a common feature somewhat consistently throughout and making
maintenance of common code easier.
Classes that use an interface must provide a body definition for each method signature (without changing the signature)
or the class will automatically include the method signature and become abstract.
[[JMK check this last statement ETA issue 55 preventing testing]]
Quark does not contain a default keyword; rather default methods are defined by providing a functional method body
inside the interface instead of just a method signature. Classes that use an interface may use the default method as is
or redefine it (without changing the signature). If a class using the interface declares the method signature of a default
method a without redefining the body contents, the method and class becomes abstract.
[[JMK check this last statement ETA issue 55 preventing testing]]
Constants
Quark does not currently have a mechanism for declaring global constants.
3.2. Core Concepts
13
Quark Documentation, Release 0.2.8
3.2.2 Naming and Other Conventions
Quark names are case sensitive and may contain only alphanumeric characters or underscores (_). Names of elements
must be unique within the scope of a package, library, or application (in the case of a library or application, fullyqualified names are considered so package1.name1 and package2.name1 are perfectly acceptable).
Package names are not tied to the location of files and are not expected to match directory structures. There are no
global rules for naming conventions; if generating Java code this may result in unconventional package names and file
locations within the resulting Java files.
By convention, Quark expects the following casing rules:
• Package names are lower case
• Class names are upper case
• variable, property, method, and function names are camel case
• annotation names are lower case
3.2.3 Inheritance
Quark supports single inheritance of classes using the extends keyword. Multiple inheritance is not supported. However, all types within Quark automatically inherit from the Object type and contain all properties and methods defined
therein.
Properties are inherited but their definition may not be overridden. In particular, you cannot add or change the default
value directly. Properties defined in the superclass may be referenced directly using self.propertyName within methods
of the subclass.
Methods are inherited and may be overridden in the subclass. The superclass constructor is called automatically for
all subclasses. A subclass may define its own constructor with fewer input parameters than its superclass so long as
default values are provided for all of the other parameters in a super() call at the top of the constructor. If the superclass
uses a constructor with no parameters defined then the subclass may define its own constructor with however many
parameters are appropriate.
3.2.4 Overloading
Quark does not currently support method overloading. Quark supports operator overloading by defining classes that
provide alternate code for the functions underlying the operator execution. When the related operators are used on
objects of that type, this code is executed.
3.2.5 Object Instantiation
Quark objects must be explicitly instantiated in all cases. This is done using the new keyword.
3.2.6 Typing
Quark is a strongly, statically typed language with support for type inheritance and generics. Quark uses primitives as
the base data types; primitives are defined by the system and cannot be modified by users.
14
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
3.2.7 Comments
Single line comments in Quark can be specified using //. Multiple line comments can be specified using /* comment
*/.
3.2.8 White Space
In general, Quark requires at least one white space character between language elements. It typically ignores any
additional whitespace, allowing for variances in indentation conventions and extra lines within code.
White space may be supplied between operators and the elements they act upon (either to their left or to their right)
but it is not required.
3.2.9 End of Statement
Executable statements in Quark must end with a semi-colon (;). Using a modern code presentation style, this typically
means that each line of Quark code ends with a semi-colon excepting the following:
• Keywords followed by an opening curly brace ({)
• The corresponding closing curly brace (})
• Annotations (which typically end with parentheses).
• Comments
3.3 Language Elements
Quark supports the following language elements:
3.3.1 Keywords
Keywords are reserved words that have a specific meaning within Quark. They cannot be used as names of usergenerated content (packages, classes, functions, etc).
Quark defines the following keywords:
break
Documentation Coming Soon
class
The class keyword is used to define a data structure and set of methods that together encapsulate the allowed behaviors
of a specific type of object.
3.3. Language Elements
15
Quark Documentation, Release 0.2.8
Syntax
The class keyword syntax is:
class className { definition }
where className is a unique name within the scope of the package (if one is defined) or the set of Quark files being
compiled together (if no package is defined) and definition is the list of properties and methods within the class and
their definitions.
continue
Documentation Coming Soon
else
The else keyword is used to indicate the alternate code to run when the condition of the related if statement is false.
Syntax
The else keyword syntax is:
else { executeIfConditionFalse }
where executeIfConditionFalse is run if condition evaluates to false. However, else is subordinate to if and cannot be
used separately. The full syntax for the combination is:
if ( condition ) { executeIfConditionTrue } else { executeIfConditionFalse }
where condition is the code being evaluated, executeIfConditionTrue is run if condition evaluates to true, and executeIfConditionFalse is run if condition evaluates to false.
See the if keyword syntax section for more information about constructing conditional clauses.
extends
The extends keyword indicates a parent class of the class currently being defined or an interface used by the class.
Syntax
The extends keyword syntax is:
class className extends superClassName { additionalClassDefinition }
where className is a unique name within the scope of the package (if one is defined) or the set of Quark files being
compiled together (if no package is defined), superClassName is the unique name of the chosen superclass, and
definition is the list of properties and methods within the class and their definitions.
or
class className extends interfaces { additionalClassDefinition }
where className is a unique name within the scope of the package (if one is defined) or the set of Quark files being
compiled together (if no package is defined), interfaces is a comma-separated list of interfaces used by this class, and
additionalClassDefinition is the list of properties and methods within the class and their definitions.
16
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
or
class className extends superClassName , interfaces { additionalClassDefinition }
where className is a unique name within the scope of the package (if one is defined) or the set of Quark files being
compiled together (if no package is defined), superClassName is the unique name of the chosen superclass, interfaces
is a comma-separated list of interfaces used by this class, and additionalClassDefinition is the list of properties and
methods within the class and their definitions.
false
The false keyword indicates that a particular condition is not true. It is one of the two allowed states of a boolean.
Syntax
The false keyword does not have specific syntax, per se. Rather it can be used as a value of any boolean variable,
boolean property, or any conditional clause of code.
if
The if keyword is used to provide code to be run only if the supplied condition evaluates to true. It can be used in
conjunction with the else keyword to provide alternate code paths when the condition evaluates to true and when it
evaluates to false.
Syntax
The if keyword syntax is:
if ( condition ) { executeIfConditionTrue }
where condition is the code being evaluated and executeIfConditionTrue is run if condition evaluates to true.
See the else keyword syntax section for the syntax of if-else statements.
interface
The interface keyword defines an interface containing template information for classes. Interfaces can contain default
methods (which can be redefined in classes using the interface) and method signatures (to be defined in classes using
the interface).
Syntax
The interface keyword syntax is:
interface interfaceName { interfaceDefinition }
where interfaceName is the name of the interface, used to include it in class definitions, and interfaceDefinition is the
content of the interface.
3.3. Language Elements
17
Quark Documentation, Release 0.2.8
macro
The macro keyword is used to define a top-level function available to use within any Quark program compiled at
the same time as the macro. Macros are defined at the top level of the file outside of any package, class, or main
definitions. Macros are evaluated at runtime and may have either a single definition used for all target languages or be
defined separately for each language supported by Quark.
Syntax
The macro keyword syntax is:
macro type ( parameters ) ${ macroDefinition };
where type is the expected type of the macro results, parameters is a comma-separated list of typed input values,
and macroDefinition is the code to run when the macro is executed. This code may be general or it may be defined
separately for each language. If separate definitions are required, the syntax is as follows:
macro type ( parameters ) $java{ javaMacroDefinition } $js{ javascriptMacroDefinition } $py{ pythonMacroDefinition }
The languages may be specified in any order. However, all supported languages must be defined individually if any
need to be; any omitted languages will result in the macro resolving to null which could cause errors or result in
unexpected behavior in that language. See linkIssue27 for more information.
new
The new keyword is used to instantiate objects.
Syntax
The new keyword syntax is:
className objectHandle = new classConstructor ;
where className is the name of the class of the new object, objectHandle is a variable pointing to the new object, and
classConstructor is the constructor method used to create the new object including any relevant parameters.
null
The null keyword is used to explicitly indicate a value is undefined. It is not the same as a value that has never been
set.
Syntax
The null keyword syntax is:
variable = null;
where variable is the handle to the value you want to set to null.
18
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
package
The package keyword is used to indicate a namespace containing groups of similar or related classes. Packages are
automatically available to any Quark files compiled at the same time as the file or files with the package definition.
Syntax
The package keyword syntax is:
package packageName { definition
}
where definition is the content of the package and packageName is the name of the package. Package names are
treated as unique within the scope of the Quark files being compiled together. If the same package name is used
multiple times, the contents of each definition section are combined and treated as a single package. Quark packages
cannot be the same as the name of the file they are defined within. See linkIssue6 for more information.
primitive
The primitive keyword is used to define basic data types in Quark. At the current time it is reserved for use by the
system.
return
The return keyword is used to indicate the return value of a function or method.
Syntax
The return keyword syntax is:
functionType functionType ( parameters ) { code return valueOfTypeFunctionType
}
where functionType is the type of the value returned by the function, functionName is the name of the function,
parameters is a comma-separated list of parameters for the function, code is the code being run by the function, and
valueOfTypeFunctionType is the value returned by the function. It must use the data type specified in the functionType
declaration.
self
The self keyword is used to reference the current object inside method definitions particularly the value of a property
of the current object.
Syntax
The self keyword syntax is:
self. propertyName
where propertyName is the name of a property defined in the current class and the entire expression evaluates to the
value stored in the current object’s propertyName property.
3.3. Language Elements
19
Quark Documentation, Release 0.2.8
super
The super keyword is used to indicate that a referenced method is defined in the current class’s superclass.
Note: A variant of the super keyword, super(), is used to reference the constructor of the superclass inside the subclass’s
constructor. Any parameters defined in the superclass constructor must be supplied when super() is called (either as
variables or as default values).
Syntax
The super keyword syntax is:
super. method
where method is the method being called including the trailing parentheses and any necessary parameters.
For instance, the following method is defined in class A:
void enrollInClass(String classId, String studentId){...}
Class B is a subclass of class A. A method inside class B calls the enrollInClass() method as follows:
super.enrollInClass("Phys123", "84-42956");
true
The true keyword indicates that a particular condition is true. It is one of the two allowed states of a boolean.
Syntax
The true keyword does not have specific syntax, per se. Rather it can be used as a value of any boolean variable,
boolean property, or any conditional clause of code.
while
The while keyword is used to provide code to be run repeatedly as long as the supplied condition continues to evaluate
to true.
Syntax
The while keyword syntax is:
while ( condition ) { executeIfConditionTrue }
where condition is the code being evaluated and executeIfConditionTrue is run as long as condition evaluates to true.
If the state of the condition is not changed in some way within this code block so it eventually evaluates to false the
code will continue to execute in an infinite loop.
3.3.2 Operators
Quark defines the following operators:
20
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
Add
The Add operator is a binary operator that adds the value on the left of the operator and the value on the right of the
operator together.
Syntax
The Add operator syntax is:
A+B
where A and B are the two values being added together. If the values are numbers, the addition is standard arithmetic
addition. If the values are strings, the addition appends the string on the right side to the string on the left side.
And
The And operator is a binary operator that evaluates to true if both the value on the left side of the operator and the
value on the right side of the operator evaluate to true. The And operator evaluates to false if only one of the two
values evaluates to true or if they both evaluate to false.
Syntax
The And operator syntax is:
A && B
where A and B are the two values being evaluated.
At
Documentation Coming Soon
Bitwise Complement
The Bitwise Complement operator is a unary operator that evaluates switches the bits of the supplied value.
Syntax
The Bitwise Complement operator syntax is:
~A
where A is the value to switch.
The Bitwise Complement operator is only partially supported at the moment. See linkIssue34 for more information.
Cast
Documentation Coming Soon
3.3. Language Elements
21
Quark Documentation, Release 0.2.8
Divide
The Divide operator is a binary operator that divides the value on the right hand side (the denominator) into the value
on the left hand side (the numerator).
Syntax
The Divide operator syntax is:
A/B
where A is any numerical value and B is any non-zero numerical value.
Equals
The Equals operator is a binary operator that sets the value on the left hand side to the value on the right hand side.
Syntax
The Equals operator syntax is:
A=B
where A is the value being set and B is the new value it is assigned.
Equivalent
The Equivalent operator is a binary operator that evaluates to true if the value on the left side is equivalent to the value
on the right hand side and evaluates to false if they are not equivalent.
Syntax
The Equivalent operator syntax is:
A == B
where A and B are the values being evaluated for equivalence.
Greater Than
The Greater Than operator is a binary operator that evaluates to true if the value on the left side is greater than the
value on the right side. It evaluates to false if the value on the right side is greater than the value on the left side or if
the two values are equal.
Syntax
The Greater Than operator syntax is:
A>B
where A and B are both numerical values.
22
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
Greater Than or Equal
The Greater Than or Equal operator is a binary operator that evaluates to true if the value on the left side is greater than
the value on the right side or if the two values are equal. It evaluates to false if the value on the right side is greater
than the value on the left side.
Syntax
The Greater Than or Equal operator syntax is:
A >= B
where A and B are both numerical values.
Less Than
The Less Than operator is a binary operator that evaluates to true if the value on the left side is less than the value on
the right side. It evaluates to false if the value on the right side is less than the value on the left side or if the two values
are equal.
Syntax
The Less Than operator syntax is:
A<B
where A and B are both numerical values.
Less Than or Equal
The Less Than or Equal operator is a binary operator that evaluates to true if the value on the left side is less than the
value on the right side or if the two values are the equal. It evaluates to false if the value on the right side is less than
the value on the left side.
Syntax
The Less Than or Equal operator syntax is:
A <= B
where A and B are both numerical values.
Modulo
The Modulo operator is a binary operator that evaluates to the remainder when the value on the right hand side is
divided into the value on the left hand side.
3.3. Language Elements
23
Quark Documentation, Release 0.2.8
Syntax
The Modulo operator syntax is:
A%B
where A and B are both integers.
Multiply
The Multiply operator is a binary operator that multiplies the value on the left of the operator and the value on the right
of the operator together.
Syntax
The Multiply operator syntax is:
A*B
where A and B are the two numbers being multiplied together.
Negate
The Negate operator is a unary operator that switches the sign of a signed number.
Syntax
The Negate operator syntax is:
-A
where A is a number.
Not
The Not operator is a unary operator that inverts the truthfulness of an expression. If the expression evaluates to true
on its own then it will evaluate to false when the Not operator is applied and vice versa.
Syntax
The Not operator syntax is:
! expression
where expression is the expression being inverted.
Not Equivalent
The Not Equivalent operator is a binary operator that evaluates to true if the value on the left side of the operator is not
equivalent to the value on the right side of the operator and evaluates to false if the two values are equivalent.
24
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
Syntax
The Not Equivalent operator syntax is:
expression1 != expression2
where expression1 and expression2 are the expressions being compared.
Or
The Or operator is a binary operator that evaluates to true if either or both of the values on the left side of the operator
and the right side of the operator evaluate to true. The Or operator evaluates to false only if both of these values
evaluate to false.
Syntax
The Or operator syntax is:
A || B
where A and B are the two values being evaluated.
Subtract
The Subtract operator is a binary operator that subtracts the value on the right hand side of the operator from the value
on the left hand side of the operator.
Syntax
The Subtract operator syntax is:
A-B
where A and B are numerical values.
3.3.3 Data Types
Quark data types typically have analogues in each target language and Quark uses the equivalent type when generating
code in the supported languages.
Quark defines the following data types:
bool
Quark bool values are booleans and indicate truthfulness.
Constraints
Boolean values are either true or false. Quark represents these states with the keywords true and false.
[[JMK should I discuss null? It compiles in Quark and evaluates to false in js/python, causes NPEs in Java]]
3.3. Language Elements
25
Quark Documentation, Release 0.2.8
Generated Code
Booleans are translated in generated code as follows:
Language
Java
Javascript
Python
Type
Boolean
Boolean
bool
Allowed values
true|false
true|false
True|False
byte
Documentation coming soon
Class
Documentation coming soon
Field
Documentation coming soon.
float
Quark float values are floating point numbers.
Constraints
Floating point values in Quark are constrained only by the rules of each generated language.
Generated Code
Floats are translated in generated code as follows:
Language
Type
Java
Double
Allowed Values
0
2-1074 to (2-2-52 )·21023
Javascript
Number
0
5*10-324 to 253 - 1
Python
float
varies; see sys.float.info
int
Quark ints are integers.
26
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
Constraints
Integers in Quark are constrained only by the rules of each generated language.
Generated Code
Integers are translated in generated code as follows:
Language
Java
Javascript
Type
Integer
Number
Python
int
Allowed Values
-231 - 1 to 231 - 1
-253 - 1 to 253 - 1
or
-263 - 1 to 263 - 1
integral
The integral type is a base type for all integers. It should not be used directly within Quark code.
List
Quark lists are strongly typed and can contain elements of any other defined data type including other lists and objects.
Constraints
Every element in a list must be the same type of data. For example, you cannot mix strings and floats or floats and
objects.
List types are specified as follows when a new List is declared:
List< type >
where type is the type of the list elements.
Lists may be further constrained by the rules of each generated language.
Generated Code
Lists are translated in generated code as follows:
Language
Java
Javascript
Python
Type
java.util.ArrayList
Array
_List
Allowed values
constrained by definition
constrained by definition
constrained by definition
long
Quark longs are long integers.
3.3. Language Elements
27
Quark Documentation, Release 0.2.8
Constraints
Quark does not permit declaration of long literal values by adding L to the end of an integer.
Long integers may be further constrained by the rules of each generated language.
Generated Code
Long integers are translated in generated code as follows:
Language
Java
Javascript
Python
Type
Long
Number
int
Allowed Values
-263 - 1 to 263 - 1
-253 - 1 to 253 - 1
unlimited
Note: Currently Quark can only handle up to 48bit values. See linkIssue58 for more information.
numerical
The numerical type is a base type for all numbers. It should not be used directly within Quark code.
Map
Quark Maps are sets of key-value pairs. They do not have an inherent order.
Constraints
Quark Maps are strongly typed. Quark supports using any defined type of data in Maps. However, every key in a
specific map must be the same type and every value in a specific Map must also be the same type (the keys and values
may be different types). Also, Quark expect the values of keys to be immutable. Quark Maps are also constrained by
additional rules in
Map types are specified as follows when a new Map is declared:
Map< keyType , valueType >
where keyType is the type of the map keys and valueType is the type of the value keys.
Maps may be further constrained by the rules of each generated language.
Generated Code
Maps are translated in generated code as follows:
Language
Java
Javascript
Python
Type
java.util.HashMap
Map
_Map
Allowed values
constrained by definition
constrained by definition
constrained by definition
Object
Quark Objects are objects instantiated from a defined class.
28
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
Constraints
Objects in Quark are constrained only by the relevant class definition and by the rules of each generated language.
Generated Code
Objects are translated in generated code as follows:
Language
Java
Javascript
Python
Type
Object
Object
object
Allowed values
constrained by definition
constrained by definition
constrained by definition
short
Documentation coming soon
String
Quark Strings are strings of characters.
Constraints
Strings in Quark are constrained only by the rules of each generated language. Additional variable-specific constraints
such as a set of allowed enumerated values are not supported.
Generated Code
Strings are translated in generated code as follows:
Language
Type
Allowed Values
Can contain any character that can be
UTF-16 encoded
Java
String
Javascript
String
Can contain any character that can be
UTF-16 encoded
Python
str
Can contain any character that can be
UTF-8 encoded
void
Quark voids are used to indicate functions and methods that do not return a value.
Constraints
voids in Quark are constrained only by the rules of each generated language.
3.3. Language Elements
29
Quark Documentation, Release 0.2.8
Generated Code
voids are translated in generated code as follows:
Language
Java
Javascript
Python
Type
void
N/A
N/A
Allowed values
any function without a return value
any function returning undefined
any function returning None
3.3.4 Integration Types
Integration types are Quark data types that depend on using an integration to execute. Typically these types are defines
with method signatures rather than code because the code needed to execute the desired functionality is specific to
a particular integration and is defined within that integration. However, some integration types may include method
definitions that use other integration types - these look like normal Quark data types but can’t be executed without an
integration because of their dependencies. Essentially normal Quark data types can be used in code without installing
an integration but integration types cannot. More information about the available integrations and how to install them
can be found here.
Quark defines the following integration types:
Buffer
Documentation coming soon
Client
A factory class that can be used to create generic clients. Typically this class will be extended to define a more specific
client for a particular application or service.
Codec
Documentation coming soon
HTTPHandler
Documentation coming soon
HTTPRequest
Documentation coming soon
HTTPResponse
Documentation coming soon
HTTPServlet
Documentation coming soon
30
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
JSONObject
Documentation coming soon
ResponseHolder
Holds a response while it is being formulated. This should only be used within types that are processing responses
prior to their being sent to the client.
Runtime
Documentation coming soon
Server
A factory class that can be used to create generic servers. Typically this class will be extended to define a more specific
server for a particular application or service.
Servlet
Documentation coming soon
Task
Documentation coming soon
WebSocket
Documentation coming soon
WSHandler
Documentation coming soon
WSServlet
Documentation coming soon
3.3.5 Integration Interfaces
Integration interfaces are Quark interfaces that use integration types within their definition and thus require code
defined within each specific integration module. You must be using an integration module to use any of these interfaces.
Quark defines the following integration interfaces:
3.3. Language Elements
31
Quark Documentation, Release 0.2.8
Service
The Service interface is used to define a set of methods required by services using RPC for communications between
their clients and their server. These methods typically won’t be called directly from any class; this interface should
be extended within RPC contracts to select and configure the desired interaction patterns then used by the client and
server definitions inside the contract to glue everything together.
[[JMK This description needs some work]]
3.3.6 Functions
Quark defines the following functions:
bool::__and__()
Documentation Coming Soon
bool::__eq__()
Documentation Coming Soon
bool::getClass()
Documentation Coming Soon
bool::getField()
Documentation Coming Soon
bool::__ne__()
Documentation Coming Soon
bool::__not__()
Documentation Coming Soon
bool::__or__()
Documentation Coming Soon
bool::setClass()
Documentation Coming Soon
bool::toJSON()
Documentation Coming Soon
32
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
bool::_to_JSONObject()
Documentation Coming Soon
bool::toString()
Documentation Coming Soon
byte::__add__()
Documentation Coming Soon
byte::__div__()
Documentation Coming Soon
byte::__eq__()
Documentation Coming Soon
byte::getClass()
Documentation Coming Soon
byte::getField()
Documentation Coming Soon
byte::__gt__()
Documentation Coming Soon
byte::__lt__()
Documentation Coming Soon
byte::__mod__()
Documentation Coming Soon
byte::__mul__()
Documentation Coming Soon
byte::__ne__()
Documentation Coming Soon
3.3. Language Elements
33
Quark Documentation, Release 0.2.8
byte::__neg__()
Documentation Coming Soon
byte::setField()
Documentation Coming Soon
byte::__sub__()
Documentation Coming Soon
byte::toFloat()
Documentation Coming Soon
byte::toJSON()
Documentation Coming Soon
byte::_to_JSONObject()
Documentation Coming Soon
byte::toString()
Documentation Coming Soon
defaultCodec()
Documentation Coming Soon
float::__add__()
Used to add two floating point values together.
Syntax
float A.__add__(B)
where A and B are floating point values
This function is used under the covers by the + operator; A + B is equivalent to A.__add__(B).
float::__div__()
Used to divide one floating point value into another.
34
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
Syntax
float A.__div__(B)
where A is the floating point numerator and B is the floating point denominator.
This function is used under the covers by the / operator; A / B is equivalent to A.__div__(B).
float::__eq__()
Documentation Coming Soon
float::getClass()
Documentation Coming Soon
float::getField()
Documentation Coming Soon
float::__gt__()
Used to evaluate whether one floating point value is greater than another.
Syntax
int A.__gt__(B)
where A and B are floating point values. Returns true (1) if A is greater than B and false (0) if A is less than or equal to
B.
This function is used under the covers by the > operator; A > B is equivalent to A.__gt__(B).
float::__lt__()
Used to evaluate whether one floating point value is less than another.
Syntax
int A.__lt__(B)
where A and B are floating point values. Returns true (1) if A is less than B and false (0) if A is greater than or equal to
B.
This function is used under the covers by the < operator; A < B is equivalent to A.__lt__(B).
float::__mul__()
Used to multiply two floating point values together.
3.3. Language Elements
35
Quark Documentation, Release 0.2.8
Syntax
float A.__mul__(B)
where A and B are floating point values
This function is used under the covers by the * operator; A * B is equivalent to A.__mul__(B).
float::__neg__()
Used to flip the sign of a floating point value.
Syntax
float A.__neg__()
where A is a floating point value.
This function is used under the covers by the - operator; - A is equivalent to A.__neg__().
float::__ne__()
Documentation Coming Soon
float::round()
Documentation Coming Soon
float::setField()
Documentation Coming Soon
float::__sub__()
Used to subtract one floating point value from another.
Syntax
float A.__sub__(B)
where A and B are floating point values and B is being subtracted from A.
This function is used under the covers by the - operator; A - B is equivalent to A.__sub__(B).
float::toJSON()
Documentation Coming Soon
36
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
float::_to_JSONObject()
Documentation Coming Soon
float::toString()
Used to cast a floating point value to a string.
Syntax
float A.toString()
where A is a floating point value.
fromJSON()
Documentation Coming Soon
int::__add__()
Used to add two integers together.
Syntax
int A.__add__(B)
where A and B are integers.
This function is used under the covers by the + operator; A + B is equivalent to A.__add__(B).
int::__div__()
Used to divide one integer value into another.
Syntax
int A.__div__(B)
where A is the integer numerator and B is the integer denominator.
This function is used under the covers by the / operator; A / B is equivalent to A.__div__(B).
int::__equal__()
Documentation Coming Soon
int::getClass()
Documentation Coming Soon
3.3. Language Elements
37
Quark Documentation, Release 0.2.8
int::getField()
Documentation Coming Soon
int::__gt__()
Used to evaluate whether one integer value is greater than another.
Syntax
int A.__gt__(B)
where A and B are both integers. Returns true (1) if A is greater than B and false (0) if A is less than or equal to B.
This function is used under the covers by the > operator; A > B is equivalent to A.__gt__(B).
int::__lt__()
Used to evaluate whether one integer value is less than another.
Syntax
int A.__lt__(B)
where A and B are integers. Returns true (1) if A is less than B and false (0) if A is greater than or equal to B.
This function is used under the covers by the < operator; A < B is equivalent to A.__lt__(B).
int::__mod__()
Used to determine the remainer (modulo) when one integer value is divided into another.
Syntax
int A.__mod__(B)
where A is the integer numerator and B is the integer denominator.
This function is used under the covers by the % operator; A % B is equivalent to A.__mod__(B).
int::__mul__()
Used to multiply two integers values together.
Syntax
int A.__mul__(B)
where A and B are integers.
This function is used under the covers by the * operator; A * B is equivalent to A.__mul__(B).
38
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
int::__neg__()
Used to flip the sign of an integer.
Syntax
int A.__neg__()
where A is any integer value.
This function is used under the covers by the - operator; - A is equivalent to A.__neg__().
int::__ne__()
Documentation Coming Soon
int::setField()
Documentation Coming Soon
int::__sub__()
Used to subtract one integer from another.
Syntax
int A.__sub__(B)
where A and B are integers and B is being subtracted from A.
This function is used under the covers by the - operator; A - B is equivalent to A.__sub__(B).
int::_to_Byte()
Documentation Coming Soon
float::toFloat()
Documentation Coming Soon
int::toJSON()
Documentation Coming Soon
int::_to_JSONObject()
Documentation Coming Soon
3.3. Language Elements
39
Quark Documentation, Release 0.2.8
int::_to_Long()
Documentation Coming Soon
int::_to_Short()
Documentation Coming Soon
int::toString()
Used to cast an integer to a string.
Syntax
int A.toString()
where A is an integer.
List::add()
Used to add a new element to a list. The element is always added to the end of the list.
Syntax
void A.__add__(B)
where A is the list and B is the element to add to the list.
This function is used under the covers by list [] notation; A [ B ] is equivalent to A.__add__(B)
List::__get__()
Used to retrieve the value of a specific element in a list.
Syntax
elementType A.__get__(B)
where elementType is the declared type of list elements, A is the list and B is the 0-based index of the element value to
return.
This function is used under the covers by list [] notation; A [ B ] is equivalent to A.__get__(B)
List::getClass()
Documentation Coming Soon
List::getField()
Documentation Coming Soon
40
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
List::__set__()
Used to modify an existing element in a list.
Syntax
void A.__set__(B,*C*)
where A is the list, B is the 0-based index number of the element to modify, and C is the new value of the element.
This function is used under the covers by list [] notation; A [ B ] = C is equivalent to A.__set__(B,*C*)
List::setField()
Documentation Coming Soon
List::size()
Returns the number of elements in a list.
Syntax
int A.__size__()
where A is the list.
long::__add__()
Used to add two long integers together.
Syntax
long A.__add__(B)
where A and B are long integers.
This function is used under the covers by the + operator; A + B is equivalent to A.__add__(B).
long::__div__()
Used to divide one long integer into another.
Syntax
long A.__div__(B)
where A is the long integer numerator and B is the long integer denominator.
This function is used under the covers by the / operator; A / B is equivalent to A.__div__(B).
3.3. Language Elements
41
Quark Documentation, Release 0.2.8
long::__eq__()
Documentation Coming Soon
long::getClass()
Documentation Coming Soon
long::getField()
Documentation Coming Soon
long::__gt__()
Used to evaluate whether one long integer is greater than another.
Syntax
long A.__gt__(B)
where A and B are long integers. Returns true (1) if A is greater than B and false (0) if A is less than or equal to B.
This function is used under the covers by the > operator; A > B is equivalent to A.__gt__(B).
long::__lt__()
Used to evaluate whether one long integer is less than another.
Syntax
long A.__lt__(B)
where A and B are long integers. Returns true (1) if A is less than B and false (0) if A is greater than or equal to B.
This function is used under the covers by the < operator; A < B is equivalent to A.__lt__(B).
long::__mul__()
Used to multiply two long integers together.
Syntax
long A.__mul__(B)
where A and B are long integers.
This function is used under the covers by the * operator; A * B is equivalent to A.__mul__(B).
42
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
long::__neg__()
Used to flip the sign of a long integer.
Syntax
long A.__neg__()
where A is a long integer.
This function is used under the covers by the - operator; - A is equivalent to A.__neg__().
long::setField()
Documentation Coming Soon
long::__sub__()
Used to subtract one long integer from another.
Syntax
long A.__sub__(B)
where A and B are long integers and B is being subtracted from A.
This function is used under the covers by the - operator; A - B is equivalent to A.__div__(B).
long::toFloat()
Documentation Coming Soon
long::toJSON()
Documentation Coming Soon
long::_to_JSONObject()
Documentation Coming Soon
long::toString()
Used to cast a long integer to a string.
Syntax
long A.toString()
where A is a long integer.
3.3. Language Elements
43
Quark Documentation, Release 0.2.8
Map::contains()
Documentation Coming Soon
Map::__eq__()
Documentation Coming Soon
Map::get()
Documentation Coming Soon
Map::getClass()
Documentation Coming Soon
Map::getField()
Documentation Coming Soon
Map::__ne__()
Documentation Coming Soon
Map::set()
Documentation Coming Soon
Map::getField()
Documentation Coming Soon
Map::update()
Documentation Coming Soon
Object::__eq__()
Documentation Coming Soon
Object::getClass()
Documentation Coming Soon
Object::getField()
Documentation Coming Soon
44
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
Object::__ne__()
Documentation Coming Soon
Object::setField()
Documentation Coming Soon
now()
Returns the current time in UTC milliseconds.
Syntax
void now()
parseInt()
Used to represent a string as a base 10 integer. If rounding is needed, the value is rounded according to the default
rounding rules of the target language.
Syntax
int parseInt(A)
where A is the string to convert.
print()
Used to print strings to stdout. Integers and floats can be printed if passed through toString() first.
Syntax
void print(A)
where A is the string to print.
short::__add__()
Documentation Coming Soon
short::__div__()
Documentation Coming Soon
short::__eq__()
Documentation Coming Soon
3.3. Language Elements
45
Quark Documentation, Release 0.2.8
short::getClass()
Documentation Coming Soon
short::getField()
Documentation Coming Soon
short::__gt__()
Documentation Coming Soon
short::__lt__()
Documentation Coming Soon
short::__mod__()
Documentation Coming Soon
short::__mul__()
Documentation Coming Soon
short::__ne__()
Documentation Coming Soon
short::__neg__()
Documentation Coming Soon
short::setField()
Documentation Coming Soon
short::__sub__()
Documentation Coming Soon
short::toFloat()
Documentation Coming Soon
short::toJSON()
Documentation Coming Soon
46
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
short::toJSONObject()
Documentation Coming Soon
short::toString()
Documentation Coming Soon
sleep()
Used to pause code execution for a specified period of time.
Syntax
void sleep(A)
where A is the number of seconds to halt execution of code.
String::__add__()
Used to concatenate strings.
Syntax
String A.__add__(B)
where A and B are both strings.
This function is used under the covers by the + operator; A + B is equivalent to A.__add__(B).
string::endsWith()
Documentation Coming Soon
string::__eq__()
Documentation Coming Soon
string::find()
Documentation Coming Soon
string::getClass()
Documentation Coming Soon
3.3. Language Elements
47
Quark Documentation, Release 0.2.8
string::getField()
Documentation Coming Soon
string::join()
Documentation Coming Soon
string::__ne__()
Documentation Coming Soon
string::parseJSON()
Documentation Coming Soon
string::replace()
Documentation Coming Soon
string::setField()
Documentation Coming Soon
string::size()
Documentation Coming Soon
string::split()
Documentation Coming Soon
string::startsWith()
Documentation Coming Soon
string::substring()
Documentation Coming Soon
string::toJSON()
Documentation Coming Soon
string::_to_JSONObject()
Documentation Coming Soon
48
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
toJSON()
Documentation Coming Soon
url_get()
Documentation Coming Soon
3.3.7 Annotations
Annotations are compiler directives used to add additional functionality or perform a specific task during code generation.
Unlike most Quark code, annotations do not use the standard end of line character and should not be followed by a
semi-colon (;).
Quark defines the following annotations:
@doc
@doc allows users to specify a description or public comment for packages, classes, properties, methods, and interfaces. The content inside @docs attributions will automatically be included in Javadoc comments for generated Java
code, Sphinx source for generated Python code, and a README.md file for generated Javascript code.
Syntax
@doc( content )
element
where versionNumber is a string representing the version number and element is the language element being described.
Note that there is no semi-colon (;) at the end of the line.
Constraints
Support for automatic documentation generation in Quark is still in its early stages and will be improved in the future.
Some currently known issues include:
• Generated Sphinx source does not include a make file. See linkIssue48 for more information.
• Javadoc does not include content of @doc annotations for methods. See linkIssue46 for more information.
• If not starting from a clean output directory prior to code generation Javadoc may pick up extraneous outdated
content. See linkIssue45 for more information.
• Javascript documentation is very basic and omits many @doc annotations. See linkIssue47 for more information.
[[JMK I have not seen actual generated Sphinx doc; I see a compiler directive to automatically pull content from the
source directory but have not written a make file to generate actual doc to see what gets included so there may also be
missing content]]
3.3. Language Elements
49
Quark Documentation, Release 0.2.8
@version
@version allows users to specify a version for a package or group of packages. If no version is specified, the version
is set to the default “0.0”. Versions will be set in a global pom.xml for all generated Java, a global setup.py for all
generated Python, and package.json inside each Javascript package.
Syntax
@version( versionNumber )
where versionNumber is a string representing the version number. Note that there is no semi-colon (;) at the end of the
line.
Constraints
@version must be defined at the top level of a Quark file. It should be used directly above a package declaration. By
default it applies to all packages defined underneath it in a file. If more than one @version annotation is included in
a Quark file, each annotation applies only to the package it directly proceeds; any package without its own @version
annotation will default to version “0.0”.
@delegate
@delegate allows users to specify an interaction pattern for communications between a client and a server.
Syntax
@delegate( interactionPattern )
where interactionPattern is the name of a defined interaction pattern supported by Quark. Note that there is no semicolon (;) at the end of the line.
Constraints
Quark currently supports only one interaction pattern, rpc, that expects a single request from the client and returns a
single response from the server.
At the current time, the preferred syntax outlined above is not working. For now, use @delegate(self.rpc) instead. See
linkIssue79 for more information.
3.4 More Information
For further information about Quark, see the following:
• The Quark Examples Repository includes a wide variety of examples illustrating both simple language features
and full end-to-end service implementations.
• The Quark Issues List provides a list of known issues - please feel free to add new issues or feature requests as
you start to use Quark.
50
Chapter 3. Quark Language Reference
Quark Documentation, Release 0.2.8
If you have not already read it, the Quark README provides a more general overview of Quark’s features.
If you have not yet installed and tried to use Quark, the Quark Installation and Configuration Guide provides detailed
information about Quark’s requirements as well as installation and compilation instructions.
3.5 Document Version
Quark Language Reference 0.2.8-1
3.5. Document Version
51
Quark Documentation, Release 0.2.8
52
Chapter 3. Quark Language Reference
CHAPTER 4
Indices and tables
• genindex
• modindex
• search
53
Quark Documentation, Release 0.2.8
54
Chapter 4. Indices and tables
CHAPTER 5
Document Version
Quark Documentation Set 0.2.8-1
55