Candle System Routines Reference

Routines without side-effects are called functions, and routines with side-effects are called methods; methods can call functions, but not vice-versa; this is called separation of side-effects in Candle;
Candle supports routine overloading based on the number of arguments and routine type (i.e. whether it is an expression function, statement function of method);

This document specifies the list of built-in routines that are supported in Candle.

Some of the namespaces that shall be used In this reference document are:

namespace
c=candle:core, m=candle:math,
io=candle:io, f=candle:io:file, sql=candle:data:sql;

2. Build-in Core Functions

The built-in core functions in Candle are defined under namespace candle.core. In Candle, function name without prefix is always resolved under this core namespace. Unlike XQuery, this default routine namespace cannot be changed by user.

2.1 Aggregate Functions

Aggregation functions can apply to a sequence of items. If any of the item in the sequence is a measure, then all of the items in the sequence should be measures having the same unit. In current version, Candle does not support casting from one measure type to another.

2.1.1 function count()

function count(arg as
item*) as integer;

Summary: Returns the number of items in the value of arg. Returns 0 if arg is the empty sequence.

Examples

Assume seq1 = (), the empty sequence and seq2 = (98.5, 98.3, 98.9).

count(seq1) returns 0.
count(seq2) returns 3.
count(seq2[. > 100]) returns 0.

2.1.2 function avg()

function avg(arg as item*)
as atomic;

Summary: Returns the average of the values in the input sequence arg, that is, the sum of the values divided by the number of values. If arg is the empty sequence, the empty sequence is returned. In current beta release, only numeric and measure types are supported.

Examples

Assume seq = (3, 4, 5).

avg(seq) returns 4.0.
avg(()) returns ().
avg((3pt, 5.6pt, 7pt)) returns 5.2pt;

2.1.3 function max()

function max(arg as item*)
as item;

Summary: Returns the item with the maximum value in the sequence arg. If arg is the empty sequence, the empty sequence is returned. In current beta release, only numeric and measure types are supported.

Examples

max((3,4,5)) returns 5.
max((5, 5.0e0)) returns 5.0e0.
max((today(), 't:2001-01-01'))) is not supported in current beta release.
max(("a", "b", "c")) is not supported in current beta release.

2.1.4 function min()

function min(arg as item*)
as item;

Summary: Returns the item with the minimum value in the sequence arg. If arg is the empty sequence, the empty sequence is returned. In current beta release, only numeric and measure types are supported.

Examples

min((3,4,5)) returns 3.
min((5, 5.0e0)) returns 5.0e0.
max((today(), 't:2001-01-01'))) is not supported in current beta release.
max(("a", "b", "c")) is not supported in current beta release.

2.1.5 function sum()

function sum(arg as item*)
as atomic;

Summary: Returns a value obtained by adding together the values in arg. The value returned for an empty sequence is the integer value 0. In current beta release, only numeric and measure types are supported.

Examples

sum((3, 4, 5)) returns 12.
sum(()) returns 0.
sum((3pt, 5.6pt, 7pt)) returns 15.6pt;

2.2 String Functions

Note: In Candle, the first character of a string is located at position 1, not position 0. This is the same as XQuery, but different from many other programming languages.

2.2.1 function contain()

function contain(arg1 as
string, arg2 as string) as boolean;

Summary: Returns an boolean indicating whether or not the value of arg1 contains (at the beginning, at the end, or anywhere within) at least one sequence of collation units that provides a minimal match to the collation units in the value of arg2, according to the collation that is used.

If the value of arg1 or arg2 is the empty sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.

If the value of arg2 is the zero-length string, then the function returns true. If the value of arg1 is the zero-length string, the function returns false.

Examples

contain("candle", "c") returns true.
contain("candle", "ccc") returns false.
contain("", ()) returns true. The first rule is applied, followed by the second rule.

2.2.2 function start-with()

function start-with(arg1 as
string, arg2 as string) as boolean;

Summary: Returns an boolean indicating whether or not the value of arg1 starts with a sequence of collation units that provides a match to the collation units of arg2 according to the collation that is used.

If the value of arg1 or arg2 is the empty sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.

