man(1) CTR man page man(1)

NAME

ctr - run a Citrine program

SYNOPSIS

ctr [PROGRAM]

DESCRIPTION

Citrine is general purpose programming language for UNIX-like operating systems.

REFERENCE MANUAL

Citrine has 5 literals:
 
- Nil
 
- Booleans (True, False)
 
- Numbers (1, -2, 3.5)
 
- Strings 'All Strings are UTF8!'
 
- Code Blocks { parameters code }
 
 
The following messages are part of the Core API of the Citrine Programming Language:
 
 
Nil

Nil represents 'nothing' or NULL in other languages.
Any object property that has not been assigned a value
will contain Nil. Unlike some other programming languages
Citrine has no concept of 'undefined' or isset, Nil is actually the
same as 'undefined' or not set.

Literal:

Nil
 
[Nil] isNil

Nil always answers this message with a boolean object 'True'.
 
Object

This is the base object, the parent of all other objects.
It contains essential object oriented programming features.
 
[Object] type

Returns a string representation of the type of object.
 
[Object] equals: [other]

Tests whether the current instance is the same as
the argument.

Alias: =

Usage:
object equals: other
 
[Object] myself

Returns the object itself.
 
[Object] do

Activates 'chain mode'. If chain mode is active, all messages will
return the recipient object regardless of their return signature.

Usage:

a := Array < 'hello' ; 'world' ; True ; Nil ; 666.
a do pop shift unshift: 'hi', push: 999, done.

Because of 'chain mode' you can do 'a do pop shift' etc, instead of

a pop.
a shift.
etc..

The 'do' message tells the object to always return itself and disgard
the original return value until the message 'done' has been received.
 
[Object] done

Deactivates 'chain mode'.
 
[Object] message: [String] arguments: [Array]

Sends a custom or 'dynamic' message to an object. This takes a string containing
the message to be send to the object and an array listing the arguments at the
correct indexes. If the array fails to provide the correct indexes this will
generate an out-of-bounds error coming from the Array object. If something other
than an Array is provided an error will be thrown as well.

Usage:

var str := 'write:'.
Pen message: 'write:' arguments: (Array < 'Hello World').

This will print the string 'Hello world' on the screen using a dynamically
crafted message.
 
[Object] on: [String] do: [Block]

Makes the object respond to a new kind of message.
Use the semicolons to indicate the positions of the arguments to be
passed.

Usage:

object on: 'greet' do: { ... }.
object on: 'between:and:' do: { ... }.

 
[Object] respondTo: [String]

Variations:

[Object] respondTo: [String] with: [String]
[Object] respondTo: [String] with: [String] and: [String]

Default respond-to implemention, does nothing.
 
[Object] isNil

Default isNil implementation.

Always returns boolean object False.
 
Boolean

Literal:

True
False
 
[Boolean] = [other]

Tests whether the other object (as a boolean) has the
same value (boolean state True or False) as the current one.

Usage:

(True = False) ifFalse: { Pen write: 'This is not True!'. }.
 
[Boolean] != [other]

Tests whether the other object (as a boolean) has the
same value (boolean state True or False) as the current one.

Usage:

(True != False) ifTrue: { Pen write: 'This is not True!'. }.
 
[Boolean] toString

Simple cast function.
 
[Boolean] break

Breaks out of the current block and bubbles up to the parent block if
the value of the receiver equals boolean True.

Usage:

(iteration > 10) break. #breaks out of loop after 10 iterations
 
[Boolean] continue

Skips the remainder of the current block in a loop, continues to the next
iteration.

Usage:

(iteration > 10) continue.
 
[Boolean] ifTrue: [block]

Executes a block of code if the value of the boolean
object is True.

Usage:
(some expression) ifTrue: { ... }.

 
[Boolean] ifFalse: [block]

Executes a block of code if the value of the boolean
object is True.

Usage:
(some expression) ifFalse: { ... }.

 
[Boolean] not

Returns the opposite of the current value.

