This is in the early stages of development. Don't use this for anything important (or at all)!
The aim of this project is to make a PHP-like runtime that enables server-side "scripting" using C/C++. At the core is a multi-worker FastCGI server that can be talked to from Nginx or similar front-end servers. UCE has a shared-nothing isolated architecture to serve page requests. To minimize the potential for memory leaks, UCE uses a per-request memory arena. UCE also provides a PHP-like API to ease web development. Advanced features such as an integrated WebSockets broker are planned. UCE aims to use minimal dependencies (at the moment, the only dependency is the Clang compiler). UCE pages are automatically recompiled and dynamically reloaded as necessary.
String memcache_command(u64 connection, String command)
connection : connection handle
command : string containing the Memcache command
return value : string containing the Memcache server's response
Executes a command on an open memcache connection.
u64 memcache_connect(String host = "127.0.0.1", short port = 11211)
host : optional host name of the memcache server, defaults to local address 127.0.0.1
port : optional memcache server's port, defaults to 11211
return value : the connection handle (or -1 if an error occurred)
Connects to a memcache server instance.
bool memcache_delete(u64 connection, String key)
connection : connection handle
key : key string
return value : true if the operation was successful
Deletes entry specified by the 'key'.
String memcache_get(u64 connection, String key, String default_value = "")
connection : connection handle
key : key string
default_value : optional default value
return value : value that was returned by the Memcache server
Retrieves a value from an existing connection to a Memcache server.
StringMap memcache_get_multiple(u64 connection, StringList keys)
connection : connection handle
keys : a list of strings containing the keys to be retrieved
return value : a StringMap with the retrieved entries
Retrieves a bunch of entries all at once.
bool memcache_set(u64 connection, String key, String value, u64 expires_in = 60*60)
connection : connection handle
key : the entry's key
value : the value to be set
expires_in : optional expiration timeout, defaults to one hour
return value : true if the operation was successful
Stores a 'value' on the Memcache server.
MySQL* mysql_connect(String host = "localhost", String username = "root", String password = "")
host : host name of the MySQL server
username : user name
password : password
return value : pointer to the MySQL connection struct
Establishes a connection to a MySQL server.
void mysql_disconnect(MySQL* m)
m : pointer to an existing MySQL connection struct
Closes a connection to a MySQL server.
String mysql_error(MySQL* m)
m : pointer to a MySQL connection struct
return value : MySQL error message (if present, otherwise empty string)
Returns the last error message from a connection to a MySQL server.
String mysql_escape(String raw, char quote_char)
raw : the string to be escaped
quote_char : the character that should be used to wrap the string (pass NULL for no wrapping)
return value : the safe version of the 'raw' string
Escapes a string such that it can be passed as a safe value into an SQL expression.
u64 mysql_insert_id(MySQL* m)
m : pointer to an active MySQL connection
return value : the last used automatic row ID
This retrieves the last row ID that was used for a column with an AUTO_INCREMENT row key.
DTree mysql_query(MySQL* m, String q, StringMap params)
m : pointer to an active MySQL connection struct
q : a string containing a MySQL query
params : optional, a list of query parameter keys and values
return value : a list of rows returned from executing the query
Executes a MySQL query and returns the resulting data (if any).
(tbd)
f64 draw_float(f64 from, f64 to)
from : minimum value
to : maximum value
return value : a noise value between 'from' and 'to'
This function works exactly like generate_float(), but context->random_index is used for the 'index' value and context->random_seed is used for the seed. After this function has been called, the context->random_index is increased by one. At the start of every request, context->random_seed is automatically populated with a new seed value.
u64 draw_int(u64 from, u64 to)
from : minimum value
to : maximum value
return value : a noise value between 'from' and 'to'
This function works exactly like generate_int(), but context->random_index is used for the 'index' value and context->random_seed is used for the seed. After this function has been called, the context->random_index is increased by one. At the start of every request, context->random_seed is automatically populated with a new seed value.
u32 noise01(u64 index, u64 seed = 0)
index : index position
seed : seed set (defaults to 0)
return value : a noise value from 0 to 1
Generates a noise value in the range from 0 to 1 for the given 'index' and 'seed' values.
u32 noise32(u32 index, u32 seed = 0)
index : index position
seed : seed set (defaults to 0)
return value : a noise value given the 'index' and 'seed' values.
Generates a noise value for the given 'index' and 'seed' values.
u32 noise64(u64 index, u64 seed = 0)
index : index position
seed : seed set (defaults to 0)
return value : a noise value given the 'index' and 'seed' values.
Generates a noise value for the given 'index' and 'seed' values.
f64 generate_float(f64 from, f64 to, u64 index, u64 seed = 0)
from : minimum result
to : maximum result
index : index position to generate number from
seed : seed position to generate number from (defaults to 0)
return value : noise value
Generates a noise value between 'from' and 'to', given the 'index' and 'seed' numbers.
u64 generate_int(u64 from, u64 to, u64 index, u64 seed = 0)
from : minimum result
to : maximum result
index : index position to generate number from
seed : seed position to generate number from (defaults to 0)
return value : noise value
Generates a noise value between 'from' and 'to', given the 'index' and 'seed' numbers.
String sha1(String s, bool as_binary = false)
s : data to be hashed
as_binary : when set to false, returns hash in hexadecimal notation (defaults to false)
return value : the resulting hash value
Returns the sha1 hash of 's'.
void ob_clear()
(none) :
Discard the current output buffer.
String ob_get()
return value : content of the current output buffer
Returns the contents of the current output buffer.
String ob_get_clear()
return value : content of the current output buffer
Returns the contents of the current output buffer and then discards the buffer.
void ob_start()
(none) :
Starts a new output buffer. All subsequent output will be directed into this buffer.
String make_session_id()
return value : a new session ID
Creates a session ID
void session_destroy(String session_name)
session_name : the name of the session
Deletes the cookie specified by 'session_name' and clears the data stored under the session ID. This empties the 'context->session_id' and 'context->session' variables.
String session_start(String session_name)
return value : the session ID, defaults to "uce-session"
Starts session or connects to existing session. This function sets a cookie with the name contained in 'session_name' if it does not exist and fills that cookie with a new unique session ID. It then loads the session data for that session ID. Afterwards, the following fields are populated in the 'context' variable:
context->session_id : the current session ID
context->session_name : the current session cookie name
context->session : the current session data. The session data is automatically saved after a request completes.
void socket_close(u64 sockfd)
sockfd : socket handle
Closes an existing socket connection.
u64 socket_connect(String host, short port)
host : host name
port : port number
return value : the socket handle
Opens a socket connection to the given 'host' and 'port'.
String socket_read(u64 sockfd, u32 max_length = 1024*128, u32 timeout = 1);
sockfd : socket handle
max_length : optional maximum data size, defaults to 128kBytes
timeout : optional operation timeout, defaults to one second
return value : string containing the data that was read
Reads data from a socket connection.
bool socket_write(u64 sockfd, String data)
sockfd : socket handle
data : a string containing the data to be written to the socket
return value : true if the write operation was successful
Writes a string of 'data' to the given socket.
StringList filter(StringList items, function f)
vector filter(vector items, function f)
items : list of items to be filtered
f : a function that decides which items should be in the new list
return value : a new list
Returns a list containing the members of 'items' for which 'f' returned boolean true.
String first(String... args)
args : a variable number of String arguments
return value : first of the 'args' that was not empty.
Given a variable number of String parameters, the first() function returns the first of these parameters that was not empty. Leading and trailing whitespace characters are not considered, resulting in a string that contains only whitespace characters being considered empty.
String join(StringList l, String delim = "\n")
l : list of strings to be joined
delim : delimiter (defaults to newline character)
return value : a string containing items joined by 'delim'
Joins the items contained in 'l' into a single String.
String nibble(String& haystack, String delim)
haystack : string to be nibbled at
delim : delimiter
return value : string before first occurrence of 'delim'
Returns the part of 'haystack' before the first occurrence of 'delim', removing the corresponding part from 'haystack' (including 'delim'). If the substring 'delim' does not occurr in 'haystack', the entire string is returned and 'haystack' is set to an empty string.
StringList split(String str, String delim)
str : string to be split
delim : delimiter
return value : a list of strings
Splits 'str' into multiple strings based on the given delimiter 'delim'.
StringList split_space(String str)
str : string to be split
return value : a list of strings
Splits 'str' into multiple strings along any whitespace characters (multiple whitespace characters count as one).
StringList split_utf8(String str, bool compound_characters = false)
str : string to be split
compound_characters : optional, if true tries to combine compound characters
return value : a list of Unicode characters
Splits the string 'str' into its constituent Unicode code points.
If 'compound_characters' is true, split_utf8 will attempt to combine compound characters based on very simple rules:
-
combine characters if they're connected by a Zero-Width Joiner (ZWJ) character
-
combine two characters if they're both a Regional Indicator Symbol Letter
-
if a character is a Variation Selector, append it to the previous character
-
in all other cases, characters remain on their own
String replace(String s, String search, String replace_with)
s : the string where replacements should happen
search : the string that should be searched for
replace_with : the string that should appear in places where 'search' occurs
return value : a version of 's' where all instances of 'search' have been replaced with 'replace_with'
Replace all occurrences of 'search' with the string defined in 'replace_with'.
String to_lower(String s)
s : the string to be converted
return value : returns a version of 's' where all upper case characters have been changed into lower case
Returns a lower case version of the input string 's'.
Note: this function is not yet Unicode-aware.
String to_upper(String s)
s : the string to be converted
return value : returns a version of 's' where all lower case characters have been changed into upper case
Returns a upper case version of the input string 's'.
Note: this function is not yet Unicode-aware.
String trim(String raw)
raw : string to be trimmed
return value : string with leading and trailing whitespace characters removed
Returns a string where leading an trailing whitespace characters have been trimmed off.
String basename(String fn)
fn : raw filename
return value : the file's name
Isolates the file name component from a path/file name.
String dirname(String fn)
fn : raw filename
return value : the directory's name
Isolates the directory name component from a path/file name.
String expand_path(String path, String relative_to_path = "")
path : a relative path
relative_to_path : optional, expand relative to this path (if not given, the current path is used)
return value : expanded version of the 'path'
Converts a relative path name into an absolute path, using the current working directory as a base.
void file_append(String file_name, ...val)
file_name : file name of file that should be written to
...val : one or more values that should be written into the file
Opens or creates a given file and appends data to it.
bool file_exists(String path)
path : the path name to be checked
return value : true if the file exists
Checks whether the file or path specified by 'path' exists.
String file_get_contents(String file_name)
file_name : file name of file that should be read
return value : String containing the file's contents
Reads the file identified by 'file_name' and returns it as a String. If the file cannot be read, this function will return an empty string.
time_t file_mtime(String file_name)
file_name : name of the file
return value : Unix time stamp of the file's last modification
Retrieves the last modification date of 'file_name' as a Unix timestamp.
bool file_put_contents(String file_name, String content)
file_name : file name of file that should be written
content : content that should be written
return value : true if write was successful
Writes the String 'content' into a file identified by 'file_name'. Any pre-existing content of the file will be overwritten.
String get_cwd()
return value : the current working directory
Returns the current working directory.
StringList ls(String path)
path : a filesystem path
return value : list of directory entries
Returns a list of files and subdirectories within the given 'path'.
bool mkdir(String path)
path : the path name to be created
return value : returns true if the directory was successfully created
Creates a directory stated by 'path'
void set_cwd(String path)
path : the new working directory
Sets a new working directory.
String shell_escape(String raw)
raw : string that should be escaped
return value : escaped version of 'raw'
Escapes a parameter for shell_exec
String shell_exec(String cmd)
cmd : string that contains the shell command line to be executed
return value : output of the command execution
Executes a Linux shell command and returns the generated output
void unlink(String file_name)
file_name : name of the file
Deletes the file identified by 'file_name'.
s64 kill(pid_t pid, s64 sig)
pid : PID of the process
sig : signal number
return value : 0 if signal was sent, -1 otherwise
This is the standard POSIX kill() function, provided here for reference.
Possible signal numbers are: SIGABND, SIGABRT, SIGALRM, SIGBUS, SIGFPE, SIGHUP, SIGILL, SIGINT, SIGKILL, SIGPIPE, SIGPOLL, SIGPROF, SIGQUIT, SIGSEGV, SIGSYS, SIGTERM, SIGTRAP, SIGURG, SIGUSR1, SIGUSR2, SIGVTALRM, SIGXCPU, SIGXFSZ, SIGCHLD, SIGIO, SIGIOERR, SIGWINCH, SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU, SIGCONT.
pid_t task(String key, std::function exec_func)
key : string uniquely identifying the task
exec_func : function to execute
return value : the process ID of the started (or still running) task
task() starts the 'exec_func' in a new process and returns that process' ID. If a process with the same 'key' is already running, task will not start a new process but instead just return the PID of the process that is already running.
pid_t task_pid(String key)
key : string uniquely identifying the task
return value : the process ID of the task
Checks whether a process with the given 'key' is running and returns its PID if it is. Returns 0 otherwise.
f64 microtime()
return value : current Unix timestamp
Returns a 64 bit float containing the current Unix timestamp with millisecond accuracy or better.
u64 time()
return value : second-accurate current Unix timestamp
Returns a 64 bit integer containing the current Unix timestamp.
String date(String format = "", u64 timestamp = 0)
format : formatting string specifying the date format
timestamp : optional timestamp value, defaults to current time
return value : a formatted date
Returns a formatted date. This is based on the Linux date() command. The formatting string supports the following sequences:
%% a literal %
%a locale's abbreviated weekday name (e.g., Sun)
%A locale's full weekday name (e.g., Sunday)
%b locale's abbreviated month name (e.g., Jan)
%B locale's full month name (e.g., January)
%c locale's date and time (e.g., Thu Mar 3 23:05:25 2005)
%C century; like %Y, except omit last two digits (e.g., 20)
%d day of month (e.g., 01)
%D date; same as %m/%d/%y
%e day of month, space padded; same as %\_d
%F full date; like %+4Y-%m-%d
%g last two digits of year of ISO week number (see %G)
%G year of ISO week number (see %V); normally useful only
with %V
%h same as %b
%H hour (00..23)
%I hour (01..12)
%j day of year (001..366)
%k hour, space padded ( 0..23); same as %\_H
%l hour, space padded ( 1..12); same as %\_I
%m month (01..12)
%M minute (00..59)
%n a newline
%N nanoseconds (000000000..999999999)
%p locale's equivalent of either AM or PM; blank if not known
%P like %p, but lower case
%q quarter of year (1..4)
%r locale's 12-hour clock time (e.g., 11:11:04 PM)
%R 24-hour hour and minute; same as %H:%M
%s seconds since 1970-01-01 00:00:00 UTC
%S second (00..60)
%t a tab
%T time; same as %H:%M:%S
%u day of week (1..7); 1 is Monday
%U week number of year, with Sunday as first day of week
(00..53)
%V ISO week number, with Monday as first day of week (01..53)
%w day of week (0..6); 0 is Sunday
%W week number of year, with Monday as first day of week
(00..53)
%x locale's date representation (e.g., 12/31/99)
%X locale's time representation (e.g., 23:13:48)
%y last two digits of year (00..99)
%Y year
%z +hhmm numeric time zone (e.g., -0400)
%:z +hh:mm numeric time zone (e.g., -04:00)
%::z +hh:mm:ss numeric time zone (e.g., -04:00:00)
%:::z numeric time zone with : to necessary precision (e.g.,
-04, +05:30)
%Z alphabetic time zone abbreviation (e.g., EDT)
By default, date pads numeric fields with zeroes. The following
optional flags may follow '%':
- (hyphen) do not pad the field
\_ (underscore) pad with spaces
0 (zero) pad with zeros
+ pad with zeros, and put '+' before future years with >4
digits
^ use upper case if possible
# use opposite case if possible
String gmdate(String format = "", u64 timestamp = 0)
format : formatting string specifying the date format
timestamp : optional timestamp value, defaults to current time
return value : a formatted date
Returns a formatted date in the GMT/UTC timezone. This is based on the Linux date() command. The formatting string supports the following sequences:
%% a literal %
%a locale's abbreviated weekday name (e.g., Sun)
%A locale's full weekday name (e.g., Sunday)
%b locale's abbreviated month name (e.g., Jan)
%B locale's full month name (e.g., January)
%c locale's date and time (e.g., Thu Mar 3 23:05:25 2005)
%C century; like %Y, except omit last two digits (e.g., 20)
%d day of month (e.g., 01)
%D date; same as %m/%d/%y
%e day of month, space padded; same as %\_d
%F full date; like %+4Y-%m-%d
%g last two digits of year of ISO week number (see %G)
%G year of ISO week number (see %V); normally useful only
with %V
%h same as %b
%H hour (00..23)
%I hour (01..12)
%j day of year (001..366)
%k hour, space padded ( 0..23); same as %\_H
%l hour, space padded ( 1..12); same as %\_I
%m month (01..12)
%M minute (00..59)
%n a newline
%N nanoseconds (000000000..999999999)
%p locale's equivalent of either AM or PM; blank if not known
%P like %p, but lower case
%q quarter of year (1..4)
%r locale's 12-hour clock time (e.g., 11:11:04 PM)
%R 24-hour hour and minute; same as %H:%M
%s seconds since 1970-01-01 00:00:00 UTC
%S second (00..60)
%t a tab
%T time; same as %H:%M:%S
%u day of week (1..7); 1 is Monday
%U week number of year, with Sunday as first day of week
(00..53)
%V ISO week number, with Monday as first day of week (01..53)
%w day of week (0..6); 0 is Sunday
%W week number of year, with Monday as first day of week
(00..53)
%x locale's date representation (e.g., 12/31/99)
%X locale's time representation (e.g., 23:13:48)
%y last two digits of year (00..99)
%Y year
%z +hhmm numeric time zone (e.g., -0400)
%:z +hh:mm numeric time zone (e.g., -04:00)
%::z +hh:mm:ss numeric time zone (e.g., -04:00:00)
%:::z numeric time zone with : to necessary precision (e.g.,
-04, +05:30)
%Z alphabetic time zone abbreviation (e.g., EDT)
By default, date pads numeric fields with zeroes. The following
optional flags may follow '%':
- (hyphen) do not pad the field
\_ (underscore) pad with spaces
0 (zero) pad with zeros
+ pad with zeros, and put '+' before future years with >4
digits
^ use upper case if possible
# use opposite case if possible
u64 parse_time(String time_string)
time_string : a string containing a date and/or time in text form
return value : the interpreted 'time_string' as a Unix timestamp
Attempts to parse the given 'time_string' into a Unix timestamp.
String encode_query(StringMap map)
q : StringMap containing URL parameters to be encoded
return value : a string with the encoded parameters
Encodes a StringMap containing URL parameters into a single String.
String make_session_id()
return value : a new session ID
Creates a session ID
StringMap parse_query(String q)
q : string containing URL parameters
return value : a StringMap containing the parameters
Decodes a string of the format 'a=b&c=d' into a StringMap containing keyed entries.
String uri_decode(String s)
s : string containing URI encoded data
return value : a string that contains the decoded version of 's'
Decodes an URI-encoded string 's'.
String uri_encode(String s)
s : string that should be encoded
return value : an URI-encoded version of 's'
URI-encodes a string.
Request* context;
Contains the current server state
All FastCGI server parameters
The current request's GET variables
The current request's POST variables
Cookies that have been transmitted by the browser
The current session
ID of the session cookie
String session_name
Name of the session cookie
Variable user-defined data
Files that have been uploaded in the current request
Headers to be sent back to the browser
Cookies that should be sent back to the browser
The current request's "random" noise generator seed
The current request's "random" noise generator index position
Contains the current request's memory arena
Whether the request should be logged
u32 stats.bytes_written
f64 stats.time_init
f64 stats.time_start
f64 stats.time_end
Invokes the UCE file 'file_name'
#load "myfile.uce"
file name : name of an UCE file that should be included
Includes another UCE file
f64 float_val(String s)
s : string to be converted
return value : a f64 containing the number (0 if no number could be identified).
Extracts a floating point number from a String.
String html_escape(String s)
s : string to be escaped
return value : an HTML-safe escaped version of 's'
Returns a version of the input string where the following characters have been replace by HTML entities:
- & → &
- < → lt;
- > → >
- " → "
u64 int_val(String s, u32 base = 10)
s : string to be converted
base : number system base (default 10)
return value : a u64 containing the number (0 if no number could be identified).
Extracts an integer from a String.
DTree json_decode(String s)
s : string containing JSON data
return value : a DTree object containing the deserialized JSON data
Deserializes 's' into a DTree structure.
String json_encode(DTree t)
t : DTree object to be serialized
return value : string containing the JSON result
Serializes a DTree structure 't' into a String in JSON notation.
void print(...val)
...val : one or more values that should be output
Appends data to the current request's output stream.
String var_dump(StringMap t, String prefix = "", String postfix = "\n")
String var_dump(StringList t, String prefix = "", String postfix = "\n")
String var_dump(DTree t, String prefix = "", String postfix = "\n")
t : object to be dumped into a string
return value : string containing a human-friendly representation of 't'
Returns a string representation of 't' intended for debugging.