If the value of arg2 is the zero-length string, then the function returns true. If the value of arg1 is the zero-length string and the value of arg2 is not the zero-length string, then the function returns false.

Examples

start-with("candle", "can") returns true.
start-with("candle", "cant") returns false.
start-with((), ()) returns true.

2.2.3 function end-with()

function end-with(arg1 as
string, arg2 as string) as boolean;

Summary: Returns an xs:boolean indicating whether or not the value of arg1 starts with a sequence of collation units that provides a match to the collation units of arg2 according to the collation that is used.

If the value of arg1 or arg2 is the empty sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.

Examples

end-with("candle", "candle") returns true.
end-with("candle", "del") returns false.
end-with((), ()) returns true.

2.2.4 function substring-before()

function
substring-before(arg1
as string, arg2 as string) as string;

Summary: Returns the substring of the value of arg1 that precedes in the value of arg1 the first occurrence of a sequence of collation units that provides a minimal match to the collation units of arg2 according to the collation that is used.

If the value of arg1 or arg2 is the empty sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.

If the value of arg2 is the zero-length string, then the function returns the zero-length string. If the value of arg1 does not contain a string that is equal to the value of arg2, then the function returns the zero-length string.

Examples

substring-before("candle", "and") returns "c".
substring-before("candle", "can") returns "".
substring-before((), ()) returns "".

2.2.5 function substring-after()

function substring-after(arg1
as string, arg2 as string) as
string;

Summary: Returns the substring of the value of arg1 that follows in the value of arg1 the first occurrence of a sequence of collation units that provides a minimal match to the collation units of arg2 according to the collation that is used.

If the value of arg1 or arg2 is the empty sequence, or contains only ignorable collation units, it is interpreted as the zero-length string.

If the value of arg2 is the zero-length string, then the function returns the value of arg1. If the value of arg1 does not contain a string that is equal to the value of arg2, then the function returns the zero-length string.

Examples

substring-after("candle", "can") returns "dle".
substring-after("candle", "candle") returns "".
substring-after((), ()) returns "".

2.2.6 function substring()

function substring(source-string
as string, starting-loc as integer) as
string;

function substring(source-string as
string, starting-loc as
integer, length as integer) as string;

Summary: Returns the portion of the value of source-string beginning at the position indicated by the value of starting-loc and continuing for the number of characters indicated by the value of length. The characters returned do not extend beyond source-string. If starting-loc is zero or negative, only those characters in positions greater than zero are returned.

More specifically, the three argument version of the function returns the characters in source-string whose position p obeys:

m:round(startingLoc) <= p < m:round(startingLoc) + m:round(length)

The two argument version of the function assumes that length is infinite and returns the characters in source-string whose position p obeys:

m:round(startingLoc) <= p < m:round(INF)

If the value of source-string is the empty sequence, the zero-length string is returned.

Note: The first character of a string is located at position 1, not position 0.

Examples

substring("motor car", 6) returns " car". Characters starting at position 6 to the end of sourceString are selected.
substring("metadata", 4, 3) returns "ada". Characters at positions greater than or equal to 4 and less than 7 are selected.
substring("12345", 1.5, 2.6) returns "234". Characters at positions greater than or equal to 2 and less than 5 are selected.
substring("12345", 0, 3) returns "12". Characters at positions greater than or equal to 0 and less than 3 are selected. Since the first position is 1, these are the characters at positions 1 and 2.
substring("12345", 5, -3) returns "". Characters at positions greater than or equal to 5 and less than 2 are selected.
substring("12345", -3, 5) returns "1". Characters at positions greater than or equal to -3 and less than 2 are selected. Since the first position is 1, this is the character at position 1.
substring((), 1, 3) returns "".

2.2.7 function index-of()

function index-of(source as
string, target as string) as integer;

function index-of(source as string, target as
string, starting-index as int) as integer;

Summary: Returns a positive integers giving the position of the first occurrence of target string within the source string. Optional parameter starting-index specifies the starting position of the search.

Note: The first character of a string is located at position 1, not position 0.

2.2.8 function uppercase()

function uppercase(arg as
string) as string;

Summary: Returns the value of arg after translating every character to its upper-case correspondent.

Examples

uppercase("abCd0") returns "ABCD0".