Usage:
True := False not.

 
[Boolean] flip

'Flips a coin'. Returns a random boolean value True or False.

Usage:
coinLandsOn := (Boolean flip).
 
[Boolean] either: [this] or: [that]

Returns argument #1 if boolean value is True and argument #2 otherwise.

Usage:
Pen write: 'the coin lands on: ' + (Boolean flip either: 'head' or: 'tail').
 
[Boolean] & [other]

Returns True if both the object value is True and the
argument is True as well.

Usage:

a & b

 
[Boolean] ! [other]

Returns True if the object value is False and the
argument is False as well.

Usage:

a ! b

 
[Boolean] | [other]

Returns True if either the object value is True or the
argument is True or both are True.

Usage:

a | b
 
[Boolean] ? [other]

Returns True if either the object value is True or the
argument is True but not both.

Usage:

a ? b
 
[Boolean] toNumber

Returns 0 if boolean is False and 1 otherwise.
 
Number

Literal:

0
1
-8
2.5

Represents a number object in Citrine.
 
 
 
[Number] > [other]

Returns True if the number is higher than other number.
 
[Number] >=: [other]

Returns True if the number is higher than or equal to other number.
 
[Number] < [other]

Returns True if the number is less than other number.
 
[Number] <=: [other]

Returns True if the number is less than or equal to other number.
 
[Number] = [other]

Returns True if the number equals the other number.
 
[Number] !=: [other]

Returns True if the number does not equal the other number.
 
[Number] between: [low] and: [high]

Returns True if the number instance has a value between the two
specified values.

Usage:

q between: x and: y
 
[Number] odd

Returns True if the number is odd and False otherwise.
 
[Number] even

Returns True if the number is even and False otherwise.
 
[Number] + [Number]

Adds the other number to the current one. Returns a new
number object.
 
[Number] +=: [Number]

Increases the number ITSELF by the specified amount, this message will change the
value of the number object itself instead of returning a new number.
 
[Number] - [Number]

Subtracts the other number from the current one. Returns a new
number object.
 
[Number] -=: [number]

Decreases the number ITSELF by the specified amount, this message will change the
value of the number object itself instead of returning a new number.
 
[Number] * [Number or Block]

Multiplies the number by the specified multiplier. Returns a new
number object.
 
[Number] times: [Block]

Runs the block of code a 'Number' of times.
This is the most basic form of a loop.

Usage:

7 times: { :i Pen write: i. }.

The example above runs the block 7 times. The current iteration
number is passed to the block as a parameter (i in this example).
 
[Number] *=: [Number]

Multiplies the number ITSELF by multiplier, this message will change the
value of the number object itself instead of returning a new number.

Usage:

x := 5.
x *=: 2. #x is now 10.

Use this message to apply the operation to the object itself instead
of creating and returning a new object.
 
[Number] / [Number]

Divides the number by the specified divider. Returns a new
number object.
 
[Number] /=: [Number]

Divides the number ITSELF by divider, this message will change the
value of the number object itself instead of returning a new number.

Usage:

x := 10.
x /=: 2. #x will now be 5.

Use this message to apply the operation to the object itself instead
of generating a new object.
 
[Number] % [modulo]

Returns the modulo of the number. This message will return a new
object representing the modulo of the recipient.

Usage:

x := 11 % 3. #x will now be 2

Use this message to apply the operation of division to the
object itself instead of generating a new one.
 
[Number] toPowerOf: [power]

Returns a new object representing the
number to the specified power.

Usage:

x := 2 toPowerOf: 8. #x will be 256

The example above will raise 2 to the power of 8 resulting in
a new Number object: 256.
 
[Number] pos

Returns a boolean indicating wether the number is positive.
This message will return a boolean object 'True' if the recipient is
positive and 'False' otherwise.

Usage:

hope := 0.1.
( hope pos ) ifTrue: { Pen write: 'Still a little hope for humanity'. }.

The example above will print the message because hope is higher than 0.
 
[Number] neg

