Skip to content

itod/GrafikKonsolDocumentation

master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 

Graphik Konsol Documentation

KonsolSkript Reference



Language

KonsolSkript is a simple, dynamic, interpreted scripting language designed for use in the Grafik Konsol application. KonsolSkript is implemented in Objective-C using a Test-Driven Development style (it has decent test coverage) and is open-source.

KonsolSkript is heavily influenced by several popular languages, including Python, JavaScript and XPath. It is intended to be appropriate for simple graphics scripting, but also for users learning their very first programming language

KonsolSkript is object-based (everthing is an Object), but not (exactly) object-oriented – there is no class construct available to users.

KonsolSkript features functions using the sub construct (short for subroutine). Functions are first-class objects as in Python or JavaScript, and may be treated like any other variable. A function can be passed as an argument to other functions, can be returned by another function and can be assigned as a value to a variable.


Types

The type of any object can be inspected using the type() function, which returns the object's type name as a String.

type(false) // 'Boolean'
type(1.0)   // 'Number'
type('')    // 'String'
type([])    // 'Array'
type({})    // 'Dictionary'
type(sub(){}) // 'Subroutine'

Object

Object is the abstract base class of all objects in KonsolSkript.


null

This type has a single value. There is a single object with this value. This object is accessed through the built-in name null. It is used to signify the absence of a value in many situations, e.g., it is returned from functions that don’t explicitly return anything. Its truth value is false.


Boolean

An object of type Boolean can have one of two values, true and false.

An or expression is evaluated by evaluating each operand and converting its value to a Boolean as if by a call to the Boolean function. The result is true if either value is true and false otherwise. The right operand is not evaluated if the left operand evaluates to true.

An and expression is evaluated by evaluating each operand and converting its value to a Boolean as if by a call to the Boolean function. The result is true if both values are true and false otherwise. The right operand is not evaluated if the left operand evaluates to false.

An EqualityExpr (that is not just a RelationalExpr) or a RelationalExpr (that is not just an AdditiveExpr) is evaluated by comparing the objects that result from evaluating the two operands.

When the operator is <=, <, >= or >, then the objects are compared by converting both objects to numbers and comparing the numbers according to IEEE 754. The < comparison will be true if and only if the first number is less than the second number. The <= comparison will be true if and only if the first number is less than or equal to the second number. The > comparison will be true if and only if the first number is greater than the second number. The >= comparison will be true if and only if the first number is greater than or equal to the second number.


Number

A number represents a floating-point number. A number can have any double-precision 64-bit format IEEE 754 value. These include a special "Not-a-Number" (NaN) value, positive Infinity, and positive and negative zero.