2.2.9 function lowercase()

function lowercase(arg as
string) as string;

Summary: Returns the value of arg after translating every character to its lower-case correspondent.

Examples

lowercase("ABc!D") returns "abc!d".

2.2.10 function trim()

function trim(arg as
string) as string;

Summary: Returns the value of arg after trimming the starting and trailing whitespace characters, including space, tab, line-feed and carriage-return.

2.2.11 function string-length()

function string-length(arg
as
string) as integer;

Summary: Returns an integer equal to the length in characters of the value of arg.

Examples

string-length("Harp not on that string, madam; that is past.") returns 45.
string-length(()) returns 0.

2.2.12 function replace()

function replace(input as
string, target as string, replacement as
string) as string;

Summary: Returns the value of input after replacing every occurance of substring target with replacement.

Examples

replace("abracadabra", "bra", "*") returns "a*cada*"

2.2.13 function translate()

function translate(arg as
string, map-string as string, trans-string as
string) as string;

Summary: Returns the value of arg modified so that every character in the value of arg that occurs at some position N in the value of map-string has been replaced by the character that occurs at position N in the value of trans-string.

If the value of arg is the empty sequence, the zero-length string is returned.

Every character in the value of arg that does not appear in the value of map-string is unchanged.

Every character in the value of arg that appears at some position M in the value of map-string, where the value of trans-string is less than M characters in length, is omitted from the returned value. If map-string is the zero-length string arg is returned.

If a character occurs more than once in map-string, then the first occurrence determines the replacement character. If trans-string is longer than map-string, the excess characters are ignored.

Examples

translate("bar","abc","ABC") returns "BAr"
translate("--aaa--","abc-","ABC") returns "AAA".
translate("abcdabc", "abc", "AB") returns "ABdAB".

2.2.14 function tokenize()

function tokenize(input as
string) as item*;

function tokenize(input as string, pattern as string) as item*;

Summary: This function breaks the input string into a sequence of strings, treating any substring that matches pattern as a separator. The separators themselves are not returned. When the optional parameter pattern is not specified, whitespace characters, including space, tab, line-feed and carriage-return, are treated as the separator.

If input is the empty sequence, or if input is the zero-length string, the result is the empty sequence.

Examples

tokenize("The cat sat on the mat.") returns ("The", "cat", "sat", "on", "the", "mat.")

2.3 Datetime Routines

2.3.1 routine now()

function now() as date-time;

method
now() as date-time;

Summary: Returns the current local datetime from the dynamic context. Note that there are two versions. One is functional and the other is procedural. The functional now() returns the value of the timestamp that is stored in the dynamic context. The procedural now() updates the timestamp in the dynamic context to the latest system time and returns this updated date-time. The timestamp in the dynamic context is initialized when the query starts, and may be updated later by the procedural now() call. The functional now() is similar to XQuery fn:current-dateTime(). The difference is that Candle returns local time, whereas fn:current-dateTime()returns datetime with timezone.

Examples

now() returns an date-time corresponding to the current date and time. For example, an invocation of now() might return 2004-05-12T18:17:15.125 corresponding to the current time on May 12, 2004.

2.3.2 routine today()

function today() as date;

method
today() as date;

Summary: Returns the current date. Note that there are two versions. One is functional and the other is procedural. The functional today() returns the date of the timestamp that is stored in the dynamic context. The procedural today() updates the timestamp in the dynamic context to the latest system time and returns this updated date. The timestamp accessed by today() is the same as the timestamp accessed by now(). The functional today() is similar to XQuery fn:current-date(). The difference is that Candle returns local time, whereas

fn:current-date()

returns date with timezone.

Examples

today() returns an date corresponding to the current date and time. For example, an invocation of today() might return 2004-05-12.

2.4 Value Constructors

2.4.1 function number()

function number(source as
string) as numeric;

Summary: This function parse the source string and converts it into the corresponding number is possible.

Examples

number("123.5") returns 123.5.

2.4.2 function color()

function color(red as
int, green as int, blue as int)
as color;

Summary: This function constructs an color based on the specified red, green, blue value of the color. The red, green and blue values should be in the range from 0 to 255 inclusive.