Returns a boolean indicating wether the number is negative.
This message will return a boolean object 'True' if the recipient is
negative and 'False' otherwise. It's the eaxct opposite of the 'positive'
message.

Usage:

hope := -1.
(hope neg) ifTrue: { Pen write: 'No hope left'. }.

The example above will print the message because the value of the variable
hope is less than 0.
 
[Number] max: [other]

Returns the biggest number of the two.

Usage:

x := 6 max: 4. #x is 6
x := 6 max: 7. #x is 7
 
[Number] min: [other]

Returns a the smallest number.

Usage:

x := 6 min: 4. #x is 4
x := 6 min: 7. #x is 7
 
[Number] factorial

Calculates the factorial of a number.
 
[Number] to: [number] step: [step] do: [block]

Runs the specified block for each step it takes to go from
the start value to the target value using the specified step size.
This is basically how you write for-loops in Citrine.

Usage:

1 to: 5 step: 1 do: { :step Pen write: 'this is step #'+step. }.
 
[Number] floor

Gives the largest integer less than the recipient.

Usage:

x := 4.5
y := x floor. #y will be 4

The example above applies the floor function to the recipient (4.5)
returning a new number object (4).
 
[Number] ceil

Rounds up the recipient number and returns the next higher integer number
as a result.

Usage:

x := 4.5.
y = x ceil. #y will be 5

The example above applies the ceiling function to the recipient (4.5)
returning a new number object (5).
 
[Number] round

Returns the rounded number.
 
[Number] abs

Returns the absolute (unsigned, positive) value of the number.

Usage:

x := -7.
y := x abs. #y will be 7

The example above strips the sign off the value -7 resulting
in 7.
 
[Number] sqrt

Returns the square root of the recipient.

Usage:

x := 49.
y := x sqrt. #y will be 7

The example above takes the square root of 49, resulting in the
number 7.
 
[Number] exp

Returns the exponent of the number.
 
[Number] sin

Returns the sine of the number.
 
[Number] cos

Returns the cosine of the number.
 
[Number] tan

Caculates the tangent of a number.
 
[Number] atan

Caculates the arctangent of a number.
 
[Number] log

Calculates the logarithm of a number.
 
[Number] toString

Wrapper for cast function.
 
[Number] toBoolean

Casts a number to a boolean object.
 
String

Literal:

'Hello World, this is a String.'

A sequence of characters. In Citrine, strings are UTF-8 aware.
You may only use single quotes. To escape a character use the
backslash '\' character.

 
 
 
[String] bytes

Returns the number of bytes in a string, as opposed to
length which returns the number of UTF-8 code points (symbols or characters).
 
[String] = [other]

Returns True if the other string is the same (in bytes).
 
[String] != [other]

Returns True if the other string is not the same (in bytes).
 
[String] length

Returns the length of the string in symbols.
This message is UTF-8 unicode aware. A 4 byte character will be counted as ONE.
 
[String] + [other]

Appends other string to self and returns the resulting
string as a new object.
 
[String] append: [String].

Appends the specified string to itself. This is different from the '+'
message, the '+' message adds the specified string while creating a new string.
Appends on the other hand modifies the original string.

Usage:

x := 'Hello '.
x append: 'World'.
Pen write: x. #Hello World

 
[String] from: [position] to: [destination]

Returns a portion of a string defined by from-to values.
This message is UTF-8 unicode aware.

Usage:

'hello' from: 2 to: 3. #ll
 
[String] from: [start] length: [length]

Returns a portion of a string defined by from
and length values.
This message is UTF-8 unicode aware.

Usage:

'hello' from: 2 length: 3. #llo
 
[String] skip: [number]

Returns a string without the first X characters.
 
[String] at: [position]

Returns the character at the specified position (UTF8 aware).
You may also use the alias '@'.

Usage:

('hello' at: 2). #l
('hello' @ 2). #l
 
[String] byteAt: [position]

