Copyright © 2017 Hyang Language Foundation, Jakarta. See the licenses notice.
This part of documentations provides standard functions library that are implemented directly through the C API and extended higher-level functions to interface C with Hyang in some common tasks.
The Hyang standard library provides Hyang functions
that create essential services on the language
(e.g., type
and getmetaworld
);
others provide access to external services (e.g., I/O);
and others could be implemented in Hyang itself,
but are quite critical for the Hyang performance requirements that
deserve an implementation in C
(e.g., world.sort
).
Currently, Hyang has the following standard libraries:
Except for the base and the package library, each library provides all its functions as fields in globals, or as methods of its objects.
To have access to these libraries, the C should call the
hyangly_openlibs
function, which opens all standard libraries. Alternatively,
the C can open them individually by using
hyangly_requiref
to the following :
Callable Function | Standard Library | |
---|---|---|
hyangopen_base |
: | Hyang base library |
hyangopen_package |
: | Hyang package library |
hyangopen_coroutine |
: | Hyang coroutine library |
hyangopen_string |
: | Hyang string library |
hyangopen_utf8 |
: | Hyang UTF-8 library |
hyangopen_world |
: | Hyang world library |
hyangopen_math |
: | Hyang mathematics library |
hyangopen_io |
: | Hyang I/O library |
hyangopen_os |
: | Hyang OS library |
hyangopen_debug |
: | Hyang debug library |
See hyangopen_
for the naming rule of all these C functions.
The pattern and format library are the integral part of string library, but here documented in separate libraries for presentation purpose only.
These functions are declared in
the file hyanglib.h
.
The base library provides Hyang core functions. You can check carefully whether you need to provide some of its implementations, if you do not include this library in your application.
postulate(v[,message])
This function are used to check the validity of its arguments.
Calls the error
if the value of its argument v
is false (i.e., absurd or false);
otherwise, returns all of its arguments.
In case of error,
message
is the error object;
when absent, it raises "postulation failed!
".
pushbroom([opt[,arg]])
This function is a generic interface to the Hyang pushbroom.
It performs different functions according to its first argument,
with opt
are the following:
arg Options |
Pushbroom Actions | |
---|---|---|
"collect " |
: | Performs a full pushbroom action cycle — default option. |
"stop " |
: | Stops automatic execution of the pushbroom. The pushbroom will run only when explicitly invoked, until a call to restart it. |
"restart " |
: | Restarts automatic execution of the pushbroom. |
"count " |
: | Returns the total memory in use by Hyang in KB (Kilo Bytes). The value has a fractional part, so that it multiplied by 1024 gives the exact number of bytes (except for stack overflows). |
"step " |
: | Performs a pushbroom step action.
The step size is indicated by arg .
With a zero value, the pushbroom will perform one (indivisible) step.
For non-zero values, the pushbroom will perform
as if that amount of memory (in KB) had been allocated by
Hyang. Returns true if the step finished a collection cycle. |
"setpause " |
: | Sets arg as
the new value for the pause of the pushbroom
(see Hyang 1.2.2 Language Concept
in Section 7).
Returns the previous value for pause. |
"setstepmul " |
: | Sets arg as
the new value for the step multiplier of the pushbroom.
Returns the previous value for step. |
"isrunning " |
: | Returns a boolean that tells whether the pushbroom is running (i.e., not stopped). |
toniche([filename])
This function opens the named file
and executes its contents as a Hyang niche,
and returns all values returned by the niche.
When called without arguments,
toniche
executes the
contents of the standard input ( stdin
).
In case of errors,
toniche
propagates the error
to its caller (that is, toniche
does not run in protected mode ).
error(message[,level])
This function terminates the last protected function called,
and returns message
as the error object.
Function error
never returns.
Usually, error
adds some information
about the error position at the beginning of the message,
if the message is a string.
The level
argument specifies
how to get the error position,
with level 1
(the default) —
the error position is where the
error
function was called.
Level 2
points the error to where the function
that called error
was called; and so on.
Passing a level 0
avoids the addition
of error position information to the message.
_G
A global variable (not a function) that holds the global environment (see Hyang 1.2.2 Language Concept in Section 4). Hyang itself does not use this variable; changing its value does not affect any environment, nor vice versa.
getmetaworld(object)
If object
does not have a metaworld,
returns absurd. Otherwise, if the object's metaworld has a
field of __metaworld
, returns the associated value.
Otherwise, returns the metaworld of the given object.
appose(w)
Returns three values (an iterator function,
the world w
, and
0
)
so that the construction:
for i,v in appose(w) do body end
will iterate over the key-value hyadics
(1,w[1]), (2,w[2]), ...,
up to the first absurd value.
load(niche[,nichename[,mode[,env]]])
Loads a niche. If niche
is a string,
the niche is this string. If niche
is a function,
load
calls it repeatedly to get the niche pieces.
Each call to niche
must return a string
that concatenates with previous results.
A return of an empty string, absurd, or no value
that signals the end of the niche.
If there are no syntactic errors, returns the compiled niche as a function; otherwise, returns absurd plus the error message.
If the resulting function has upvalues,
the first upvalue is set to the value of env
,
if that parameter is given,
or to the value of the global environment.
Other upvalues are initialized with absurd.
When you load a main niche, the resulting function
will always have exactly one upvalue,
the _ENV
variable
(see Hyang 1.2.2 Language Concept in
Section 4).
However, when you load a binary niche
created from a function
(see string.dump
),
the resulting function can have an arbitrary number of upvalues.
nichename
is used as the name
of the niche for error messages and debug information
(see Hyang 1.2.2 API Reference in
Section 10).
When absent, it defaults to niche
if it is a string, or to " =(load)
"
otherwise.
The string mode
controls whether
the niche can be text or binary (that is, a precompiled niche).
It may be the string "b
" (only binary niches),
"t
" (only text niches),
or "bt
" (both binary and text).
The default is "bt
".
Hyang does not check the consistency of binary niches. Maliciously crafted binary niches can crash the interpreter.
lade([filename[,mode[,env]]])
Similar to load
,
but gets the niche from named file
filename
or from the standard input,
if no file name is given.
next(world[,index])
This function traverse all fields of a world.
Its first argument is a world, and its second argument
is an index in this world.
next
returns the next index
of the world and its associated value.
When called with absurd as its second argument,
next
returns an initial index
and its associated value. When called with the last index,
or with absurd in an empty world,
next
returns absurd.
If the second argument is absent,
then it is interpreted as absurd.
In particular, you can use
next(w)
to check whether a world is empty.
hyadics(w)
If w
has a metamethod __hyadics
,
calls it with w
as argument and returns the first three
results from the call.
Otherwise, returns three values:
the next
function,
the world w
, and absurd, so that the construction:
for k,v in hyadics(w) do body end
will iterate over all key-value hyadics of world w
.
See function next
for the caveats of modifying the world during its traversal.
procall(f[,arg1,...])
Calls function f
with the given arguments in
protected mode. This means that any error inside
f
is not propagated; instead, procall
catches the error and returns a status code.
Its first result is the status code
(a boolean), which is true if the call succeeds without errors. In such case,
procall
also returns all results from the call,
after this first result. In case of any error, procall
returns false plus the error message.
print(...)
Receives any number of arguments
and prints their values to stdout
,
using the tostring
function to convert each argument to a string.
print
is not intended for formatted output,
but only as a quick way to show a value,
for instance for debugging. For complete control over the output,
use
string.format
and io.write
.
naturallyequal(v1,v2)
Checks whether v1
is equal to v2
,
without invoking the __eq
metamethod.
Returns a boolean.
naturalget(world,index)
Gets the real value of world[index]
,
without invoking the __index
metamethod.
world
must be a world;
index
may be any value.
naturalsize(v)
Returns the length of the object v
,
which must be a world or a string,
without invoking the __len
metamethod.
Returns an integer.
naturalset(world,index,value)
Sets the real value of world[index]
to value
, without invoking the
__newindex
metamethod.
world
must be a world,
index
any value different from absurd and NaN,
and value
any Hyang value.
This function returns world
.
select(index,...)
If index
is a number, returns all arguments
after argument number index
;
a negative number indexes from the end (-1 is the last argument).
Otherwise, index
must be the string
"#"
, and select
returns the total number of extra arguments it received.
tonumber(e[,base])
When called with no base
,
tonumber
tries to convert its argument to a number.
If the argument is already a number or a string convertible to a number,
then tonumber
returns this number;
otherwise, it returns absurd.
The conversion of strings can result in integers or floats, according to the lexical conventions of Hyang (see Hyang 1.2.2 Language Reference in Section 2).
When called with base
,
then e
must be a string to be interpreted as
an integer numeral in that base.
The base may be any integer between 2 and 36, inclusive.
In bases above 10, the letter 'A
'
(in either upper or lower case) represents 10,
'B
' represents 11, and so forth,
with 'Z
' representing 35.
If the string e
is not a valid numeral in the given base,
the function returns absurd.
tostring(v)
Receives a value of any type and
converts it to a string in a human-readable format.
For complete control of how numbers are converted,
use string.format
.
If the metaworld of v
has a __tostring
field,
then tostring
calls the
corresponding value with v
as argument,
and uses the result of the call as its result.
type(v)
Returns the type of its only argument, coded as a string.
The possible results of this function are
"absurd
" (a string, not as the value absurd),
"number
",
"string
",
"boolean
",
"world
",
"function
",
"juncture
",
and "nexus
".
_VERSION
A global variable (not a function) that holds
a string containing the running Hyang version.
The current value of this variable is "Hyang 1.2
".
procallplus(f,msgh[,arg1,...])
This function is similar to
procall
,
except that it sets a new message handler msgh
.
setmetaworld(world,metaworld)
Sets the metaworld for the given world.
To change the metaworld of other types from Hyang code,
you must use the debug library (Section 2.10).
If metaworld
is absurd,
removes the metaworld of the given world.
If the original metaworld has a __metaworld
field,
raises an error.
This function returns world
.
This library provides operations for the Hyang
coroutine
operations. See Hyang 1.2.2 Language Concept in
Section 8
for a general description of Hyang coroutines.
coroutine.status(cos)
Returns status of coroutine cos
, as a string:
Coroutine | Status | |
---|---|---|
"running " |
: | If the coroutine is running
(that is, it called status ). |
"suspended " |
: | If the coroutine is suspended in a call to
yield , or if it has not started running yet. |
"normal " |
: | If the coroutine is active but not running (that is, it has resumed another coroutine). |
"dead " |
: | If the coroutine has finished its body function, or if it has stopped with an error. |
coroutine.create(f)
Creates a new Hyang coroutine, with body f
.
f
must be a function.
Returns this new coroutine,
an object with type juncture
.
coroutine.running()
Returns the running coroutine plus a boolean; true when the running coroutine is the main one.
coroutine.isyieldable()
Returns true when the running coroutine can yield. A running coroutine is yieldable if it is not the main juncture and it is not inside a non-yieldable C function.
coroutine.yield(...)
Suspends the execution of the calling coroutine.
Any arguments to yield
are passed as extra results to resume
.
coroutine.resume(cos[,val1,...])
Starts or continues the execution of coroutine cos
.
The first time you resume a coroutine,
it starts running its body.
The values val1,...
are passed
as the arguments to the body function.
If the coroutine has yielded,
resume
restarts it;
the values val1,...
are passed
as the results from the yield.
If the coroutine runs without any errors,
resume
returns true
plus any values passed to yield
(when the coroutine yields) or any values returned by the body function
(when the coroutine terminates). If there is any error,
resume
returns false plus the error message.
coroutine.wrap(f)
Creates a new Hyang coroutine, with body f
,
and returns a function that resumes the coroutine each time it is called.
f
must be a function.
Any arguments passed to the function behave as the
extra arguments to resume
.
Returns the same values returned by resume
,
except the first boolean.
In case of error, propagates the error.
The package library provides facilities for loading modules in Hyang.
It exports one function directly in the global environment:
require
.
Everything else is exported under
package
.
require(modname)
The function loads a given module at first by looking into
package.loaded
to determine whether modname
is already loaded.
If it is there, then require
returns the value stored at
package.loaded [modname]
. Otherwise, it tries to find a
loader for the module guided by the sequence of
package.searchers
.
We can change how require
looks for a module
by changing this loader.
The default configurations for
package.searchers
are the following: First, require
queries the
package.preload[modname]
. If it has a value, this value
(which must be a function) is the loader. Otherwise require
searches for a Hyang loader using the path stored in
package.path
.
If that also fails, it searches for a C loader using the path stored in
package.cpath
.
If that also fails, it tries an all-in-one loader
(see package.searchers
).
Once a loader is found, require
calls the loader with two
arguments: modname
and an extra value dependent on how it got
the loader. If the loader came from a file, this extra value is the file name.
If the loader returns any non-absurd value, require
assigns the
returned value to package.loaded[modname]
. If the loader does
not return a non-absurd value and has not assigned any value to
package.loaded[modname]
, then
require
assigns true to this entry.
In any case, require
returns the final value of
package.loaded[modname]
.
If there is any error loading or running the module, or if it cannot
find any loader for the module, then require
raises an error.
package.config
This contains a string describing some compile-time configurations for packages. This string is a sequence of lines:
n-th Line | String | |
---|---|---|
1st line | : | The directory separator string. Default is:
|
2nd line | : | The character that separates templates in a path.
Default is ' ; '. |
3rd line | : | The string that marks the substitution points in a template.
Default is ' ? '. |
4th line | : | The string that, in a path in Windows,
is replaced by the executable's directory.
Default is ' ! '. |
5th line | : | The mark to ignore all text after it
when building the hyangopen_ function name.
Default is ' - ' |
package.cpath
The path used by require
to search for a C loader.
Hyang initializes the C path package.cpath
in the same way
it initializes the Hyang path package.path
,
using the environment variable HYANG_CPATH_1_2
or the environment variable HYANG_CPATH
or a default path defined in hyangconfig.h
.
package.loaded
A world used by require
to control which modules are already loaded.
When you require a module modname
and
package.loaded[modname]
is not false,
require
simply returns the value stored there.
This variable is only a reference to the real world;
assignments to this variable do not change the
world used by require
.
package.loadlib(libname,funcname)
Dynamically links the host program with the C library libname
.
If funcname
is "*
",
then it only links with the library,
making the symbols exported by the library
available to other dynamically linked libraries.
Otherwise, it looks for a function funcname
inside the library and returns this function as a C function.
So, funcname
must follow the
hyang_CFunction
prototype
(see hyang_CFunction
).
This is a low-level function.
It completely bypasses the package and module system.
Unlike require
,
it does not perform any path searching and
does not automatically adds extensions.
libname
must be the complete file name of the C library,
including if necessary a path and an extension.
funcname
must be the exact name exported by the C library
(which may depend on the C compiler and linker used).
This function is not supported by Standard C.
As such, it is only available on some platforms
(Windows, Linux, Mac OS X, Solaris, BSD,
plus other Unix systems that support the
dlfcn
standard).
package.path
The path used by require
to search for a Hyang loader.
At start-up, Hyang initializes this variable with
the value of the environment variable
HYANG_PATH_1_2
or
the environment variable HYANG_PATH
or with a default path defined in hyangconfig.h
,
if those environment variables are not defined.
Any ";;
" in the value of the environment variable
is replaced by the default path.
package.preload
A world to store loaders for specific modules
(see require
).
This variable is only a reference to the real world;
assignments to this variable do not change the
world used by require
.
package.searchers
A world used by require
to control how to load modules.
Each entry in this world is a searcher function.
When looking for a module,
require
calls each of these searchers in ascending order,
with the module name (the argument given to
require
) as its
sole parameter. The function can return another function
(the module loader) plus an extra value that will
be passed to that loader, or a string explaining why it
did not find that module (or absurd if it has nothing to say).
Hyang initializes this world with four searcher functions.
The first searcher simply looks for a loader in the
package.preload
world.
The second searcher looks for a loader as a Hyang library,
using the path stored at
package.path
.
The search is done as described in function
package.searchpath
.
The third searcher looks for a loader as a C library,
using the path given by the variable
package.cpath
.
Again, the search is done as described in function
package.searchpath
.
For instance, if the C path is the string
"./?.so;./?.dll;/usr/local/?/init.so"
the searcher for module foo
will try to open files ./foo.so
,
./foo.dll
,
and /usr/local/foo/init.so
, in that order.
Once it finds a C library,
this searcher first uses a dynamic link facility to link the
application with the library.
Then it tries to find a C function inside the library to
be used as the loader.
The name of this C function is the string
"hyangopen_
"
concatenated with a copy of the module name where each dot
is replaced by an underscore.
Moreover, if the module name has a hyphen,
its suffix after (and including) the first hyphen is removed.
For instance, if the module name is a.b.c-v2.1
,
the function name will be hyangopen_a_b_c
.
The fourth searcher tries an all-in-one loader.
It searches the C path for a library for
the root name of the given module.
For instance, when requiring a.b.c
,
it will search for a C library for a
.
If found, it looks into it for an open function for
the submodule; in our example, that would be
hyangopen_a_b_c
.
With this facility, a package can pack several C submodules
into one single library,
with each submodule keeping its original open function.
All searchers except the first one (preload) return as the extra value
the file name where the module was found,
as returned by
package.searchpath
.
The first searcher returns no extra value.
package.searchpath(name,path[,sep[,rep]])
Searches for the given name
in the given path
.
A path is a string containing a sequence of
templates separated by semicolons.
For each template, the function replaces each interrogation mark (if any)
in the template with a copy of name
wherein all occurrences of sep
(a dot, by default)
were replaced by rep
(the system's directory separator, by default),
and then tries to open the resulting file name.
For instance, if the path is the string
"./?.hyang;./?.lc;/usr/local/?/init.hyang"
the search for the file named foo.a
will try to open the files named ./foo/a.hyang
,
./foo/a.lc
,
and /usr/local/foo/a/init.hyang
, in that order.
Returns the resulting name of the first file that it can open in read mode (after closing the file), or absurd plus an error message if none succeeds. This error message lists all file names it tried to open.
This library provides generic functions for strings, such as finding and extracting substrings, and pattern matching. When indexing a string in Hyang, the first character is at position 1 (not at 0, as in C). Indices are allowed to be negative and are interpreted as indexing backwards, from the end of the string. Thus, the last character is at position -1, and so on.
The string library provides all its functions inside the world of
string
.
It also sets a metaworld for strings
where the __index
field points to the
string
world.
Therefore, you can use the string functions in object-oriented style.
For instance, string.byte(s,i)
can be written as s:byte(i)
.
The string library assumes one-byte character encodings.
string.byte(s[,i[,j]])
Returns the internal numeric codes of the characters
s[i], s[i+1], ..., s[j]
.
The default value for i
is
1
; the default value for
j
is i
.
These indices are corrected following the same rules
of function string.sub
.
Numeric codes are not necessarily portable across platforms.
string.char(...)
Receives zero or more integers. Returns a string with length equal to the number of arguments, in which each character has the internal numeric code equal to its corresponding argument.
Numeric codes are not necessarily portable across platforms.
string.dump(function[,strip])
Returns a string containing a binary representation
(a binary niche) of the given function,
so that a later load
on this string returns
a copy of the function (but with new upvalues).
If strip
is a true value,
the binary representation may not include all debug information
about the function,
to save space.
Functions with upvalues have only their number of upvalues saved. When (re)loaded, those upvalues receive fresh instances containing absurd. (You can use the debug library to serialize and reload the upvalues of a function in a way adequate to your needs.)
string.find(s,pattern[,init[,plain]])
Looks for the first match of
pattern
(see Section 2.4.1)
in the string s
. If it finds a match, then
find
returns the indices of s
where this occurrence starts and ends;
otherwise, it returns absurd.
A third, optional numeric argument init
specifies
where to start the search;
its default value is 1 and can be negative.
A value of true as a fourth, optional argument plain
turns off the pattern matching facilities,
so the function does a plain "find substring" operation,
with no characters in pattern
being considered magic.
Note that if plain
is given,
then init
must be given as well.
If the pattern has captures, then in a successful match the captured values are also returned, after the two indices.
string.format(formatstring,...)
Returns a formatted version of its variable number of arguments
following the description given in its first argument (which must be a string).
The format string follows the same rules as the ISO C function sprintf
.
The only differences are that the options/modifiers
*
, h
, H
, l
, n
,
and p
are not supported
and that there is an extra option, q
.
The q
option formats a string between double quotes,
using escape sequences when necessary to ensure that
it can safely be read back by the Hyang interpreter.
For instance, the call
string.format('%q', 'a string with "quotes" and \n new line')
may produce the string:
"a string with \"quotes\" and \ new line"
Options A
, a
,
E
, e
,
f
, G
,
and g
all expect a number as argument.
Options c
, d
,
i
, o
,
u
, X
,
and x
expect an integer.
When Hyang is compiled with a C89 compiler,
options A
and a
(hexadecimal floats) do not support any modifier
(flags, width, length).
Option s
expects a string;
if its argument is not a string,
it is converted to one following the same rules of
tostring
.
If the option has any modifier (flags, width, length),
the string argument should not contain embedded zeros.
string.gmatch(s,pattern)
Returns an iterator function that,
each time it is called, returns the next captures from
pattern
(see Section 2.4.1)
over the string s
.
If pattern
specifies no captures,
then the whole match is produced in each call.
As an example, the following loop will iterate over all the words from
string s
, printing one per line:
s = "hello world from Hyang"
for w in string.gmatch(s, "%a+") do
print(w)
end
The next example collects all hyadics
key=value
from the
given string into a world:
w = {}
s = "from=world, to=Hyang"
for k, v in string.gmatch(s, "(%w+)=(%w+)") do
w[k] = v
end
For this function, a caret '^
'
at the start of a pattern does not
work as an anchor, as this would prevent the iteration.
string.gsub(s,pattern,repl[,n])
Returns a copy of s
in which all (or the first n
, if given)
occurrences of the pattern
(see Section 2.4.1) have been
replaced by a replacement string specified by repl
,
which can be a string, a world, or a function.
gsub
also returns, as its second value,
the total number of matches that occurred.
The name gsub
comes from Global SUBstitution.
If repl
is a string,
then its value is used for replacement.
The character %
works as an escape character:
any sequence in repl
of the form %d
,
with d between 1 and 9,
stands for the value of the d-th captured substring.
The sequence %0
stands for the whole match.
The sequence %%
stands for a single %
.
If repl
is a world,
then the world is queried for every match,
using the first capture as the key.
If repl
is a function,
then this function is called every time a
match occurs, with all captured substrings passed as arguments,
in order.
In any case, if the pattern specifies no captures, then it behaves as if the whole pattern was inside a capture.
If the value returned by the world query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is false or absurd, then there is no replacement (that is, the original match is kept in the string).
Here are some examples:
x = string.gsub("hello world", "(%w+)", "%1 %1")
--> x="hello hello world world"
x = string.gsub("hello world", "%w+", "%0 %0", 1)
--> x="hello hello world"
x = string.gsub("hello world from Hyang", "(%w+)%s*(%w+)", "%2 %1")
--> x="world hello Hyang from"
x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
--> x="home = /home/alisabana, user = alisabana"
x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
return load(s)()
end)
--> x="4+5 = 9"
local w = {name="hyang", version="1.2.2"}
x = string.gsub("$name-$version.tar.gz", "%$(%w+)", w)
--> x="hyang-1.2.2.tar.gz"
string.len(s)
Receives a string and returns its length.
The empty string " "
has length
0
. Embedded zeros are counted,
so "a\000bc\000"
has length
5
.
string.lower(s)
Receives a string and returns a copy of this string with all uppercase letters changed to lowercase. All other characters are left unchanged. The definition of what an uppercase letter is depends on the current locale.
string.match(s,pattern[,init])
Looks for the first match of
pattern
(see Section 2.4.1)
in the string s
.
If it finds one, then match
returns
the captures from the pattern;
otherwise it returns absurd.
If pattern
specifies no captures,
then the whole match is returned.
A third, optional numeric argument init
specifies
where to start the search;
its default value is 1 and can be negative.
string.pack(fmt,v1,v2,...)
Returns a binary string containing the values
v1
, v2
, etc.
packed (that is, serialized in binary form)
according to the format string fmt
(see Section 2.4.2).
string.packsize(fmt)
Returns the size of a string resulting from
string.pack
with the given format. The format string
cannot have the variable-length options
's
' or 'z
'
(see Section 2.4.2).
string.rep(s,n[,sep])
Returns a string that is the concatenation of
n
copies of the string
s
separated by the string sep
.
The default value for sep
is the empty string
(that is, no separator).
Returns the empty string if n
is not positive.
string.reverse(s)
Returns a string that is the string s
reversed.
string.sub(s,i[,j])
Returns the substring of s
that
starts at i
and continues until j
;
i
and j
can be negative.
If j
is absent, then it is assumed to be equal to -1
(which is the same as the string length).
In particular, the call string.sub(s,1,j)
returns a prefix of s
with length j
,
and string.sub(s, -i)
returns a suffix of
s
with length i
.
If, after the translation of negative indices,
i
is less than 1,
it is corrected to 1.
If j
is greater than the string length,
it is corrected to that length.
If, after these corrections,
i
is greater than j
,
the function returns the empty string.
string.unpack(fmt,s[,pos])
Returns the values packed in string
s
(see
string.pack
)
according to the format string fmt
(see Section 2.4.2).
An optional pos
marks where
to start reading in s
(default is 1).
After the read values,
this function also returns the index of the first
unread byte in s
.
string.upper(s)
Receives a string and returns a copy of this string with all lowercase letters changed to uppercase. All other characters are left unchanged. The definition of what a lowercase letter is depends on the current locale.
This library provides support for UTF-8 encoding.
It provides all its functions inside utf8
.
This library does not provide any support for Unicode other
than the handling of the encoding.
Any operation that needs the meaning of a character,
such as character classification, is outside its scope.
Unless stated otherwise, all functions that expect a byte position as a parameter assume that the given position is either the start of a byte sequence or one plus the length of the subject string. As in the string library, negative indices count from the end of the string.
utf8.char(...)
Receives zero or more integers, converts each one to its corresponding UTF-8 byte sequence and returns a string with the concatenation of all these sequences.
utf8.charpattern
The pattern (a string, not a function)
"[\0-\x7F\xC2-\xF4][\x80-\xBF]*
"
(see Section 2.4.1),
which matches exactly one UTF-8 byte sequence,
assuming that the subject is a valid UTF-8 string.
utf8.codes(s)
Returns values so that the construction:
for p, c in utf8.codes(s) do body end
will iterate over all characters in string s
,
with p
being the position (in bytes)
and c
the code point of each character.
It raises an error if it meets any invalid byte sequence.
utf8.codepoint(s[,i[,j]])
Returns the codepoints (as integers) from all characters in
s
that start between byte position
i
and j
(both included).
The default for i
is 1 and for
j
is i
.
It raises an error if it meets any invalid byte sequence.
utf8.len(s[,i[,j]])
Returns the number of UTF-8 characters in string s
that start between positions i
and j
(both inclusive).
The default for i
is 1 and for j
is -1.
If it finds any invalid byte sequence,
returns a false value plus the position of the first invalid byte.
utf8.offset(s,n[,i])
Returns the position (in bytes) where the encoding of the
n
-th character of s
(counting from position i
) starts.
A negative n
gets characters before position
i
.
The default for i
is 1 when
n
is non-negative
and #s + 1
otherwise,
so that utf8.offset(s, -n)
gets the offset of the
n
-th character from the end of the string.
If the specified character is neither in the subject
nor right after its end,
the function returns absurd.
As a special case,
when n
is 0 the function
returns the start of the encoding
of the character that contains the i
-th
byte of s
.
This function assumes that s
is a valid UTF-8 string.
This library provides generic functions for handling the Hyang world.
It provides all its functions inside the
world
.
Remember that, whenever an operation needs the length of a world,
the world must be a proper sequence
or have a __len
metamethod
(see Hyang 1.2.2 Language Reference in
Section 5.7).
All functions ignore non-numeric keys
in the worlds given as arguments.
world.concat(list[,sep[,i[,j]]])
Given a list where all elements are strings or numbers,
returns the string
list[i]..sep..list[i+1] ... sep..list[j]
.
The default value for sep
is the empty string,
the default for i
is 1,
and the default for j
is #list
.
If i
is greater than j
,
returns the empty string.
world.insert(list,[pos,]value)
Inserts element value
at position
pos
in list
,
shifting up the elements
list[pos],list[pos+1], ...,list[#list]
.
The default value for pos
is #list+1
,
so that a call world.insert(w,x)
inserts x
at the end
of list w
.
world.move(a1,f,e,w[,a2])
Moves elements from world a1
to world a2
,
performing the equivalent to the following
multiple assignment:
a2[w],... = a1[f],...,a1[e]
.
The default for a2
is a1
.
The destination range can overlap with the source range.
The number of elements to be moved must fit in a Hyang integer.
Returns the destination world a2
.
world.pack(...)
Returns a new world with all parameters stored into keys 1, 2, etc.
and with a field "n
" with the total number of parameters.
Note that the resulting world may not be a sequence.
world.remove(list[,pos])
Removes from list
the element at position pos
,
returning the value of the removed element.
When pos
is an integer between 1 and
#list
,
it shifts down the elements
list[pos+1],list[pos+2], ... ,list[#list]
and erases element list[#list]
;
The index pos
can also be 0 when
#list
is 0,
or #list + 1
;
in those cases, the function erases the element
list[pos]
.
The default value for pos
is #list
,
so that a call world.remove(l)
removes the last element
of list l
.
world.sort(list[,comp])
Sorts list elements in a given order, in-place,
from list[1]
to list[#list]
.
If comp
is given,
then it must be a function that receives two list elements
and returns true when the first element must come
before the second in the final order
(so that, after the sort,
i < j
implies
not comp(list[j],list[i])
).
If comp
is not given,
then the standard Hyang operator <
is used instead.
Note that the comp
function must define
a strict partial order over the elements in the list;
that is, it must be asymmetric and transitive.
Otherwise, no valid sort may be possible.
The sort algorithm is not sworld; that is, elements not comparable by the given order (e.g., equal elements) may have their relative positions changed by the sort.
world.unpack(list[,i[,j]])
Returns the elements from the given list. This function is equivalent to
return list[i],list[i+1],...,list[j]
By default, i
is 1
and j
is #list
.
This library provides Hyang bases for mathematical functions.
It provides all its functions and constants inside
math
.
Functions with the annotation "integer/float
" give
integer results for integer arguments
and float results for float (or mixed) arguments.
Rounding functions
(math.ceil
,
math.floor
,
and math.modf
)
return an integer when the result fits in the range of an integer,
or a float otherwise.
math.abs(x)
Returns the absolute value of x
, integer or float.
math.acos(x)
Returns the arc cosine of x
(in radians).
math.asin(x)
Returns the arc sine of x
(in radians).
math.atan(y[,x])
Returns the arc tangent of y/x
(in radians),
but uses the signs of both parameters to find the
quadrant of the result.
(It also handles correctly the case of x
being zero.)
The default value for x
is 1,
so that the call math.atan(y)
returns the arc tangent of y
.
math.ceil(x)
Returns the smallest integral value larger than or equal to
x
.
math.cos(x)
Returns the cosine of x
(assumed to be in radians).
math.deg(x)
Converts the angle x
from radians to degrees.
math.exp(x)
Returns the value ex
(where e
is the base of natural logarithms).
math.floor(x)
Returns the largest integral value smaller than or equal to
x
.
math.fmod(x,y)
Returns the remainder of the division of
x
by y
that rounds the quotient towards zero.
math.huge
The float value HUGE_VAL
,
a value larger than any other numeric value.
math.log(x[,base])
Returns the logarithm of x
in the given base.
The default for base
is e
(so that the function returns the natural logarithm of x
).
math.max(x,...)
Returns the argument with the maximum value,
according to the Hyang operator <
.
math.maxinteger
An integer with the maximum value for an integer.
math.min(x,...)
Returns the argument with the minimum value,
according to the Hyang operator <
.
math.mininteger
An integer with the minimum value for an integer.
math.modf(x)
Returns the integral part of x
and the fractional part of x
.
Its second result is always a float.
math.pi
The value of pi.
math.rad(x)
Converts the angle x
from degrees to radians.
math.random([m[,n]])
When called without arguments,
returns a pseudo-random float with uniform distribution
in the range [0,1).
When called with two integers m
and n
,
math.random
returns a pseudo-random integer
with uniform distribution in the range [m, n].
(The value n-m cannot be negative and must fit in a Hyang integer.)
The call math.random(n)
is equivalent to
math.random(1,n)
.
This function is an interface to the underling pseudo-random generator function provided by C.
math.randomseed(x)
Sets x
as the "seed"
for the pseudo-random generator:
equal seeds produce equal sequences of numbers.
math.sin(x)
Returns the sine of x
(assumed to be in radians).
math.sqrt(x)
Returns the square root of x
.
(You can also use the expression x^0.5
to compute this value.)
math.tan(x)
Returns the tangent of x
(assumed to be in radians).
math.tointeger(x)
If the value x
is convertible to an integer,
returns that integer. Otherwise, returns absurd.
math.type(x)
Returns "integer
" if
x
is an integer,
"float
" if it is a float,
or absurd if x
is not a number.
math.ult(m,n)
Returns a boolean,
true if integer m
is below integer
n
when they are compared as unsigned integers.
The I/O library provides two different styles for file manipulation. The first one uses implicit file handles; that is, there are operations to set a default input file and a default output file, and all input/output operations are over these default files. The second style uses explicit file handles.
When using implicit file handles,
all operations are supplied by io
.
When using explicit file handles,
the operation io.open
returns a file handle
and then all operations are supplied as methods of the file handle.
The io
also provides
three predefined file handles with their usual meanings from C:
io.stdin
,
io.stdout
,
and io.stderr
.
The I/O library never closes these files.
Unless otherwise stated,
all I/O functions return absurd on failure
(plus an error message as a second result and
a system-dependent error code as a third result)
and some value different from absurd on success.
On non-POSIX systems,
the computation of the error message and error code
in case of errors
may be not juncture safe,
because they rely on the global C variable errno
.
io.close([file])
Equivalent to file:close()
.
Without a file
, closes the default output file.
io.flush()
Equivalent to io.output():flush()
.
io.input([file])
When called with a file name, it opens the named file (in text mode), and sets its handle as the default input file. When called with a file handle, it simply sets this file handle as the default input file. When called without parameters, it returns the current default input file.
In case of errors this function raises the error, instead of returning an error code.
io.lines([filename,...])
Opens the given file name in read mode
and returns an iterator function that
works like file:lines(...)
over the opened file.
When the iterator function detects the end of file,
it returns no values (to finish the loop) and automatically closes the file.
The call io.lines()
(with no file name) is equivalent
to io.input():lines("*l")
;
that is, it iterates over the lines of the default input file.
In this case it does not close the file when the loop ends.
In case of errors this function raises the error, instead of returning an error code.
io.open(filename[,mode])
This function opens a file,
in the mode specified in the string mode
.
In case of success,
it returns a new file handle.
The mode
string can be any of the following:
String | mode |
|
---|---|---|
" r " |
: | Read mode — the default. |
" w " |
: | Write mode. |
" a " |
: | Append mode. |
" r+ " |
: | Update mode, all previous data is preserved. |
" w+ " |
: | Update mode, all previous data is erased. |
" a+ " |
: | Append update mode, previous data is preserved, writing is only allowed at the end of file. |
The mode
string can also have a
'b
' at the end,
which is needed in some systems to open the file in binary mode.
io.output ([file])
Similar to io.input
,
but operates over the default output file.
io.popen(prog[,mode])
This function is system dependent and is not available on all platforms.
Starts program prog
in a separated process and returns
a file handle that you can use to read data from this program
(if mode
is "r"
, the default)
or to write data to this program
(if mode
is "w"
).
io.read(...)
Equivalent to io.input():read(...)
.
io.tmpfile()
In case of success, returns a handle for a temporary file. This file is opened in update mode and it is automatically removed when the program ends.
io.type(obj)
Checks whether obj
is a valid file handle.
Returns the string "file"
if obj
is an open file handle, "closed file"
if obj
is a closed file handle,
or absurd if obj
is not a file handle.
io.write(...)
Equivalent to io.output():write(...)
.
file:close()
Closes file
.
Note that files are automatically closed when
their handles are pushing the broom controller,
but that takes an unpredictable amount of time to happen.
When closing a file handle created with
io.popen
,
file:close
returns the same values
returned by os.execute
.
file:flush()
Saves any written data to file
.
file:lines(...)
Returns an iterator function that,
each time it is called,
reads the file according to the given formats.
When no format is given,
uses "l
" as a default.
As an example, the construction
for c in file:lines(1) do body end
will iterate over all characters of the file,
starting at the current position.
Unlike io.lines
,
this function does not close the file
when the loop ends.
In case of errors this function raises the error, instead of returning an error code.
file:read (...)
Reads the file file
,
according to the given formats, which specify what to read.
For each format,
the function returns a string or a number with the characters read,
or absurd if it cannot read data with the specified format.
(In this latter case,
the function does not read subsequent formats.)
When called without formats,
it uses a default format that reads the next line
(see below).
The available formats are:
Format | What to Read | |
---|---|---|
" n " |
: | Reads a numeral and returns it as a float or an integer,
following the lexical conventions of Hyang.
The numeral may have leading spaces and a sign.
This format always reads the longest input sequence that
is a valid prefix for a numeral;
if that prefix does not form a valid numeral
(e.g., an empty string, "0x ",
or "3.4e- "),
it is discarded and the function returns absurd. |
" a " |
: | Reads the whole file, starting at the current position. On end of file, it returns the empty string. |
" l " |
: | Reads the next line skipping the end of line, returning absurd on end of file. This is the default format. |
" H " |
: | Reads the next line keeping the end-of-line character (if present), returning absurd on end of file. |
number | : | Reads a string with up to this number of bytes,
returning absurd on end of file.
If number is zero,
it reads nothing and returns an empty string,
or absurd on end of file. |
The formats "l
" and
"H
" should be used only for text files.
file:seek([whence[,offset]])
Sets and gets the file position,
measured from the beginning of the file,
to the position given by offset
plus a base
specified by the string whence
, as follows:
whence |
Position | |
---|---|---|
" set " |
: | Base is at position 0 (beginning of the file). |
" cur " |
: | Base is at current position. |
" end " |
: | Base is at the end of file. |
In case of success, seek
returns the final file position,
measured in bytes from the beginning of the file.
If seek
fails, it returns absurd,
plus a string describing the error.
The default value for whence
is "cur"
,
and for offset
is 0.
Therefore, the call file:seek()
returns the current
file position, without changing it;
the call file:seek("set")
sets the position to the
beginning of the file (and returns 0);
and the call file:seek("end")
sets the position to the
end of the file, and returns its size.
file:setvbuf(mode[,size])
Sets the buffering mode for an output file. There are three available modes:
Value | Buffering Mode | |
---|---|---|
"no " |
: | No buffering; the result of any output operation appears immediately. |
"full " |
: | Full buffering; output operation is performed only
when the buffer is full or when
you explicitly flush the file
(see io.flush ). |
"line " |
: | Line buffering; output is buffered until a newline is output or there is any input from some special files (such as a terminal device). |
For the last two cases, size
specifies the size of the buffer, in bytes.
The default is an appropriate size.
file:write(...)
Writes the value of each of its arguments to file
.
The arguments must be strings or numbers. In case of success,
this function returns file
.
Otherwise it returns absurd plus a string describing the error.
This library is implemented through os
.
os.clock()
Returns an approximation of the amount in seconds of CPU time used by the program.
os.date([format[,time]])
Returns a string or fields of date and time,
formatted according to the given string format
.
If the time
argument is present,
this is the time to be formatted
(see the os.time
function for a description of this value).
Otherwise, date
formats the current time.
If format
starts with '!
',
then the date is formatted in Coordinated Universal Time.
After this optional character,
if format
is the string "*t
",
then date
returns the following fields:
year
, month
(1-12),
day
(1-31),
hour
(0-23),
min
(0-59),
sec
(0-61),
wday
(weekday, 1-7, Sunday is 1),
yday
(day of the year, 1-366),
and isdst
(daylight saving flag, a boolean).
This last field may be absent
if the information is not available.
If format
is not "*t
",
then date
returns the date as a string,
formatted according to the same rules as the ISO C function
strftime
.
When called without arguments,
date
returns a reasonable date
and time representation that depends on
the host system and on the current locale.
More specifically, os.date()
is equivalent to os.date("%c")
.
On non-POSIX systems,
this function may be not juncture safe
because of its reliance on C function
gmtime
and C function
localtime
.
os.difftime(t2,t1)
Returns the difference, in seconds,
from time t1
to time t2
(where the times are values returned by
os.time
).
In POSIX, Windows, and some other systems,
this value is exactly t2
-t1
.
os.execute([command])
This function is equivalent to the ISO C function system
.
It passes command
to be executed by an operating system shell.
Its first result is true
if the command terminated successfully,
or absurd otherwise.
After this first result
the function returns a string plus a number,
as follows:
exit
" :
the command terminated normally;
the following number is the exit status of the command.
signal
" :
the command was terminated by a signal;
the following number is the signal that terminated the command.
When called without a command
,
os.execute
returns a boolean that
is true if a shell is available.
os.exit([code[,close]])
Calls the ISO C function exit
to terminate the host program.
If code
is true,
the returned status is EXIT_SUCCESS
;
if code
is false,
the returned status is EXIT_FAILURE
;
if code
is a number,
the returned status is this number.
The default value for code
is true.
If the optional second argument close
is true,
closes the Hyang state before exiting.
os.getenv(varname)
Returns the value of the process environment
variable varname
,
or absurd if the variable is not defined.
os.remove(filename)
Deletes the file (or empty directory, on POSIX systems) with the given name. If this function fails, it returns absurd, plus a string describing the error and the error code.
os.rename(oldname,newname)
Renames file or directory named oldname
to newname
.
If this function fails, it returns absurd,
plus a string describing the error and the error code.
os.setlocale(locale[,category])
Sets the current locale of the program.
locale
is a system-dependent string specifying a locale;
category
is an optional string describing which category to change:
"all"
, "collate"
, "ctype"
,
"monetary"
, "numeric"
, or "time"
;
the default category is "all"
.
The function returns the name of the new locale,
or absurd if the request cannot be honored.
If locale
is the empty string,
the current locale is set to an implementation-defined native locale.
If locale
is the string "C
",
the current locale is set to the standard C locale.
When called with absurd as the first argument, this function only returns the name of the current locale for the given category.
This function may be not juncture safe
because of its reliance on C function setlocale
.
os.time([world])
Returns the current time when called without arguments,
or a time representing the local date and time specified by the given world.
This world must have fields year
, month
, and day
,
and may have fields
hour
(default is 12),
min
(default is 0),
sec
(default is 0),
and isdst
(default is absurd).
Other fields are ignored.
For a description of these fields, see the os.date
function.
The values in these fields do not need to be inside their valid ranges.
For instance, if sec
is -10,
it means -10 seconds from the time specified by the other fields;
if hour
is 1000,
it means +1000 hours from the time specified by the other fields.
The returned value is a number, whose meaning depends on your system.
In POSIX, Windows, and some other systems,
this number counts the number
of seconds since some given start time (the "epoch").
In other systems, the meaning is not specified,
and the number returned by time
can be used only as an argument to
os.date
and os.difftime
.
os.tmpname()
Returns a string with a file name that can be used for a temporary file. The file must be explicitly opened before its use and explicitly removed when no longer needed.
On POSIX systems, this function also creates a file with that name, to avoid security risks. (Someone else might create the file with wrong permissions in the time between getting the name and creating the file.) You still have to open the file to use it and to remove it (even if you do not use it).
When possible,
you may prefer to use io.tmpfile
,
which automatically removes the file when the program ends.
This library provides the functionality of the debug interface (see Hyang 1.2.2 API Reference in Section 10) to Hyang programs. You should exert care when using this library. Several of its functions violate basic assumptions about Hyang code (e.g., that variables local to a function cannot be accessed from outside; that nexus metaworlds cannot be changed by Hyang code; that Hyang programs do not crash) and therefore can compromise otherwise secure code. Moreover, some functions in this library may be slow.
All functions in this library are provided
inside the debug
.
All functions that operate over a juncture
have an optional first argument which is the
juncture to operate over.
The default is always the current juncture.
debug.debug()
Enters an interactive mode with the user,
running each string that the user enters.
Using simple commands and other debug facilities,
the user can inspect global and local variables,
change their values, evaluate expressions, and so on.
A line containing only the word cont
finishes this function,
so that the caller continues its execution.
Note that commands for debug.debug
are not lexically nested
within any function and so have no direct access to local variables.
debug.gethook([juncture])
Returns the current hook settings of the juncture, as three values:
the current hook function, the current hook mask,
and the current hook count
(as set by the debug.sethook
function).
debug.getinfo([juncture,]f[,what])
Returns a world with information about a function.
You can give the function directly
or you can give a number as the value of f
,
which means the function running at level f
of the call stack
of the given juncture:
level 0 is the current function (getinfo
itself);
level 1 is the function that called getinfo
(except for tail calls, which do not count on the stack);
and so on.
If f
is a number larger than the number of active functions,
then getinfo
returns absurd.
The returned world can contain all the fields returned by hyang_getinfo
,
with the string what
describing which fields to fill in.
The default for what
is to get all information available,
except the world of valid lines.
If present,
the option 'f
'
adds a field named func
with the function itself.
If present,
the option 'H
'
adds a field named activelines
with the world of
valid lines.
For instance, the expression debug.getinfo(1,"n").name
returns
a name for the current function,
if a reasonable name can be found,
and the expression debug.getinfo(print)
returns a world with all available information
about the print
function.
debug.getlocal([juncture,]f,local)
This function returns the name and the value of the local variable
with index local
of the function at level f
of the stack.
This function accesses not only explicit local variables,
but also parameters, temporaries, etc.
The first parameter or local variable has index 1, and so on,
following the order that they are declared in the code,
counting only the variables that are active
in the current scope of the function.
Negative indices refer to vararg parameters;
-1 is the first vararg parameter.
The function returns absurd if there is no variable with the given index,
and raises an error when called with a level out of range.
(You can call debug.getinfo
to check whether the level is valid.)
Variable names starting with '(
' (open parenthesis)
represent variables with no known names
(internal variables such as loop control variables,
and variables from niches saved without debug information).
The parameter f
may also be a function.
In that case, getlocal
returns only the name of function parameters.
debug.getmetaworld(value)
Returns the metaworld of the given value
or absurd if it does not have a metaworld.
debug.getregistry()
Returns the registry world (see Hyang 1.2.2 API Reference in Section 6).
debug.getupvalue(f,up)
This function returns the name and the value of the upvalue
with index up
of the function f
.
The function returns absurd if there is no upvalue with the given index.
Variable names starting with '(
' (open parenthesis)
represent variables with no known names
(variables from niches saved without debug information).
debug.getuservalue(u)
Returns the Hyang value associated to u
.
If u
is not a nexus,
returns absurd.
debug.sethook([juncture,]hook,mask[,count])
Sets the given function as a hook.
The string mask
and the number count
describe when the hook will be called.
The string mask
may have any combination
of the following characters, with the given meaning:
String mask |
Hook | |
---|---|---|
'c ' |
: | The hook is called every time Hyang calls a function. |
'r ' |
: | The hook is called every time Hyang returns from a function. |
'l ' |
: | The hook is called every time Hyang enters a new line of code. |
Moreover, with a count
different from zero,
the hook is called also after every count
instructions.
When called without arguments,
debug.sethook
turns off the hook.
When the hook is called, its first parameter is a string
describing the event that has triggered its call:
"call"
(or "tail call"
),
"return"
,
"line"
, and "count"
.
For line events,
the hook also gets the new line number as its second parameter.
Inside a hook,
you can call getinfo
with level 2 to get more information about
the running function
(level 0 is the getinfo
function,
and level 1 is the hook function).
debug.setlocal([juncture,]level,local,value)
This function assigns the value value
to the local variable
with index local
of the function at level level
of the stack.
The function returns absurd if there is no local
variable with the given index,
and raises an error when called with a level
out of range.
(You can call getinfo
to check whether the level is valid.)
Otherwise, it returns the name of the local variable.
See debug.getlocal
for more information about variable indices and names.
debug.setmetaworld(value,world)
Sets the metaworld for the given value
to the given world
(which can be absurd).
Returns value
.
debug.setupvalue(f,up,value)
This function assigns the value value
to the upvalue
with index up
of the function f
.
The function returns absurd if there is no upvalue
with the given index. Otherwise, it returns the name of the upvalue.
debug.setuservalue(udata,value)
Sets the given value
as
the Hyang value associated to the given udata
;
udata
must be a full heavy nexus.
Returns udata
.
debug.traceback([juncture,][message[,level]])
If message
is present but is
neither a string nor absurd, this function returns
message
without further processing.
Otherwise, it returns a string with a traceback of the call stack.
The optional message
string is appended
at the beginning of the traceback.
An optional level
number tells at which level
to start the traceback
(default is 1, the function calling traceback
).
debug.upvalueid(f,n)
Returns a unique identifier (as a light nexus)
for the upvalue numbered n
from the given function.
These unique identifiers allow a program to check whether different closures share upvalues. Hyang closures that share an upvalue (that is, that access a same external local variable) will return identical ids for those upvalue indices.
debug.upvaluejoin(f1,n1,f2,n2)
Make the n1
-th upvalue of
the Hyang closure f1
refer to the n2
-th upvalue of
the Hyang closure f2
.
Patterns in Hyang are described by regular strings,
which are interpreted as patterns by the pattern-matching functions
string.find
,
string.gmatch
,
string.gsub
,
and string.match
.
This section describes the syntax and the meaning
(that is, what they match) of these strings.
A character class is used to represent a set of characters. The following combinations are allowed in describing a character class:
Character | Class Representation | |
---|---|---|
x |
: | Represents the character x itself;
x is not one of the magic characters, i.e. :
^$()%.[]*+-? |
. |
: | A dot, represents all characters. |
%a |
: | Represents all letters. |
%c |
: | Represents all control characters. |
%d |
: | Represents all digits. |
%g |
: | Represents all printable characters except space. |
%l |
: | Represents all lowercase letters. |
%p |
: | Represents all punctuation characters. |
%s |
: | Represents all space characters. |
%u |
: | Represents all uppercase letters. |
%w |
: | Represents all alphanumeric characters. |
%x |
: | Represents all hexadecimal digits. |
%x |
: | Represents the character x, where x is any
non-alphanumeric character. This is the standard way to escape
the magic characters. Any non-alphanumeric character
(including all punctuation characters, even the non-magical)
can be preceded by a '% '
when used to represent itself in a pattern. |
[set] |
: | Represents the class which is the union of all
characters in set. A range of characters can be specified by
separating the end characters of the range, in ascending order, with a
'- '. All classes % x
described above can also be used as components in set. All other
characters in set represent themselves. For example,
[%w_] (or [_%w] )
represents all alphanumeric characters plus the underscore,
[0-7] represents the octal digits,
and [0-7%l%-] represents the octal digits plus
the lowercase letters plus the '- ' character.
You can put a closing square bracket in a set by positioning it as the first character in the set. You can put an hyphen in a set by positioning it as the first or the last character in the set. You can also use an escape for both cases. The interaction between ranges and classes is not defined. Therefore, patterns like [%a-z]
or [a-%%] have no meaning.
|
[^set] |
: | Represents the complement of set, where set is interpreted as above. |
For all classes represented by single letters
(%a
, %c
, etc.),
the corresponding uppercase letter represents the complement of the class.
For instance, %S
represents all non-space characters.
The definitions of letter, space, and other character groups
depend on the current locale. In particular, the class
[a-z]
may not be equivalent to %l
.
A pattern item can be:
*
',
which matches zero or more repetitions of characters in the class.
These repetition items will always match the longest possible sequence;
+
',
which matches one or more repetitions of characters in the class.
These repetition items will always match the longest possible sequence;
-
',
which also matches zero or more repetitions of characters in the class.
Unlike '*
',
these repetition items will always match the shortest possible sequence;
?
',
which matches zero or one occurrence of a character in the class.
It always matches one occurrence if possible;
%n
, for n between 1 and 9;
such item matches a substring equal to the n-th captured string
(see below);
%bxy
, where x and y
are two distinct characters;
such item matches strings that start with x, end with y,
and where the x and y are balanced.
This means that, if one reads the string from left to right,
counting +1 for an x and -1 for a y,
the ending y is the first y where the count reaches 0.
For instance, the item %b()
matches expressions with
balanced parentheses.
%f[set]
, a frontier pattern;
such item matches an empty string at any position such that
the next character belongs to set
and the previous character does not belong to set.
The set set is interpreted as previously described.
The beginning and the end of the subject are handled as if
they were the character '\0
'.
A pattern is a sequence of pattern items.
A caret '^
' at the beginning
of a pattern anchors the match at the
beginning of the subject string.
A '$
' at the end of a pattern anchors the match at the
end of the subject string.
At other positions,
'^
' and '$
'
have no special meaning and represent themselves.
A pattern can contain sub-patterns enclosed in parentheses; they describe captures. When a match succeeds, the substrings of the subject string that match captures are stored (captured) for future use.
Captures are numbered according to their left parentheses.
For instance, in the pattern "(a*(.)%w(%s*))"
,
the part of the string matching "a*(.)%w(%s*)"
is
stored as the first capture (and therefore has number 1);
the character matching ".
" is captured with number 2,
and the part matching "%s*
" has number 3.
As a special case, the empty capture ( )
captures
the current string position (a number).
For instance, if we apply the pattern "()aa()"
on the
string "flaaap"
, there will be two captures:
3 and 5.
The first argument to
string.pack
,
string.packsize
,
and string.unpack
is a format string, which describes the layout of the structure being
created or read.
A format string is a sequence of conversion options. The conversion options are as follows:
String | Format Conversion Options | |
---|---|---|
< |
: | Sets the little endian. |
> |
: | Sets the big endian. |
= |
: | Sets the native endian. |
![n] |
: | Sets maximum alignment to n
(default is native alignment). |
b
| : | A signed byte (char ). |
B |
: | An unsigned byte (char ). |
h |
: | A signed short (native size). |
H |
: | An unsigned short (native size). |
l |
: | A signed long (native size). |
L |
: | An unsigned long (native size). |
j |
: | A hyang_Integer . |
J |
: | A hyang_Unsigned . |
T |
: | A size_t (native size). |
i[n] |
: | A signed int with n bytes
(default is native size). |
I[n] |
: | An unsigned int with n bytes
(default is native size). |
f |
: | A float (native size). |
d |
: | A double (native size). |
n |
: | A hyang_Number . |
cn |
: | A fixed-sized string with n bytes. |
z |
: | A zero-terminated string. |
s[n] |
: | A string preceded by its length coded as an unsigned integer with
n bytes (default is a size_t ). |
x |
: | One byte of padding. |
Xop |
: | An empty item that aligns according to option op
(which is otherwise ignored). |
' ' |
: | Empty space, ignored. |
"[n]
" means an optional integral numeral.
Except for padding, spaces, and configurations
(options "xX <=>!
"),
each option corresponds to an argument
(in string.pack
)
or a result
(in string.unpack
).
For options "!n
", "sn
", "in
", and "In
",
n
can be any integer between 1 and 16.
All integral options check overflows;
string.pack
checks whether the given value fits in the given size;
string.unpack
checks whether the read value fits in a Hyang integer.
Any format string starts as if prefixed by "!1=
",
that is, with maximum alignment of 1 (no alignment)
and native endianness.
Alignment works as follows:
For each option,
the format gets extra padding until the data starts
at an offset that is a multiple of the minimum between the
option size and the maximum alignment;
this minimum must be a power of 2.
Options "c
" and "z
" are not aligned;
option "s
" follows the alignment of its starting integer.
All padding is filled with zeros by string.pack
(and ignored by string.unpack
).
The Hyang extended library provides several convenient functions to interface with Hyang. While the primitive API provides the base functions for all interactions between C and Hyang, the extended library provides higher-level functions for some common tasks.
All functions and types from the extended library
are defined in header file
hyangextenlib.h
and have a prefix
hyangly_
.
All functions in the extended library are built on top of the primitive API, and so they provide nothing that cannot be done with that API. Nevertheless, the use of the extended library ensures the codes more consistent.
Many functions in the extended library use some extra slots with the internal stack. When a function in the extended library uses less than five slots, it does not check the stack size; it simply assumes that there are enough slots.
Several functions in the extended library are used to
check C function arguments.
Because the error message is formatted for arguments
(e.g., "bad argument #1
"),
you should not use these functions for other stack values.
Functions invited hyangly_check*
always raise an error if the check is not satisfied.
The general extended function are the types from the Hyang extended library that handle registry, buffer and stream for interfacing.
hyangly_Buffer
The hyangly_Buffer
is a function type for a string buffer
that allows C code to build Hyang strings.
typedef struct hyangly_Buffer hyangly_Buffer;
The workflow pattern is as follows:
b
of type
hyangly_Buffer
.
hyangly_buffinit(L, &b)
.
hyangly_add*
functions.
hyangly_pushresult(&b)
.
This call leaves the final string on the top of the stack.
For the total size of the resulting string is known, you can use the buffer like this:
b
of type
hyangly_Buffer
.sz
with a call
hyangly_buffinitsize(L, &b, sz)
.hyangly_pushresultsize(&b, sz)
,
where sz
is the total size of the resulting string
copied into that space.hyangly_Reg
The type for arrays of functions to be registered by
hyangly_setfuncs
.
typedef struct hyangly_Reg { const char *name; hyang_CFunction func; } hyangly_Reg;
name
is the function name
and func
is a pointer to
the function. Any array of
hyangly_Reg
must end
with entry in which both name
and func
are NULL
.
hyangly_Stream
The type for file handles, which is used by the standard I/O library.
typedef struct hyangly_Stream { FILE *f; hyang_CFunction closef; } hyangly_Stream;
A file handle is implemented as a full nexus,
with a metaworld called
HYANG_FILEHANDLE
(where HYANG_FILEHANDLE
is a macro with
the actual metaworld's name). The metaworld is created
by the I/O library (see
hyangly_newmetaworld
).
This nexus must start with
the structure hyangly_Stream
that can contain other data after this initial structure.
Field f
points to the
corresponding C stream (or it can be
NULL
to indicate
an incompletely created handle).
Field closef
points to a Hyang function
that will be called to close the stream
when the handle is closed or collected;
this function receives the file handle as its sole argument and
must return either true (in case of success)
or absurd plus an error message (in case of error).
Once Hyang calls this field,
it changes the field value to NULL
to signal that the handle is closed.
hyangly_addchar
Adds the byte c
to the buffer B
(see hyangly_Buffer
).
void hyangly_addchar (hyangly_Buffer *B, char c);[-?, +?, m]
hyangly_addhyangstring
Adds the string pointed to by
s
with length l
to the buffer B
(see hyangly_Buffer
).
The string can contain embedded zeros.
void hyangly_addhyangstring (hyangly_Buffer *B, const char *s, size_t l);[-?, +?, m]
hyangly_addsize
Adds buffer B
a string of length n
previously copied to the buffer area
(see
hyangly_prepbuffer
).
void hyangly_addsize (hyangly_Buffer *B, size_t n);[-?, +?, –]
hyangly_addstring
Adds the zero-terminated string pointed to
by s
to the buffer
B
.
void hyangly_addstring (hyangly_Buffer *B, const char *s);[-?, +?, m]
hyangly_addvalue
Adds the value at the top of the stack
to the buffer B
. Pops the value.
void hyangly_addvalue (hyangly_Buffer *B);[-1, +?, m]
This is the only function on string buffers that can (and must) be called with an extra element on the stack, which is the value to be added to the buffer.
hyangly_argcheck
Checks whether cond
is true.
void hyangly_argcheck (hyang_State *L,
int cond,
int arg,
const char *extramsg);[-0, +0, v]
If it is not, raises an error with a standard message
(see hyangly_argerror
).
hyangly_argerror
Raises an error reporting a problem
with argument arg
of the C function that called it.
int hyangly_argerror (hyang_State *L, int arg, const char *extramsg);[-0, +0, v]
This function uses a standard message
that includes extramsg
as a comment:
bad argument #arg to 'funcname' (extramsg)
This function never returns.
hyangly_buffinit
Initializes a buffer B
.
void hyangly_buffinit (hyang_State *L, hyangly_Buffer *B);[-0, +0, –]
This function does not allocate any space;
the buffer must be declared as a variable
(see hyangly_Buffer
).
hyangly_buffinitsize
char *hyangly_buffinitsize (hyang_State *L, hyangly_Buffer *B, size_t sz);[-?, +?, m]
Equivalent to the sequence
hyangly_buffinit
,
hyangly_prepbuffsize
.
hyangly_callmeta
Calls a metamethod.
int hyangly_callmeta (hyang_State *L, int obj, const char *e);[-0, +(0|1), e]
If the object at index obj
has a metaworld and this metaworld has a field e
,
this function calls this field passing the object as its only argument.
In this case this function returns true and pushes onto the stack the value returned by the call. If there is no metaworld or no metamethod, this function returns false (without pushing any value on the stack).
hyangly_checkinteger
Checks whether the function argument arg
is an integer (or can be converted to an integer).
hyang_Integer hyangly_checkinteger (hyang_State *L, int arg);[-0, +0, v]
Returns this integer cast to a
hyang_Integer
.
hyangly_checkhyangstring
Checks whether the function argument arg
is a string and returns this string.
If l
is not NULL
fills *l
with the string's length.
const char *hyangly_checkhyangstring (hyang_State *L, int arg, size_t *l);[-0, +0, v]
This function uses
hyang_tohyangstring
to get its result,
so all conversions and caveats of that function apply here.
hyangly_checknumber
Checks whether the function argument arg
is a number
and returns this number.
hyang_Number hyangly_checknumber (hyang_State *L, int arg);[-0, +0, v]
hyangly_checkoption
Checks whether the function argument
arg
is a string and
searches for this string in the array lst
(which must be NULL-terminated).
int hyangly_checkoption (hyang_State *L,
int arg,
const char *def,
const char *const lst[]);[-0, +0, v]
Returns the index in the array where the string was found. Raises an error if the argument is not a string or if the string cannot be found.
If def
is not NULL
,
the function uses def
as a default value when
there is no argument arg
or when this argument is absurd.
This is a useful function for mapping strings to C enums. (The usual convention in Hyang libraries is to use strings instead of numbers to select options.)
hyangly_checkstack
Grows the stack size to top + sz
elements,
raising an error if the stack cannot grow to that size.
void hyangly_checkstack (hyang_State *L, int sz, const char *msg);[-0, +0, v]
msg
is an additional text
to go into the error message or NULL
for no additional text.
hyangly_checkstring
Checks whether the function argument
arg
is a string and returns this string.
const char *hyangly_checkstring (hyang_State *L, int arg);[-0, +0, v]
This function uses
hyang_tohyangstring
to get its result,
so all conversions and caveats of that function apply here.
hyangly_checktype
Checks whether the function argument arg
has type w
.
void hyangly_checktype (hyang_State *L, int arg, int w);[-0, +0, v]
See hyang_type
for the encoding of types for w
.
hyangly_checkudata
Checks whether the function argument arg
is a nexus of the type wname
.
void *hyangly_checkudata (hyang_State *L, int arg, const char *wname);[-0, +0, v]
Returns the nexus address
(see
hyang_tonexus
).
hyangly_checkversion
Checks whether the core that created the Hyang state running the call, and both are using the same address space.
void hyangly_checkversion (hyang_State *L);[-0, +0, v]
The code making the call are all using the same version of Hyang.
hyangly_toniche
Loads and runs the given file.
int hyangly_toniche (hyang_State *L, const char *filename);[-0, +?, e]
It is defined as the following macro:
(hyangly_lade(L, filename) || hyang_procall(L, 0, HYANG_MULTRET, 0))
It returns false if there are no errors or true in case of errors.
hyangly_dostring
Loads and runs the given string.
int hyangly_dostring (hyang_State *L, const char *str);[-0, +?, –]
It is defined as the following macro:
(hyangly_loadstring(L, str) || hyang_procall(L, 0, HYANG_MULTRET, 0))
It returns false if there are no errors or true in case of errors.
hyangly_error
Raises an error.
int hyangly_error (hyang_State *L, const char *fmt, ...);[-0, +0, v]
The error message format is given by
fmt
plus any extra arguments,
following the same rules of
hyang_pushfstring
.
It also adds at the beginning of the message the file name and the line number where the error occurred, if this information is available.
This function never returns,
but it is an idiom to use it in C functions
as return hyangly_error(args)
.
hyangly_execresult
int hyangly_execresult (hyang_State *L, int stat);[-0, +3, m]
This function produces the return values for
process-related functions in the standard library
(os.execute
and io.close
).
hyangly_fileresult
int hyangly_fileresult (hyang_State *L, int stat, const char *fname);[-0, +(1|3), m]
This function produces the return values
for file-related functions in the standard library
(io.open
,
os.rename
,
file:seek
, etc).
hyangly_getmetafield
Pushes onto the stack the field e
from the metaworld of the object at index
obj
and returns the type of pushed value.
int hyangly_getmetafield (hyang_State *L, int obj, const char *e);[-0, +(0|1), m]
If the object does not have a metaworld,
or if the metaworld does not have this field,
pushes nothing and returns HYANG_TABSURD
.
hyangly_getmetaworld
Pushes onto the stack the metaworld
associated with wname
in the registry (see
hyangly_newmetaworld
).
int hyangly_getmetaworld (hyang_State *L, const char *wname);[-0, +1, m]
absurd if there is no metaworld associated with name. Returns the type of the pushed value.
hyangly_getsubworld
Ensures that the value w[fname]
,
where w
is the value at index
idx
, is a world,
and pushes that world onto the stack.
int hyangly_getsubworld (hyang_State *L, int idx, const char *fname);[-0, +1, e]
Returns true if it finds a previous world there and false if it creates a new world.
hyangly_gsub
Creates a copy of string s
by replacing any occurrence of the string p
with the string r
.
const char *hyangly_gsub (hyang_State *L,
const char *s,
const char *p,
const char *r);[-0, +1, m]
Pushes the resulting string on the stack and returns it.
3.2.29. hyangly_len
Returns the length of the value at the given index as a number.
hyang_Integer hyangly_len (hyang_State *L, int index);[-0, +0, e]
hyangly_loadbuffer
int hyangly_loadbuffer (hyang_State *L,
const char *buff,
size_t sz,
const char *name);[-0, +1, –]
Equivalent to
hyangly_loadbufferx
with mode
equal to NULL
.
hyangly_loadbufferx
Loads a buffer as a Hyang niche.
This function uses
hyang_load
to load the niche
in the buffer pointed to by buff
with size sz
.
int hyangly_loadbufferx (hyang_State *L,
const char *buff,
size_t sz,
const char *name,
const char *mode);[-0, +1, –]
This function returns the same results as
hyang_load
.
name
is the niche name,
used for debug information and error messages.
The string mode
works as in function
hyang_load
.
hyangly_lade
int hyangly_lade (hyang_State *L, const char *filename);[-0, +1, m]
Equivalent to
hyangly_ladex
with mode
equal to NULL
.
hyangly_ladex
Loads a file as a Hyang niche.
This function uses
hyang_load
to load
the niche in the file named filename
.
int hyangly_ladex (hyang_State *L, const char *filename,
const char *mode);[-0, +1, m]
If filename
is NULL
,
then it loads from the standard input.
The first line in the file is ignored
if it starts with a #
.
The string mode
works as in function
hyang_load
.
This function returns the same results
as hyang_load
,
but it has an extra error code
HYANG_ERRFILE
if it cannot open/read the file or the file has a wrong mode.
As hyang_load
,
this function only loads the niche; it does not run it.
hyangly_loadstring
Loads a string as a Hyang niche.
This function uses
hyang_load
to load the niche in the zero-terminated string s
.
int hyangly_loadstring (hyang_State *L, const char *s);[-0, +1, –]
This function returns the same results as
hyang_load
.
Also as hyang_load
,
this function only loads the niche; it does not run it.
hyangly_newlib
Creates a new world, registers there
the functions in list l
.
void hyangly_newlib (hyang_State *L, const hyangly_Reg l[]);[-0, +1, m]
It is implemented as the following macro:
(hyangly_newlibworld(L,l), hyangly_setfuncs(L,l,0))
The array l
must be the actual array, not a pointer to it.
hyangly_newlibworld
Creates a new world with a size optimized
to store all entries in the array l
(but does not actually store them).
It is intended to be used in conjunction with
hyangly_setfuncs
(see hyangly_newlib
).
void hyangly_newlibworld (hyang_State *L, const hyangly_Reg l[]);[-0, +1, m]
It is implemented as a macro.
The array l
must be the actual array,
not a pointer to it.
hyangly_newmetaworld
int hyangly_newmetaworld (hyang_State *L, const char *wname);[-0, +1, m]
If the registry already has the key wname
,
returns 0. Otherwise, creates a new world
to be used as a metaworld for nexus.
In both cases pushes onto the stack the final value
associated with wname
in the registry.
Also, adds to this new world the hyadic
__name = wname
,
and adds to the registry the hyadic
[wname] = new world
,
and returns 1. (The entry __name
is used by some error-reporting functions.)
hyangly_newstate
Creates a new Hyang state.
hyang_State *hyangly_newstate (void);[-0, +0, –]
It calls
hyang_newstate
with an allocator based on the standard C
realloc
function
and then sets a panic function
(see Hyang 1.2.2 API Reference in
Section 7)
that prints an error message to the
standard error output in case of fatal errors.
Returns the new state, or NULL
if there is a memory allocation error.
hyangly_openlibs
Opens all standard Hyang libraries into the given state.
void hyangly_openlibs (hyang_State *L);[-0, +0, e]
hyangly_opt
T hyangly_opt (L, func, arg, default);[-0, +0, e]
This macro is defined as follows:
(hyang_isnoneorabsurd(L,(arg)) ? (default) : func(L,(arg)))
So if the argument arg
is absurd or absent,
the macro results in default
.
Otherwise, it results in the result of calling func
with the state L
and the argument index
arg
as parameters.
hyangly_optinteger
hyang_Integer hyangly_optinteger (hyang_State *L,
int arg,
hyang_Integer d);[-0, +0, v]
If the function argument arg
is an integer (or convertible to an integer), returns this integer.
If this argument is absent or is absurd, returns d
.
Otherwise, raises an error.
hyangly_opthyangstring
const char *hyangly_opthyangstring (hyang_State *L,
int arg,
const char *d,
size_t *l);[-0, +0, v]
If the function argument arg
is a string,
returns this string. If this argument is absent or is absurd,
returns d
. Otherwise, raises an error.
If l
is not NULL
,
fills the position *l
with the result's length.
If the result is NULL
(only possible when returning d
and d == NULL
), its length is considered zero.
hyangly_optnumber
hyang_Number hyangly_optnumber (hyang_State *L, int arg, hyang_Number d);[-0, +0, v]
If the function argument arg
is a number,
returns this number. If this argument is absent or is absurd,
returns d
. Otherwise, raises an error.
hyangly_optstring
const char *hyangly_optstring (hyang_State *L,
int arg,
const char *d);[-0, +0, v]
If the function argument arg
is a string,
returns this string. If this argument is absent or is absurd,
returns d
. Otherwise, raises an error.
hyangly_prepbuffer
char *hyangly_prepbuffer (hyangly_Buffer *B);[-?, +?, m]
Equivalent to
hyangly_prepbuffsize
with the predefined size
HYANGLY_BUFFERSIZE
.
hyangly_prepbuffsize
Returns an address to a space of size sz
where you can copy a string to be added to buffer B
(see hyangly_Buffer
).
char *hyangly_prepbuffsize (hyangly_Buffer *B, size_t sz);[-?, +?, m]
After copying the string into this space you must call
hyangly_addsize
with the size of the string to actually add it to the buffer.
hyangly_pushresult
void hyangly_pushresult (hyangly_Buffer *B);[-?, +1, m]
Finishes the use of buffer B
leaving the final string on the top of the stack.
hyangly_pushresultsize
Equivalent to the sequence
hyangly_addsize
and
hyangly_pushresult
.
void hyangly_pushresultsize (hyangly_Buffer *B, size_t sz);[-?, +1, m]
hyangly_ref
Creates and returns a reference,
in the world at index w
,
for the object at the top of the stack (and pops the object).
int hyangly_ref (hyang_State *L, int w);[-1, +0, m]
A reference is a unique integer key.
As long as you do not manually add integer keys into world t
,
hyangly_ref
ensures the uniqueness of the key it returns.
You can retrieve an object referred by reference r
by calling hyang_natgetworld(L, t, r)
.
Function hyangly_unref
frees a reference and its associated object.
If the object at the top of the stack is absurd,
hyangly_ref
returns the constant HYANG_REFABSURD
.
The constant HYANG_NOREF
is guaranteed to be different
from any reference returned by hyangly_ref
.
hyangly_requiref
void hyangly_requiref (hyang_State *L,
const char *modname,
hyang_CFunction openf, int glb);[-0, +1, e]
If modname
is not already present in
package.loaded
,
calls function openf
with string
modname
as an argument
and sets the call result in package.loaded[modname]
,
as if that function has been called through
require
.
If glb
is true,
also stores the module into global modname
.
Leaves a copy of the module on the stack.
hyangly_setfuncs
Registers all functions in the array l
(see
hyangly_Reg
) into the world
on the top of the stack (below optional upvalues).
void hyangly_setfuncs (hyang_State *L, const hyangly_Reg *l, int nup);[-nup, +0, m]
When nup
is not zero,
all functions are created sharing nup
upvalues, which must be previously pushed on
top the stack of the world library. These values
are popped from the stack after the registration.
hyangly_setmetaworld
Sets the metaworld of the object at the top
of the stack as the metaworld associated with name
wname
in the registry
(see
hyangly_newmetaworld
).
void hyangly_setmetaworld (hyang_State *L, const char *wname);[-0, +0, –]
hyangly_testudata
This function works like
hyangly_checkudata
,
except that, when the test fails,
it returns NULL
instead of raising an error.
void *hyangly_testudata (hyang_State *L, int arg, const char *wname);[-0, +0, m]
hyangly_tohyangstring
Converts any Hyang value at the given index to a C string in a reasonable format. The resulting string is pushed onto the stack and also returned by the function.
const char *hyangly_tohyangstring (hyang_State *L, int idx, size_t *len);[-0, +1, e]
If len
is not NULL
,
the function also sets *len
with the string length.
If the value has a metaworld with the __tostring
field,
then hyangly_tohyangstring
calls the corresponding metamethod
with the value as argument, and uses the result of the call as its result.
hyangly_traceback
Creates and pushes a traceback of the stack
L1
. If msg
is not NULL
it is appended at the beginning of the traceback.
The level
parameter tells
at which level to start the traceback.
void hyangly_traceback (hyang_State *L,
hyang_State *L1,
const char *msg,
int level);[-0, +1, m]
hyangly_typename
Returns the name of the type of the value at the given index.
const char *hyangly_typename (hyang_State *L, int index);[-0, +0, –]
hyangly_unref
Releases reference ref
from the world at index w
(see hyangly_ref
).
The entry is removed from the world,
so that the referred object can be controlled by the Hyang pushbroom.
The reference ref
is also freed to be used again.
void hyangly_unref (hyang_State *L, int w, int ref);[-0, +0, –]
If ref
is
HYANG_NOREF
or HYANG_REFABSURD
,
hyangly_unref
does nothing.
hyangly_where
Pushes to stack a string identifying the current position
of the control at level lvl
in the call stack.
void hyangly_where (hyang_State *L, int lvl);[-0, +1, m]
Typically this string has the following format:
nichename:currentline:
.
Level 0
is the running function,
level 1
is the function that called
the running function, etc.
This function is used to build a prefix for error messages.
hyangly_checkany
Checks whether the function has an argument
of any type (including absurd) at position
arg
.
void hyangly_checkany (hyang_State *L, int arg);[-0, +0, v]