2.4.3 function qname()

2.5 Other Core Routines

2.5.1 function not()

function not(arg as item*)
as boolean;

Summary: arg is first reduced to an effective boolean value. Then returns true if the effective boolean value is false, and false if the effective boolean value is true. This function is similar to fn:not() in XQuery.

Examples

not(true) returns false.
not(false) returns false.

2.5.2 function exist()

function exist(arg as
item*) as boolean;

Summary: If the value of arg is not the empty sequence, the function returns true; otherwise, the function returns false. This function is similar to fn:exists() in XQuery.

Examples

exist(<elmt/>/@*) returns false.

2.5.3 function deep-equal()

function deep-equal(source
as item, target as item) as boolean;

Summary: This function assesses whether two sequences are deep-equal to each other. To be deep-equal, they must contain items that are pairwise deep-equal; and for two items to be deep-equal, they must either be atomic values that compare equal, or nodes of the same kind, with the same name, whose children are deep-equal. This is defined in more detail below. This function is similar to XQuery fn:deep-equal() function.

If the two sequences are both empty, the function returns true.

If the two sequences are of different lengths, the function returns false.

If the two sequences are of the same length, the function returns true if and only if every item in the sequence parameter1 is deep-equal to the item at the same position in the sequence parameter2. The rules for deciding whether two items are deep-equal follow.

Call the two items i1 and i2 respectively.

If i1 and i2 are both atomic values, they are deep-equal if and only if (i1 == i2) is true, or if both values are NaN. If the eq operator is not defined for i1 and i2, the function returns false.

If one of the pair i1 or i2 is an atomic value and the other is a node, the function returns false.

If i1 and i2 are both nodes, they are compared as described below:

If the two nodes are of different kinds, the result is false.

If the two nodes are both document nodes then they are deep-equal if and only if the sequence i1/(*|text()) is deep-equal to the sequence i2/(*|text()).

If the two nodes are both element nodes then they are deep-equal if and only if all of the following conditions are satisfied:

the two nodes have the same name, that is (qname(i1) == qname(i2)).
the two nodes are both annotated as having simple content or both nodes are annotated as having complex content.
the two nodes have the same number of attributes, and for every attribute a1 in i1/@* there exists an attribute a2 in i2/@* such that a1 and a2 are deep-equal.
One of the following conditions holds:
- Both element nodes have a type annotation that is simple content, and the typed value of i1 is deep-equal to the typed value of i2.
- Both element nodes have a type annotation that is complex content with elementOnly content, and each child element of i1 is deep-equal to the corresponding child element of i2.
- Both element nodes have a type annotation that is complex content with mixed content, and the sequence i1/(*|text()) is deep-equal to the sequence i2/(*|text()).
- Both element nodes have a type annotation that is complex content with empty content.

If the two nodes are both attribute nodes then they are deep-equal if and only if both the following conditions are satisfied:

the two nodes have the same name, that is (qname(i1) == qname(i2)).
the typed value of i1 is deep-equal to the typed value of i2.

If the two nodes are both processing instruction nodes, then they are deep-equal if and only if both the following conditions are satisfied:

the two nodes have the same name, that is (qname(i1) == qname(i2)).
the string value of i1 is equal to the string value of i2.

If the two nodes are both namespace nodes, then they are deep-equal if and only if both the following conditions are satisfied:

the two nodes either have the same name or are both nameless, that is deep-equal(qname(i1), qname(i2)).
the string value of i1 is equal to the string value of i2 when compared using the Unicode codepoint collation.

If the two nodes are both text nodes or comment nodes, then they are deep-equal if and only if their string-values are equal.

Notes:

The two nodes are not required to have the same type annotation, and they are not required to have the same in-scope namespaces. They may also differ in their parent, their base URI. The order of children is significant, but the order of attributes is insignificant.

The contents of comments and processing instructions are significant only if these nodes appear directly as items in the two sequences being compared. The content of a comment or processing instruction that appears as a descendant of an item in one of the sequences being compared does not affect the result. However, the presence of a comment or processing instruction, if it causes a text node to be split into two text nodes, may affect the result.

The result of deep-equal(1, now()) is false; it does not raise an error.

Examples

Assume