Returns the byte at the specified position (in bytes).
Note that you cannot use the '@' message here because that will
return the unicode point at the specified position, not the byte.

Usage:
('abc' byteAt: 1). #98
 
[String] indexOf: [subject]

Returns the index (character number, not the byte!) of the
needle in the haystack.

Usage:

'find the needle' indexOf: 'needle'. #9

 
[String] asciiUpperCase

Returns a new uppercased version of the string.
Note that this is just basic ASCII case functionality, this should only
be used for internal keys and as a basic utility function. This function
DOES NOT WORK WITH UTF8 characters !
 
[String] asciiLowerCase

Returns a new lowercased version of the string.
Note that this is just basic ASCII case functionality, this should only
be used for internal keys and as a basic utility function. This function
DOES NOT WORK WITH UTF8 characters !
 
[String] asciiLowerCase1st

Converts the first character of the recipient to lowercase and
returns the resulting string object.
 
[String] asciiUpperCase1st

Converts the first character of the recipient to uppercase and
returns the resulting string object.
 
[String] lastIndexOf: [subject]

Returns the index (character number, not the byte!) of the
needle in the haystack.

Usage:

'find the needle' lastIndexOf: 'needle'. #9
 
[String] replace: [string] with: [other]

Replaces needle with replacement in original string and returns
the result as a new string object.

Usage:

'LiLo BootLoader' replace: 'L' with: 'l'. #lilo Bootloader
 
[String] trim

Trims a string. Removes surrounding white space characters
from string and returns the result as a new string object.

Usage:

' hello ' trim. #hello

The example above will strip all white space characters from the
recipient on both sides of the text. Also see: leftTrim and rightTrim
for variations of this message.
 
[String] leftTrim

Removes all the whitespace at the left side of the string.

Usage:

message := ' hello world '.
message leftTrim.

The example above will remove all the whitespace at the left of the
string but leave the spaces at the right side intact.
 
[String] rightTrim

Removes all the whitespace at the right side of the string.

Usage:

message := ' hello world '.
message rightTrim.

The example above will remove all the whitespace at the right of the
string but leave the spaces at the left side intact.
 
[String] toNumber

Converts string to a number.
 
[String] toBoolean

Converts string to boolean
 
StringSplit

Converts a string to an array by splitting the string using
the specified delimiter (also a string).
 
[String] htmlEscape

Escapes HTML chars.
 
Block

Literal:

{ parameters (if any) here... code here... }

each parameter has to be prefixed with
a colon (:).

Examples:

{ Pen write: 'a simple code block'. } run.
{ :param Pen write: param. } applyTo: 'write this!'.
{ :a :b ^ a + b. } applyTo: 1 and: 2.
{ :a :b :c ^ a + b + c. } applyTo: 1 and: 2 and: 3.

 
[Block] applyTo: [object]

Runs a block of code using the specified object as a parameter.
If you run a block using the messages 'run' or 'applyTo:', me/my will
refer to the block itself instead of the containing object.
 
[Block] whileTrue: [block]

Runs a block of code, depending on the outcome runs the other block
as long as the result of the first one equals boolean True.

Usage:

x := 0.
{ ^(x < 6). } whileFalse:
{ x add: 1. }. #increment x until it reaches 6.

Here we increment variable x by one until it reaches 6.
While the number x is lower than 6 we keep incrementing it.
Don't forget to use the return ^ symbol in the first block.
 
[Block] whileFalse: [block]

Runs a block of code, depending on the outcome runs the other block
as long as the result of the first one equals to False.

Usage:

x := 0.
{ ^(x > 5). }
whileFalse: { x add: 1. }. #increment x until it reaches 6.

Here we increment variable x by one until it reaches 6.
While the number x is not higher than 5 we keep incrementing it.
Don't forget to use the return ^ symbol in the first block.
 
[Block] run

Sending the unary message 'run' to a block will cause it to execute.
The run message takes no arguments, if you want to use the block as a function
and send arguments, consider using the applyTo-family of messages instead.
This message just simply runs the block of code without any arguments.

