Octavia Function Reference
Note: this is extremely outdated.

Preamble and Design

Names for functions are a mixture of Perl, PHP, and classic BASIC. PHP often prefixes "str" or "str_" onto string-handling functions, which is primarily tiresome, and some of Perl's irregular syntax constructions would simply be too much work for a naïve interpreter, itself interpreted. Zero-indexed string-handling functions use PHP-style names, however, to differentiate their functionalities.

In general, string-handling functions often also change the orders of their arguments in various languages: Perl, PHP, and VB all agree that index()/strpos()/instr() should have (haystack, needle) syntax, but peculiarly, PHP's str_replace() uses (old, new, haystack) for its syntax. In Octavia, string-handling functions always put haystack-like variables first, and database functions always put id variables, or other numeric handles, last. ...actually this is a lie, but you'll live.

Square brackets in the examples below indicate optional syntaxes, not array subscripts or code blocks.

Output Functions and Templates

Only echo() and its alias print() actually send to the output buffer. However, any line of code that returns a value will also send to the output buffer, so echo() generally isn't necessary.

print/echo(message[, message[, ...]])
Sends message to output. If more than one parameter is supplied, all of them are printed.

page(mode, id)
Returns the page with id = id, using the supplied mode.

index(mode, id)
Returns all pages with parent = id using mode. These pages are sorted first by priority, and then alphabetically.

children(mode, id)
As index(), except pages are sorted by priority and then by id, which corresponds directly to order of creation.

locate(mode, field, value)
Lists all entries that exactly meet the criterion field == value. Contrast with search(), which permits examining multiple fields simultaneously.

search(mode, param, value, ...)
Searches all entries for those that contain value within the field specified by param. Multiple param/value pairs may be specified, indicating to show only entries that meet all of the criteria indicated. Case-insensitive. For number fields, values must match exactly.

Returns a wrapper made out of div tags to start a message box with.

Returns the end of the same message box.

If the viewer has the e (edit) permission, returns a link to the current page in the edit mode. Otherwise, returns nothing.

String Manipulation

Returns the ASCII code for a character.

Returns the integer value of a number. If the data supplied is non-numeric, returns zero.

Returns the character corresponding to a specified ASCII code.

len(string[, string[, ...]])
Returns the length of string. If multiple arguments are provided, the sum is returned.

Converts string to minuscule letters.

Converts string to MAJUSCULE letters.

replace(haystack, old, new)
Returns a form of haystack with all occurrences of old replaced by new.

substr(haystack, start, length)
Returns a range of characters from haystack, starting at start and ending at start + length. start = 0 is the start of the string. Negative values for both start and length will work backward.

strpos(haystack, needle[, offset])
Starting from offset, search for needle in haystack and return the position of its first occurrence, with 0 being the start of the string. If the string is not found, returns -1.

strrpos(haystack, needle[, offset])
Starting from offset, search backward for needle in haystack and return the starting position of its last occurrence, with 0 being the start of the string. If the string is not found, returns -1.

Entry Manipulation and Database I/O

putv(name, value)
Treats $_body as a variable table, and attempts to store value in the entry name. If value is "", the entry will be removed. If it does not exist (and value is not empty), it will be created.

Using the same $_body format as putv(), returns the contents of the entry name. If name does not exist, returns a blank string.

Returns the title of the entry id.

Returns the lowest id amongst entries with the title specified.

set_title, set_subtitle, set_author, set_parent, set_permissions, set_template, set_group, set_priority, set_date(id, data)
If the user has d (direct) permissions on the entry id, sets the specified piece of data to data. The script may also set these pieces of data for itself directly, by modifying the appropriate $_ variables ($_title, $_subtitle, $_author, $_parent, $_permissions, $_template, $_group, $_priority and $_date).

set_body(id, body)
If the user has e (edit) permissions on the entry id, sets the contents of the entry's body field to body.

new_page(title, parent)
Creates a page with the specified title and parent, and returns the new page's id number. 0 or -1 indicate failure.

Retrieves the name of the user specified.

Miscellaneous and Flow Control

Returns the number of arguments provided.

iif(condition, true[, false])
If condition evaluates to true, executes and returns true. Otherwise, executes and returns false.

if(condition) true[ else false]
If condition evaluates to true, executes and returns true. Otherwise, executes and returns false.

foreach(data[, separator]) verb
Explodes data at every occurrence of separator, yielding the variables $_index and $_data for use inside of the statement verb, then re-implodes and returns the resultant modifications of $_data. If no separator is provided, a linebreak is assumed. An example of the most useful syntax is foreach($foo) {[$_data = {[$_index]. [$_data]}; ]};. If $_data is not set, the original variable will be returned unharmed.

Returns a linebreak-delimited list of the files in path and its subdirectories. Directories themselves are not included.