at =
<attendees> <name last='Parker'
first='Peter'/> <name last='Barker' first='Bob'/> <name
last='Parker' first='Peter'/> </attendees>

deep-equal(at, at/*) returns false.
deep-equal(at/name[1], at/name[2]) returns false.
deep-equal(at/name[1], at/name[3]) returns true.
deep-equal(at/name[1], 'Peter Parker') returns false.

2.5.4 function position()

Returns the context position, same as defined in XQuery.

2.5.5 function size()

Returns the context size, same as last() function in XQuery.

2.5.6 function parse()

function parse(source
as
string) as node*;

function parse(source
as
string, mime-format as qname) as node*;

Summary: This function parse the source string based on the specified MIME format and returns the result as a sequence of nodes. If the MIME format is omitted, it is default to Candle Markup, i.e. c:markup. The supported MIME formats are:

MIME Qname	MIME Description
`c:markup`	- Candle Markup
`c:script`	- Candle Script
`c:xml`	- XML
`c:xhtml`	- XHTML
`c:html`	- HTML
`c:url-encoded`	- URL encoded query string or form data
`c:json`	- JSON

2.5.7 function xparse()

function xparse(source as
string, grammar-name as qname) as
element;

Summary: This function parse the source string based on the grammar with grammar-name, and returns the result AST (abstract syntax tree) as an element.

2.5.8 function eval()

function eval(source as
string) as item*;

Summary: This function parse the source string as Candle expression, and then evaluate the parsed expression and returns the result as a sequence of items. The source is parsed relative to the script containing this eval() call, for example to resolve any function call in the source string.

Examples

eval("sum(1 to 100)") returns 5050.

2.5.9 function call()

function call(scriptUri as
string, expressionFuncName as qname)
as item*;

function call(scriptUri as string, expressionFuncName as
qname, param as item*) as item*;

function call(scriptUri as string, statementFuncName as qname);

function call(scriptUri as string, statementFuncName as
qname, param
as item*);

method call(scriptUri as string, methodName as qname) as item*;

method call(scriptUri as string, methodName as
qname, param
as
item*) as item*;

Summary: This group of routines dynamically invoke the corresponding function or method defined in a script at scriptUri. The return value from the invoked function of method is returned as the return value of this call() function.

2.5.10 function result()

function result()
as item*;

Summary: This function returns the return value of the last method call in current thread.

2.6 Debugging Routines

2.6.1 routine assert()

function assert(expr) as
empty;

function assert(expr);

method assert(expr) as empty;

Summary: This group of routines check the value of the expr at runtime. If the value is true, the execution continues normally. If the value is false, the execution is suspended; if Candle is running in desktop mode, then a popup windows containing an error message is shown; if Candle is running in other modes, then the error message is written to the system log file. The execution continues after the popup window is dismissed. As the routines return empty value, you can nest them anywhere in your script and even leave them in production scripts.

2.6.2 routine log()

function log(expr) as empty;

function log(expr);

method log(expr) as empty;

Summary: This group of routines logs the string value of the expr to the system log file. As the routines return empty value, you can nest them anywhere in your script and even leave them in production scripts.

2.6.3 routine alert()

function alert(expr) as
empty;

function alert(expr);

method alert(expr) as empty;

Summary: This group of routines firstly suspend execution when invoked. If Candle is running in desktop mode, then a popup windows is shown containing the string value of the expr; if Candle is running in other modes, then the string value is written to the system log file.

3. Math Functions

Math functions are defined under namespace candle.math.

3.1 Basic Functions

3.1.1 function m:abs()

function m:abs(x as double)
as double;

Summary: Returns the absolute value of x.

3.1.2 function m:floor()

function m:floor(x as
double) as double;

Summary: Returns x, rounded downwards to the nearest integer.

3.1.3 function m:ceil()

function m:ceil(x as
double) as double;

Summary: Returns x, rounded upwards to the nearest integer.

3.1.4 routine m:random()

function m:random(seed as
decimal) as
double;

method


m:random() as
double;

Summary: Returns a floating-point, pseudo-random number in the range

[0,
1)

that is, from 0 (inclusive) up to but not including 1 (exclusive), which you can then scale to your desired range. For the functional random(), you need to pass in the seed explicitly. For the procedural random(), the random number generator is seeded from the current time.

3.2 Power and Exponential Functions

3.2.1 function m:sqrt()

function m:sqrt(x as
double) as double;

Summary: Returns the square root of x.

3.2.2 function m:pow()

function m:pow(base as
double, exponent) as double;

Summary: Returns base raised to the power exponent.

3.2.3 function m:exp()

function m:exp(x as double)
as double;

Summary: Returns the base-e exponential function of x, which is the e number raised to the power x.

3.2.4 function m:log()

function m:log(x as double)
as double;

Summary: Returns the base-e natural logarithm of x.

3.2.5 function m:log10()

function m:log10(var as
double) as double;

Summary: Returns the common (base-10) logarithm of x.

3.3 Trigonometric Functions

3.3.1 function m:sin()

function m:sin(x as double)
as double;

Summary: Returns the sine of x (x is in radians).

3.3.2 function m:cos()

function m:cos(x as double)
as double;

Summary: Returns the cosine of x (x is in radians).

3.3.3 function m:tan()

function m:tan(x as double)
as double;

Summary: Returns the tangent of an angle of x radians.

3.3.4 function m:asin()

function m:asin(x as
double) as double;

Summary: Returns the principal value of the arc sine of x, expressed in radians.

3.3.5 function m:acos()

function m:acos(x as
double) as double;

Summary: Returns the principal value of the arc cosine of x, expressed in radians.

3.3.6 function m:atan()

function m:atan(x as
double) as double;

Summary: Returns the principal value of the arc tangent of x, expressed in radians.

4. I/O Routines

4.1 Standard I/O Routines

4.1.1 function io:input()


function io:input(arg as string) as document;

Summary: Retrieves a document using a URI supplied as an string, and returns the corresponding document node. This function is similar to XQuery fn:doc() function.

If uri is the empty sequence, the result is an empty sequence.

If uri is not a valid URI, an error may be raised.

If uri is a relative URI reference, it is resolved relative to the value of the base URI property from the static context, which by default is the URI of the current script. The resulting absolute URI is promoted to an string.

This function detects the MIME type of the document based on the file extension:

File Extension	File Type
.cmk	Candle Markup
.xml, .xhtml, .xsl	XML Document
.htm, .html	HTML Document
.csv	CSV Document
any other extesions	Plain Text Document

4.1.2 method io:output()

method io:output(arg as
node);

Save the document that contains the arg node back to it original location. It cannot be used with a document that is constructed dynamically.

method io:output(arg as
node, file-uri as uri);


method io:output(arg as node, file-uri as uri, format
as
qname);

Output the arg node to the specified location. The arg has to be a document node or an element node. If the format is specified, then the document is written based on that format; otherwise, the format is defaulted to be Candle Markup.

file-uri can only be a local file URI. If the URI is relative, it is resolved relative to the value of the base URI property from the static context, which by default is the URI of the current script.

4.1.3 method io:exec()

method io:exec(cmd as
string) as string;

method
io:exec(cmd as string, blocking as boolean) as
string;

This method spawns a child process to execute the cmd with the native OS shell and returns the entire output from the command as a string.

The optional parameter blocking tells whether the command should be executed in blocking or non-blocking mode. Under blocking mode, Candle runtime waits for the command to terminate to return the output. Under non-blocking mode, Candle runtime returns immediately after spawning the child process; the return value is always empty under this mode.

4.1.4 method io:popen()

method io:popen(cmd as
string) as item;

This method spawns a child process to execute the cmd with the native OS shell. A pipe is return to return output from the command.

Unless you want to process the command output in a line by line manner, it is more convenient to just use io:exec() method instead.

4.1.5 method io:open()

method io:open(file-uri as
uri, mode as string) as

item

This method opens a file at the location specified by file-uri under the specified mode.

file-uri can only be a local file URI. If the URI is relative, it is resolved relative to the value of the base URI property from the static context, which by default is the URI of the current script.

The mode parameter can take 3 value: "r" for read mode; "w" for write mode; and "a" for append mode.

4.1.6 method io:readln()

method io:readln() as string;

This method reads a line of input text from the standard input (STDIN) of the program and puts it as the return value. If Candle runs under desktop mode, the standard input is not available, and this method will always return empty.

method io:readln(stream
as

item

)
as string;

This method reads a line of input text from the given stream, either returned from io:popen() or io:open().

4.1.7 method io:write()

method io:write(arg as
item);

This method writes the string value of the arg to the standard output (STDOUT) of the program. If Candle runs under desktop mode, the standard input is not available, and this method returns directly.

method io:write(

stream
as

item,

arg
as item);

This method writes the string value of the arg to the given stream. The stream is either returned from io:popen() or io:open().

4.1.8 method io:writeln()

method io:writeln(arg as
item);

This method writes the string value of the arg and an additional newline character (U+000A) to the standard output (STDOUT) of the program. If Candle runs under desktop mode, the standard input is not available, and this method returns directly.

method io:writeln(

stream
as

item,

arg
as item);

This method writes the string value of the arg and an additional newline character (U+000A) to the given stream. The stream is either returned from io:popen() or io:open().

4.1.9 method io:close()

method io:close(

stream
as

item

);

This method closes the stream which is either returned from io:popen() or io:open().

4.2 File and Directory Handling Routines

4.2.1 method f:create-file()

method f:create-file(uri as
uri);

Summary: This method creates an empty file at the location specified by the uri. The directories containing the result file are created when necessary. If a file of the same name already exists that the target location, then a runtime error is raised.

4.2.2 method f:create-dir()


method f:create-dir(uri as uri);

Summary: This method creates a directory at the location specified by the uri. The directories containing the result file are created when necessary. If a directory already exists that the target location, the method returns as success.

4.2.3 method f:copy()


method f:copy(src-uri as uri, trg-uri as uri);

Summary: This method copies a file or directory from the src-uri to the trg-uri. If a file of the same name already exists that the target location, the file is overwritten silently.

4.2.4 method f:move()


method f:move(src-uri as uri, trg-uri as uri);

Summary: This method moves a file or directory from the src-uri to the trg-uri. If a file of the same name already exists that the target location, the file is overwritten silently.

4.2.5 method f:delete()


method f:delete(uri as uri);

Summary: This method deletes a file or directory at the uri. The files and sub-directories are deleted recursively.

5. Data Access Routines

5.1 Relational Database Access

Note: in current release, we only supports connecting to SQLite database. The connection string for SQLite database should follow the pattern of "sqlite:path-to-db-file", e.g.

"sqlite:c:/path/file,
sqlite:/var/db/file"

5.1.1 function sql:select()

function sql:select(dsn as
string, sql as string) as element;

function sql:select(dsn as string, sql as
string, params as
item*)
as element;

Summary: Connects to the database using the connection string dsn, and returns the result-set of the sql statement as an element. Each record in the result-set is mapped to an element, and each column in the record is mapped to as an attribute in the element. If DB column name is available, then it is used as the attribute name, otherwise, a name is generated for the attribute.

When params is specified, the sql statement can be a prepared SQL statement containing '?'. The number of '?'s in the SQL statement should match the items in params argument. In current beta release, only numeric types and string type are supported as the parameter.

5.1.2 method sql:execute()

method sql:execute(dsn as
string, sql as string) as integer;

method sql:execute(dsn as string, sql as
string, params as
item*)
as integer;

Summary: Connects to the database using the connection string dsn, executes the sql statement, and returns the number of rows affected by the SQL statement.

Appendices

A. References

XQuery 1.0 and XPath 2.0 Functions and Operators;
XSLT Functions;
FunctX XQuery Functions;

B. Mapping Between Functions in Candle and XQuery/XPath

Candle Functions	XQuery 1.0 and XPath 2.0 Functions
c:input()	fn:doc()
c:deep-equal()	fn:deep-equal()
...	...

Note that, this mapping only means that a Candle function is designed based on a particular function prototype in XQuery and XPath. During our design and implementation, we try to keep the two the same in semantics as much as possible, but the behavior of the two functions may still vary slightly due to the differences in the data model of two languages.

If you spot any differences and think that Candle should follow XQuery and XPath more closely, you can always raise it as a bug or feature request.