Usage:

{ Pen write: 'Hello World'. } run. #prints 'Hello World'

The example above will run the code inside the block and display
the greeting.
 
[Block] set: [name] value: [object]

Sets a variable in a block of code. This how you can get closure-like
functionality.

Usage:

shout := { Pen write: (my message + '!!!'). }.
shout set: 'message' value: 'hello'.
shout run.

Here we assign a block to a variable named 'shout'.
We assign the string 'hello' to the variable 'message' inside the block.
When we invoke the block 'shout' by sending the run message without any
arguments it will display the string: 'hello!!!'.

Similarly, you could use this technique to create a block that returns a
block that applies a formula (for instance simple multiplication) and then set the
multiplier to use in the formula. This way, you could create a block
building 'formula blocks'. This is how you implement use closures
in Citrine.
 
[Block] error: [object].

Sets error flag on a block of code.
This will throw an error / exception.
You can attach an object to the error, for instance
an error message.

Example:

{
thisBlock error: 'oops!'.
} catch: { :errorMessage
Pen write: errorMessage.
}, run.
 
[Block] catch: [otherBlock]

Associates an error clause to a block.
If an error (exception) occurs within the block this block will be
executed.

Example:

#Raise error on division by zero.
{
var z := 4 / 0.
} catch: { :errorMessage
Pen write: e, brk.
}, run.
 
[Array] new

Creates a new Array.

Usage:

a := Array new.

or, the short form:

a := Array < 1 ; 2 ; 3.

 
[Array] push: [Element]

Pushes an element on top of the array.

Usage:

numbers := Array new.
numbers push: 3.
 
[Array] min

Returns the minimum value from an array.

Usage:

a := Array < 8 ; 4 ; 2 ; 16.
m := a min. #2

 
[Array] max

Returns the maximum value from an array.

Usage:

a := Array < 8 ; 4 ; 2 ; 16.
m := a max. #16

 
[Array] sum

Takes the sum of an array. This message will calculate the
sum of the numerical elements in the array.

Usage:

a := Array < 1 ; 2 ; 3.
s := a sum. #6

In the example above, the sum of array will be stored in s and
it's value will be 6.
 
[Array] product

Takes the product of an array. On receiving this message, the
Array recipient object will calculate the product of its
numerical elements.

Usage:

a := Array < 2 ; 4 ; 8.
p := a product. #64

In the example above, the product of the array will be calculated
because the array receives the message 'product'. The product of the elements
( 2 * 4 * 8 = 64 ) will be stored in p.
 
[Array] map: [Block].

Iterates over the array. Passing each element as a key-value pair to the
specified block.
The map message will pass the following arguments to the block, the key,
the value and a reference to the array itself. The last argument might seem
redundant but allows for a more functional programming style.

Usage:

files map: showName.
files map: {
:key :filename :files
Pen write: filename, brk.
}.
 
[Array] each: [Block].

Alias for [Array] map: [Block].
 
[Array] < [Element1] ; [Element2] ; ...

Creates a new instance of an array and initializes this
array with a first element, useful for literal-like Array
notations.

Usage:

a := Array < 1 ; 2 ; 3.

Note that the ; symbol here is an alias for 'push:'.
 
[Array] unshift: [Element].

Unshift operation for array.
Adds the specified element to the beginning of the array.

Usage:

a := Array new.
a push: 1.
a unshift: 3. #now contains: 3,1
 
[Array] join: [Glue].

Joins the elements of an array together in a string
separated by a specified glue string.

Usage:

collection := Array new.
collection push: 1, push: 2, push 3.
collection join: ','. # results in string: '1,2,3'
 
[Array] at: [Index]

Returns the element in the array at the specified index.
Note that the fisrt index of the array is index 0.

Usage:

fruits := Array < 'apples' ; 'oranges' ; 'bananas'.
fruits at: 1. #returns 'oranges'
 
[Array] @ [Index]

Alias for [Array] at: [Index]
 