There are three different ways to represent a Number literal. All three types allow underscore separator chars (_) anywhere within the Number literal – these can be used to enhance readability but have no effect on the literal value.

  • Decimal Number literals consist of an optionally signed sequence of digits with an optional decimal point and fractional part.

    42
    -280
    3.14
    47.
    1_000_000
    
  • Hexadecimal Number literals consist of an octothorpe (#) followed by a sequence of case-insensitive hexadecimal digits (0-9, A-F or a-f). This is particularly convenient for specifying hex color values (as in CSS) when calling builtin functions which deal with colors.

    #FFFFFF
    #00CC77
    #00_CC_77
    
  • Binary Number literals consist of a dollar sign ($) followed by a sequence of binary digits (0-1). This is useful for learning bit-fiddling.

    $1111
    $0101_0000
    

Arithmetic may only be performed on two Number operands – The operands of a numeric operator are type-checked at runtime. A TypeError runtime exception is thrown if the first operand is a Number, and the second is not.

The + operator performs addition.

The - operator performs subtraction.

The / operator performs floating-point division according to IEEE 754.

The % operator returns the remainder from a truncating division. For example,

 5 %  2  // 1
 5 % -2  // 1
-5 %  2  // -1
-5 % -2  // -1

NOTE: This is the same as the % operator in Java and ECMAScript.

NOTE: This is not the same as the IEEE 754 remainder operation, which returns the remainder from a rounding division.


String

A String is a sequence of values that represent Unicode code points. All the code points in the range U+0000 - U+10FFFF can be represented in a String. The built-in function ord() converts a code point from its String form to an integer in the range 0 - 10FFFF; chr() converts an integer in the range 0 - 10FFFF to the corresponding length 1 String object.

More documentation is obviously needed here, but KonsolSkript is implemented in Objective-C, so various features of KS String objects will obviously mirror aspects of NSString from Objective-C.

String Literals

String literals are represented with either single or double quotes:

'"Hello", he said.'

"It's ok."

String Formatting

Strings may be concatenated using the + operator, but both operands must be of type String or a TypeError will be thrown at runtime.

String formatting is done using the % operator with a string object on the left-hand side, and a single object or an array of objects on the right-hand side, similar to Python. The available format specifiers are %s, %d, %i, and %f.

'Number: %d' % 1 // 'Number 1'

'Herr %s, Frau %s' % ['Schröder', 'Müller'] // 'Herr Schröder, Frau Müller'

"Float format : %0.2f" % 1.0 // 'Float format : 1.00'

Array

KonsolSkript Arrays are virtually identical to Arrays in Python, with two important differences:

  • KonsolSkript Arrays are 1-index based (like XPath), not 0-index based (like Python).
  • The following syntax (borrowed from PHP) is used for appending an object to an Array in KS:
    var a = ['x'] // create array
    a[] = 'y'     // appends 'y'
    a[] = 'z'     // appends 'z'
    print(a)      // ['x', 'y', 'z']
    

Python-style Array slicing is fully supported in KonsolSkript Arrays (again, with the difference that KS Arrays are 1-index based).

// …continued from above
print(a)      // ['x', 'y', 'z']
print(a[1])   // 'x'
print(a[2])   // 'y'
print(a[-1])  // 'z'
print(a[-2])  // 'y'
print(a[:])   // ['x', 'y', 'z']
print(a[:1])  // 'x'
print(a[3:])  // 'z'
print(a[1:2]) // ['x', 'y']

Arrays may be concatenated using the + operator, but both operands must be of type Array or a TypeError will be thrown at runtime.


Dictionary

KonsolSkript Dictionaries are virtually identical to Dictionaries in Python, with the exception that accessing a key which is not present in the Dictionary returns null rather than throwing an exception.

var d = {'foo': 1}
d['bar'] = 2
print(d)        // {'foo': 1, 'bar': 2}
print(d['baz']) // null

Subroutine

The terms "function" and "subroutine" are used completely interchangeably in the context of KonsolSkript. In this context, "subroutine" simply means "function" (all subroutines/functions may return a value). But the official type name is Subroutine.

Subroutines are first class objects in KonsolSkript, and are very similar to functions in JavaScript as of ECMAScript 5.

sub add(a, b) {
    return a + b
}

add(2, 4) // 6

var f = add

f(3, 5) // 8

var div = sub (a, b) {
    return a / b
}

div(4, 2) // 2

Default parameter values are supported as in Python. Any parameter with a default value is option when calling the function:

sub pow(base, exp=2) {
    return base ** exp
}

pow(4)    // 16
pow(4, 3) // 64

Variable Declarations

Variables are declared with the var keyword.

var foo = 'bar'
var baz = 1.0

Statement Terminators

Statements may be explicitly terminated with a semicolon, or the semicolon may be omitted where new lines are inserted.

var foo = 'bar';

Boolean Logic

Boolean logic is expressed with and, or, not and ! (the last two are synonyms).


Equality

Object equality is tested using == and !=. Object identity is tested using is.


Conditionals / Looping

Curly braces are always required around statements within a conditional or looping construct – even when there is only one such statement.

if

if a > b or b == 0 {
    // …
}

while

while a > b and b != 0 {
    // …
}

for / in

For loops are often used in conjunction with the range() function inspired by Python – with the difference that the resulting iterable object is 1-index based and inclusive.

The following are identical:

for i in range(3) {
    // 1,2,3
}

for i in range(1, 3) {
    // 1,2,3
}

for i in range(1, 3, 1) {
    // 1,2,3
}

For loops can be used with any iterable type – String, Array or Dictionary:

for c in 'abc' {
    // 'a','b','c'
}

for item in ['x', 'y', 'z'] {
    // 'x','y','z'
}

var d = {'foo':1, 'bar':2}
for key,val in d {
    print('%s: %s' % [key, val])
}

Exception Handling

Exception handling is supported via the try / catch / finally construct, very similar to JavaScript.

var resource = checkOut()

try {
    use(resource)
}
catch ex {
    print(ex)
}
finally {
    checkIn(resource)
}

There is currently no "Exception" type. Any "exception" object thrown by the system is a Dictionary with the following string keys:

  • 'name' – the name of the exception type.
  • 'reason' – a message describing why the exception occurred.
  • 'line' – the line number where the exception occurred.

There is also a throw construct available to users for custom exception handling or flow control. Objects of any type may be thrown.

throw 'foo'

Builtin Functions/Subroutines

Name Array()
Description
Syntax Array Array(array?)
Parameters
array? :
Returns Array

Name Boolean()
Description
Syntax Boolean Boolean(object?)
Parameters
object? :
Returns Boolean

Name Dictionary()
Description
Syntax Dictionary Dictionary(dictionary?)
Parameters
dictionary? :
Returns Dictionary

Name Number()
Description
Syntax Number Number(object?)
Parameters
object? :
Returns Number

Name String()
Description
Syntax String String(object?)
Parameters
object? :
Returns String

Name abs()
Description
Syntax Number abs(n)
Parameters
n :
Returns Number

Name acos()
Description
Syntax Number acos(n)
Parameters
n :
Returns Number

Name arc()
Description
Syntax Void arc(x, y, radius, startAngle, endAngle, clockwise)
Parameters
x :
y :
radius :
startAngle :
endAngle :
clockwise :
Returns Void

Name asin()
Description
Syntax Number asin(n)
Parameters
n :
Returns Number

Name assert()
Description
Syntax Void assert(test, message?)
Parameters
test :
message? :
Returns Void

Name atan()
Description
Syntax Number atan(n)
Parameters
n :
Returns Number

Name atan2()
Description
Syntax Number atan2(y, x)
Parameters
y :
x :
Returns Number

Name background()
Description
Syntax Void background(color?)
Parameters
color? :
Returns Void

Name bezier()
Description
Syntax Void bezier(x1, y1?, x2?, y2?, x3?, y3?, x4?, y4?)
Parameters
x1 :
y1? :
x2? :
y2? :
x3? :
y3? :
x4? :
y4? :
Returns Void

Name ceil()
Description
Syntax Number ceil(n)
Parameters
n :
Returns Number

Name chr()
Description
Syntax String chr(number)
Parameters
number :
Returns String

Name compare()
Description
Syntax Number compare(lhs, rhs)
Parameters
lhs :
rhs :
Returns Number

Name contains()
Description
Syntax Boolean contains(rectArray, pointArray, rectMode?)
Parameters
rectArray :
pointArray :
rectMode? :
Returns Boolean

Name copy()
Description
Syntax Object copy(object)
Parameters
object :
Returns Object

Name cos()
Description
Syntax Number cos(n)
Parameters
n :
Returns Number

Name count()
Description
Syntax Number count(sequence)
Parameters
sequence :
Returns Number

Name degrees()
Description
Syntax Number degrees(radians)
Parameters
radians :
Returns Number

Name description()
Description
Syntax String description(object)
Parameters
object :
Returns String

Name ellipse()
Description
Syntax Void ellipse(x, y?, width?, height?)
Parameters
x :
y? :
width? :
height? :
Returns Void

Name ellipseMode()
Description
Syntax Void ellipseMode(mode)
Parameters
mode :
Returns Void

Name exit()
Description
Syntax Void exit()
Parameters
Returns Void

Name fill()
Description
Syntax Void fill(r, g?, b?, a?)
Parameters
r :
g? :
b? :
a? :
Returns Void

Name filter()
Description
Syntax Array filter(array, function)
Parameters
array :
function :
Returns Array

Name floor()
Description
Syntax Number floor(n)
Parameters
n :
Returns Number

Name frameRate()
Description
Syntax Void frameRate(frameRate)
Parameters
frameRate :
Returns Void

Name globals()
Description
Syntax Dictionary globals()
Parameters
Returns Dictionary

Name isNaN()
Description
Syntax Boolean isNaN(n)
Parameters
n :
Returns Boolean

Name line()
Description
Syntax Void line(x1, y1?, x2?, y2?)
Parameters
x1 :
y1? :
x2? :
y2? :
Returns Void

Name locals()
Description
Syntax Dictionary locals(recurse?)
Parameters
recurse? :
Returns Dictionary

Name log()
Description
Syntax Number log(n)
Parameters
n :
Returns Number

Name loop()
Description
Syntax Void loop(shouldLoop)
Parameters
shouldLoop :
Returns Void

Name lowercase()
Description
Syntax String lowercase(string)
Parameters
string :
Returns String

Name map()
Description
Syntax Array map(array, function)
Parameters
array :
function :
Returns Array

Name matches()
Description
Syntax Boolean matches(input, pattern, flags?)
Parameters
input :
pattern :
flags? :
Returns Boolean

Name max()
Description
Syntax Number max(a, b?)
Parameters
a :
b? :
Returns Number

Name min()
Description
Syntax Number min(a, b?)
Parameters
a :
b? :
Returns Number

Name noFill()
Description
Syntax Void noFill()
Parameters
Returns Void

Name noStroke()
Description
Syntax Void noStroke()
Parameters
Returns Void

Name ord()
Description
Syntax Number ord(string)
Parameters
string :
Returns Number

Name popStyle()
Description
Syntax Void popStyle()
Parameters
Returns Void

Name position()
Description
Syntax Number position(sequence, object, compareIdentity?)
Parameters
sequence :
object :
compareIdentity? :
Returns Number

Name print()
Description
Syntax Void print(object)
Parameters
object :
Returns Void

Name pushStyle()
Description
Syntax Void pushStyle()
Parameters
Returns Void

Name radians()
Description
Syntax Number radians(degrees)
Parameters
degrees :
Returns Number

Name random()
Description
Syntax Number random(low, high?)
Parameters
low :
high? :
Returns Number

Name range()
Description
Syntax Array range(a, b?, step?)
Parameters
a :
b? :
step? :
Returns Array

Name rect()
Description
Syntax Void rect(x, y?, width?, height?)
Parameters
x :
y? :
width? :
height? :
Returns Void

Name rectMode()
Description
Syntax Void rectMode(mode)
Parameters
mode :
Returns Void

Name redraw()
Description
Syntax Void redraw()
Parameters
Returns Void

Name replace()
Description
Syntax String replace(input, pattern, replacement, flags?)
Parameters
input :
pattern :
replacement :
flags? :
Returns String

Name repr()
Description
Syntax String repr(object)
Parameters
object :
Returns String

Name rotate()
Description
Syntax Void rotate(radians)
Parameters
radians :
Returns Void

Name round()
Description
Syntax Number round(n)
Parameters
n :
Returns Number

Name scale()
Description
Syntax Void scale(width, height?)
Parameters
width :
height? :
Returns Void

Name sin()
Description
Syntax Number sin(n)
Parameters
n :
Returns Number

Name size()
Description
Syntax Void size(width, height?)
Parameters
width :
height? :
Returns Void

Name sleep()
Description
Syntax Object sleep(seconds)
Parameters
seconds :
Returns Object

Name sort()
Description
Syntax Void sort(array, function?)
Parameters
array :
function? :
Returns Void

Name sqrt()
Description
Syntax Number sqrt(n)
Parameters
n :
Returns Number

Name stroke()
Description
Syntax Void stroke(r, g?, b?, a?)
Parameters
r :
g? :
b? :
a? :
Returns Void

Name strokeCap()
Description
Syntax Void strokeCap(type)
Parameters
type :
Returns Void

Name strokeJoin()
Description
Syntax Void strokeJoin(type)
Parameters
type :
Returns Void

Name strokeWeight()
Description
Syntax Void strokeWeight(weight)
Parameters
weight :
Returns Void

Name sum()
Description
Syntax Number sum(sequence)
Parameters
sequence :
Returns Number

Name tan()
Description
Syntax Number tan(n)
Parameters
n :
Returns Number

Name translate()
Description
Syntax Void translate(x, y?)
Parameters
x :
y? :
Returns Void

Name trim()
Description
Syntax String trim(string)
Parameters
string :
Returns String

Name type()
Description
Syntax String type(object)
Parameters
object :
Returns String

Name uppercase()
Description
Syntax String uppercase(string)
Parameters
string :
Returns String

About

Grafik Konsol Documentation

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published