[Array] put: [Element] at: [Index]

Puts a value in the array at the specified index.
Array will be automatically expanded if the index is higher than
the maximum index of the array.

Usage:

fruits := Array new.
fruits put: 'apples' at: 5.
 
[Array] pop

Pops off the last element of the array.
 
[Array] shift

Shifts off the first element of the array.
 
[Array] count

Returns the number of elements in the array.
 
[Array] from: [Begin] length: [End]

Copies part of an array indicated by from and to and
returns a new array consisting of a copy of this region.
 
[Array] + [Array]

Returns a new array, containing elements of itself and the other
array.
 
 
[Array] sort: [Block]

Sorts the contents of an array using a sort block.
Uses qsort.
 
Map

Creates a Map object.

Usage:

files := Map new.
files put: 'readme.txt' at: 'textfile'.
 
[Map] put: [Element] at: [Key]

Puts a key-value pair in a map.

Usage:

map put: 'hello' at: 'world'.

 
[Map] at: [Key]

Retrieves the value specified by the key from the map.
 
[Map] @ [Key]

Alias for [Map] at: [Key].

 
[Map] count

Returns the number of elements in the map.
 
[Map] each: [Block]

Iterates over the map, passing key-value pairs to the specified block.
Note that within an each/map block, 'me' and 'my' refer to the collection.
 
File

Represents a File object.
Creates a new file object based on the specified path.

Usage:

File new: '/example/path/to/file.txt'.
 
[File] path

Returns the path of a file. The file object will respond to this
message by returning a string object describing the full path to the
recipient.
 
[File] read

Reads contents of a file. Send this message to a file to read the entire contents in
one go. For big files you might want to prefer a streaming approach to avoid
memory exhaustion (see readBytes etc).

Usage:

data := File new: '/path/to/mydata.csv', read.

In the example above we read the contents of the entire CSV file callled mydata.csv
in the variable called data.
 
[File] write: [String]

Writes content to a file. Send this message to a file object to write the
entire contents of the specified string to the file in one go. The file object
responds to this message for convience reasons, however for big files it might
be a better idea to use the streaming API if possible (see readBytes etc.).

data := '<xml>hello</xml>'.
File new: 'myxml.xml', write: data.

In the example above we write the XML snippet in variable data to a file
called myxml.xml in the current working directory.
 
[File] append: [String]

Appends content to a file. The file object responds to this message like it
responds to the write-message, however in this case the contents of the string
will be appended to the existing content inside the file.
 
[File] exists

Returns True if the file exists and False otherwise.
 
[File] include

Includes the file as a piece of executable code.
 
[File] delete

Deletes the file.
 
[File] size

Returns the size of the file.
 
[File] open: [string]

Open a file with using the specified mode.

Usage:

f := File new: '/path/to/file'.
f open: 'r+'. #opens file for reading and writing

The example above opens the file in f for reading and writing.
 
[File] close.

Closes the file represented by the recipient.

Usage:

f := File new: '/path/to/file.txt'.
f open: 'r+'.
f close.

The example above opens and closes a file.
 
[File] readBytes: [Number].

Reads a number of bytes from the file.

Usage:

f := File new: '/path/to/file.txt'.
f open: 'r+'.
x := f readBytes: 10.
f close.

The example above reads 10 bytes from the file represented by f
and puts them in buffer x.
 
[File] writeBytes: [String].

Takes a string and writes the bytes in the string to the file
object. Returns the number of bytes actually written.

Usage:

f := File new: '/path/to/file.txt'.
f open: 'r+'.
n := f writeBytes: 'Hello World'.
f close.

The example above writes 'Hello World' to the specified file as bytes.
The number of bytes written is returned in variable n.
 
[File] seek: [Number].

Moves the file pointer to the specified position in the file
(relative to the current position).

Usage:

file open: 'r', seek: 10.

The example above opens a file for reading and moves the
pointer to position 10 (meaning 10 bytes from the beginning of the file).
The seek value may be negative.
 
[File] rewind.

Rewinds the file. Moves the file pointer to the beginning of the file.

Usage:

file open: 'r'.
x := file readBytes: 10. #read 10 bytes
file rewind. #rewind, set pointer to begin again
y := file readBytes: 10. #re-read same 10 bytes

The example above reads the same sequence of 10 bytes twice, resulting
in variable x and y being equal.
 
[File] end.

Moves the file pointer to the end of the file. Use this in combination with
negative seek operations.

Usage:

file open: 'r'.
file end.
x := file seek: -10, readBytes: 10.

The example above will read the last 10 bytes of the file. This is
accomplished by first moving the file pointer to the end of the file,
then putting it back 10 bytes (negative number), and then reading 10
bytes.
 
 
 
 
Broom

GarbageCollector, to invoke use:

[Broom] sweep.
 
[Broom] dust

Returns the number of objects collected.
 
[Broom] objectCount

Returns the total number of objects considered in the latest collect
cycle.
 
[Broom] keptCount

Returns the total number of objects that have been marked during the
latest cycle and have therefore been allowed to stay in memory.
 
[Broom] keptAlloc

Returns the amount of allocated memory.
 
[Broom] stickyCount

Returns the total number of objects that have a sticky flag.
These objects will never be removed.
 
[Broom] memoryLimit

Sets the memory limit, if this limit gets exceeded the program will produce
an out-of-memory error.
 
[Broom] mode: [Number]

Selects mode of operation for GC.

Available Modes:
0 - No Garbage Collection
1 - Activate Garbage Collector
4 - Activate Garbage Collector for every single step (testing only)
 
[Shell] call: [String]

Performs a Shell operation. The Shell object uses a fluid API, so you can
mix shell code with programming logic. For instance to list the contents
of a directory use:

Shell ls

This will output the contents of the current working directly, you
can also pass keyword messages like so:

Shell echo: 'Hello from the Shell!'.

The example above will output the specified message to the console.
Every message you send will be turned into a string and dispatched to
the 'call:' message.
 
 
 
[Program] argument: [Number]

Obtains an argument from the CLI invocation.
 
[Program] argCount

Returns the number of CLI arguments passed to the script.
 
[Program] exit

Exits program immediately.
 
[Program] env: [String]

Returns the value of an environment variable.

Usage:

x := Command env: 'MY_PATH_VAR'.
 
[Program] env: [Key] val: [Value]

Sets the value of an environment variable.
 
[Program] waitForInput

Ask a question on the command-line, resumes program
only after pressing the enter key.
Only reads up to 100 characters.

Usage:

Pen write: 'What is your name ?'.
x := Command waitForInput.
Pen write: 'Hello ' + x + ' !', brk.

The example above asks the user for his/her name and
then displays the input received.
 
[Program] input.

Reads all raw input from STDIN.

Usage (for instance to read raw CGI post):

post := Program input.
 
 
[Program] forbidShell

This method is part of the security profiles feature of Citrine.
This will forbid the program to execute any shell operations. All
external libraries and plugins are assumed to respect this setting as well.

Usage:

Program forbidShell.
 
[Program] forbidFileWrite

This method is part of the security profiles feature of Citrine.
This will forbid the program to modify, create or delete any files. All
external libraries and plugins are assumed to respect this setting as well.

Usage:

Program forbidFileWrite.
 
[Program] forbidFileRead

This method is part of the security profiles feature of Citrine.
This will forbid the program to read any files. In fact this will prevent you from
creating the file object at all.
This will also prevent you from reading environment variables.
All external libraries and plugins are assumed to respect this setting as well.
Forbidding a program to read files also has the effect to forbid including other
source files.

Usage:

Program forbidFileRead.
 
[Program] forbidInclude

This method is part of the security profiles feature of Citrine.
This will forbid the program to include any other files. All
external libraries and plugins are assumed to respect this setting as well.

Usage:

Program forbidInclude.
 
[Program] remainingMessages: [Number]

This method is part of the security profiles feature of Citrine.
This will initiate a countdown for the program, you can specify the maximum quota of
messages the program may process, once this quota has been exhausted the program will
be killed entirely (no exception).

Usage:

Program remainingMessages: 100.
 
[Program] flush.

Flushes the STDOUT output buffer.
 
[Dice] rollWithSides: [Number]

Rolls the dice, generates a pseudo random number.
 
[Dice] roll

Rolls a standard dice with 6 sides.
 
[Dice] rawRandomNumber

Generates a random number, the traditional way (like rand()).
 
[Clock] wait

Waits X seconds.
 
[Clock] time

Returns UNIX epoch time in seconds.
 
[Pen] write: [String]

Writes string to console.
 
[Pen] brk

Outputs a newline character.
 
 
 
 
 
Request get: [string]

Returns the value of the specified GET parameter from the HTTP query string.
For example if the query string of an url is: ?search=glasses
then the value of:

item := Request get: 'search'.

would be 'glasses'.
 
Request getArray: [string].

Returns an array of strings extracted from the query string.
For example if the query string contains: ?option=a&option=b

Request getArray: 'option'.

will contain two elements: 'a' and 'b'. Note that
this also works with array-like notation: ?option[]='a'&option[]=b:

Request getArray: 'option[]'.

will return the same array.
 
Request post: [string].

Obtains a string from the HTTP POST payload. Just like 'get:' but for
POST variables. See 'Request get:' for details.
 
Request postArray: [string].

Obtains an array from the HTTP POST payload. Just like 'getArray:' but for
POST variables. See 'Request getArray:' for details.
 
Request cookie: [string].

Obtains a string from the HTTP COOKIE payload. Just like 'get:' but for
COOKIE variables. See 'Request get:' for details.
 
Request cookieArray: [string].

Obtains an array from the HTTP COOKIE payload. Just like 'getArray:' but for
COOKIE variables. See 'Request getArray:' for details.
 
Request file: [string].

Returns array containing the path to the uploaded temporay file (0) and
the desired name of the uploaded file (1).
 
Request serverOption: [string] is: [string].

Sets a server option, available server option for SCGI server include:

- minidle, minimum number of idle processes
- maxidle, maximum number of idle processes
- maxproc, maximum number of processes
- maxreq, maximum number of concurrent requests to allow

Usage:

Request
serverOption: 'minidle' is: 8,
serverOption: 'maxreq' is: 100.

This sets the minimum number of idle processes to 8 and the
maximum number of concurrent requests to 100, you can chain
multiple options using a comma (,).
 
Request host: [string] listen: [string] pid: [string] callback: [block].

Sets up Storm Server.
Storm Server is an SCGI server. Both the Request Object Plugin and Storm Server
are based on S. Losen's CCGI library (http://libccgi.sourceforge.net/doc.html)
licensed LGPL.

To set up a Storm Server, specify host (i.e. 'localhost'),
a port to listen to (i.e. 9000) a pid file '/var/run/mypid.pid' and a
callback block.

Usage:

Request host:'localhost' listen:4000 pid:'/var/run/storm.pid' callback: {
Pen write: 'Content-type: text/html\n\n'.
var fname := Command env: 'DOCUMENT_URI'.
var script := File new: '/var/www/webapp'+fname.
script include.
}.

Here we set up a server listening to port 4000. The callback prints out
the content type header. Then, we extract the DOCUMENT URI, i.e. '/hello.ctr'
and map this to a path '/var/www/webapp/hello.ctr'

By default there is no output buffering, either create another callback or
simply override the '<' or 'Pen' object to buffer instead of outputting
directly.
 
 

BUGS

This is a preliminary version (< 1.0) of Citrine, there might still be very serious bugs. Please refrain from using this version in a production environment. This version of Citrine is still considered 'alpha' stage and cannot be expected to be reliable.
 

AUTHOR

Gabor de Mooij and the Citrine Community
31 October 2016 1.0