Squirrel 3.1 标准库

1、介绍

squirrel标准库包含一组用C ++实现的模块。 虽然对于该语言不是必不可少的，但它们提供了一系列有用的服务，这些服务通常被广泛的应用程序（文件I / O，正则表达式等）使用，而且它们为开发其他库提供了基础。

 

所有库都是通过squirrel API和ANSI C运行时库实现的。 模块按以下方式组织：

 

I / O：输入和输出

blob：二进制缓冲区操作

math：基本的数学例程

system：系统访问功能

string：字符串格式和操作

aux：辅助功能

可以独立注册库，但依赖于bloblib的IO库除外。

 

2、输入/输出 库

2.1. Squirrel API

2.1.1. 全局符号

dofile 

dofile(path[, raiseerror])

 

编译一个松鼠脚本或加载一个预编译的脚本并执行它。 返回脚本返回的值，如果没有返回值，则返回null。 如果可选参数’raiseerror’为true，则在语法错误的情况下调用编译器错误处理程序。 如果省略raiseerror或将其设置为false，则不会调用编译器错误处理程序。 当squirrel以unicode模式编译时，该函数可以处理不同的字符编码，带有和不带前缀的UTF8和带前缀的UCS-2（都是big endian和little endian）。 如果源流没有前缀，则UTF8 ecoding用作默认值。

 

 

loadfile

loadfile(path[, raiseerror])

编译一个松鼠脚本或加载预编译的脚本并将其作为函数返回。 如果可选参数’raiseerror’为true，则在语法错误的情况下调用编译器错误处理程序。 如果省略raiseerror或将其设置为false，则不会调用编译器错误处理程序。 当squirrel以unicode模式编译时，该函数可以处理不同的字符编码，带有和不带前缀的UTF8和带前缀的UCS-2（都是big endian和little endian）。 如果源流没有前缀，则UTF8 ecoding用作默认值。

 

writeclosuretofile

writeclosuretofile(destpath, closure)

将闭包序列化为字节码文件（destpath）。 可以使用loadfile（）和dofile（）加载序列化文件。

 

stderr

绑定在os标准错误流上的文件对象

stdin

绑定在os标准输入流上的文件对象

stdout

绑定在os标准输出流上的文件对象

 

2.1.2. The file class(file类)

文件对象在操作系统文件上实现流。

file

classfile(path, patten)

它的构造函数模仿C运行时函数fopen的行为，例如。

local myfile = file(“test.xxx”,”wb+”);

在当前目录中创建具有读/写访问权限的文件。

 

file.close()

关闭文件

 

file.eos()

如果读/写指针位于流的末尾，则返回非null值。

 

file.flush()

刷新，如果成功stream.return 的值 !=null，否则 = null。

 

file.len()

返回流的长度

 

file.readblob(size)

Arguments:

size (int) – 读取字节数

从流中读取n个字节并将其作为blob返回

 

file.readn(type)

Arguments:

type (int) – 要读取的数字的类型

根据类型参数从流中读取一个数字。

type可以具有以下值：

参数	返回描述	返回类型
‘l’	取决于处理器，32位处理器为32位，64位处理器为64位	integer
‘i’	32位数	integer
‘s’	16位有符号整数	integer
‘w’	16位无符号整数	integer
‘c’	8位有符号整数	integer
‘b’	8位无符号整数	integer
‘f’	32位浮点数	float
‘d’	64 位浮点数	float

 

file.resize(size)

Arguments:

size (int) – blob的新大小（以字节为单位）

将blob的大小调整为指定的大小

 

file.seek(offset[, origin])

Arguments:

offset (int) – 表示来自原点的偏移字节数。 origin (int) – ‘b’ 流的开头 ‘c’ 当前位置 ‘e’ 流的结尾

将读/写指针移动到指定位置。

 

注意：如果省略origin，则参数默认为’b’（流的开头）。

 

file.tell()

返回读/写指针的绝对位置

 

file.writeblob(src)

Arguments:

src (blob) –包含要写入的数据的源blob

在流中写一个blob

 

file.writen(n, type)

Arguments:

n (number) – 要写的值 type (int) – 要写的数字的类型

在根据类型参数格式化的流中写入数字

type可以具有以下值：

参数	返回描述
‘i’	32位数
‘s’	16位有符号整数
‘w’	16位无符号整数
‘c’	8位有符号整数
‘b’	8位无符号整数
‘f’	32位浮点数
‘d’	64位浮点数

 

2.2. C API

SQRESULT sqstd_register_iolib(HSQUIRRELVM v)

Parameters:	v (HSQUIRRELVM) –  目标 VM
Returns:	SQRESULT
Remarks:	函数详情是栈顶部一个表，用于注册全局库函数。

在给定的VM中初始化并注册io库。

2.2.1. File 对象

SQRESULT sqstd_createfile(HSQUIRRELVM v, SQFILE file, SQBool owns)

Parameters:	v (HSQUIRRELVM) – 目标VM file (SQFILE) – 将由文件对象表示的流 owns (SQBool) – 如果不为true，则在销毁新创建的文件对象时，将自动关闭流。
Returns:	SQRESULT

创建一个文件对象，绑定到通过参数传递的SQFILE，并将其压入到栈中

 

SQRESULT sqstd_getfile(HSQUIRRELVM v, SQInteger idx, SQFILE* file)

Parameters:	v (HSQUIRRELVM) – 目标VM idx (SQInteger) –  栈索引 file (SQFILE*) – 指向将存储结果的SQFILE的指针
Returns:	SQRESULT

从栈中的任意位置获取流句柄的指针。

2.2.2. 脚本加载和序列化

SQRESULT sqstd_loadfile(HSQUIRRELVM v, const SQChar* filename, SQBool printerror)

Parameters:	v (HSQUIRRELVM) –  目标VM filename (SQChar*) –  要加载的脚本的路径 printerror (SQBool) – 如果为true，则在发生错误时将调用编译器错误处理程序
Returns:	SQRESULT

编译一个松鼠脚本或加载预编译的脚本，将其作为闭包压入栈中。 当squirrel以unicode模式编译时，该函数可以处理不同的字符编码，带有和不带前缀的UTF8和带前缀的UCS-2（都是big endian和little endian）。 如果源流没有前缀，则UTF8 ecoding用作默认值。

SQRESULT sqstd_dofile(HSQUIRRELVM v, const SQChar* filename, SQBool retval, SQBool printerror)

Parameters:	v (HSQUIRRELVM) – 目标 VM filename (SQChar*) – 要加载的脚本的路径 retval (SQBool) – 如果为true，则该函数将在栈中压入已执行脚本的返回值。 printerror (SQBool) – 如果为true，则在发生错误时将调用编译器错误处理程序
Returns:	SQRESULT
Remarks:	函数详情是栈顶部的一个表，它将用作执行脚本的“this”。 ‘this’参数在栈中保持不变。

编译松鼠脚本或加载预编译的脚本并执行它。 （可选）在栈中压入已执行脚本的返回值。 当squirrel以unicode模式编译时，该函数可以处理不同的编码生态，带有和不带前缀的UTF8和带前缀的UCS-2（都是big endian和little endian）。 如果源流没有前缀，则UTF8 ecoding用作默认值。

SQRESULT sqstd_writeclosuretofile(HSQUIRRELVM v, const SQChar* filename)

Parameters:	v (HSQUIRRELVM) – 目标VM filename (SQChar*) – 序列化闭包的目标路径
Returns:	SQRESULT

序列化栈顶部位置的闭包，作为由paremeter文件名指定的文件中的字节码。 如果已存在具有相同名称的文件，则将覆盖该文件。

 

3. Blob 库

blob库实现二进制数据操作。该库基于blob对象，它们呈现任意二进制数据的缓冲区。

3.1. Squirrel API

3.1.1. Global symbols

castf2i(f)

将float转换为int

casti2f(n)

将int转换为float

swap2(n)

交换一个数字的字节顺序（就像它是一个16位整数）

swap4(n)

交换整数的字节顺序

swapfloat(n)

交换float的字节顺序

 

3.1.2. blob 类

blob对象是任意二进制数据的缓冲区。 该对象的行为类似于文件流，它具有读/写指针，如果数据从其边界写出，它会自动增长。 也可以通过[]运算符逐字节访问blob。

class blob(size)

Arguments:

size (int) – blob的初始大小

返回指定大小的blob类的新实例，以字节为单位

blob.eos()

如果读/写指针位于流的末尾，则返回非null值。

blob.flush()

刷新，如果成功stream.return值!=null，否则返回null

blob.len()

返回流的长度

blob.readblob(size)

Arguments:

size (int) – 要读取的字节数

从流中读取n个字节并将其作为blob返回

blob.readn(type)

Arguments:

type (int) – 要读取的数字的类型

根据类型参数从流中读取一个数字。

type可以具有以下值：

参数	返回描述	返回类型
‘l’	取决于处理器，32位处理器为32位，64位处理器为64位	integer
‘i’	32位数	integer
‘s’	16位有符号整数	integer
‘w’	16位无符号整数	integer
‘c’	8位有符号整数	integer
‘b’	8位无符号整数	integer
‘f’	32位浮点数	float
‘d’	64 位浮点数	float

 

blob.resize(size)

Arguments:

size (int) – blob的新大小（以字节为单位）

将blob的大小调整为指定的大小

blob.seek(offset[, origin])

Arguments:

offset (int) – 表示来自原点的偏移字节数。 origin (int) – ‘b’ 流的开始 ‘c’ 当前位置 ‘e’ 流的结尾

将读/写指针移动到指定位置

注意：

如果省略origin，则参数默认为’b’（流的开头）。

blob.swap2()

交换blob内容的字节顺序，它将是16位整数的数组

blob.swap4()

交换blob内容的字节顺序，它将是32位整数的数组

blob.tell()

返回读/写指针的绝对位置

blob.writeblob(src)

Arguments:

src (blob) – 包含要写入的数据的源blob

在流中写一个blob

blob.writen(n, type)

Arguments:

n (number) – 要写的值 type (int) – 要写的数字的类型

在根据类型参数格式化的流中写入数字

type可以具有以下值：

参数	返回描述
‘i‘	32位数
‘s‘	16位有符号整数
‘w‘	16位无符号整数
‘c‘	8位有符号整数
‘b‘	8位无符号整数
‘f‘	32位浮点数
‘d‘	64位浮点数

 

 

3.2. C API

SQRESULT sqstd_register_bloblib(HSQUIRRELVM v)

Parameters:	v (HSQUIRRELVM) – 目标 VM
Returns:	an SQRESULT
Remarks:	函数详情是栈顶部的一个表，用于注册全局库函数。

在给定的VM中初始化并注册blob库。

SQRESULT sqstd_getblob(HSQUIRRELVM v, SQInteger idx, SQUserPointer* ptr)

Parameters:	v (HSQUIRRELVM) – 目标VM idx (SQInteger) – 栈索引 ptr (SQUserPointer*) –指向 blob的有效负载的userpointer的指针
Returns:	SQRESULT

从栈中的任意位置检索blob的有效负载的指针。

SQInteger sqstd_getblobsize(HSQUIRRELVM v, SQInteger idx)

Parameters:	v (HSQUIRRELVM) – 目标 VM idx (SQInteger) – 栈索引
Returns:	idx位置的blob大小

从栈中的任意位置获取blob的有效负载的大小。

SQUserPointer sqstd_createblob(HSQUIRRELVM v, SQInteger size)

Parameters:	v (HSQUIRRELVM) –目标VM size (SQInteger) –要创建的blob有效内容的大小
Returns:	指向新创建的blob有效内容的指针

创建具有给定有效负载大小的blob并将其压入栈中。

 

4. 数学库

math lib提供基本的数学函数。该库模仿C运行时库实现。

4.1. Squirrel API

4.1.1. 全局符号

abs(x)

以整数形式返回x的绝对值

acos(x)

返回x的反余弦值

asin(x)

返回x的反正弦值

atan(x)

返回x的反正切值

atan2(x, y)

返回x / y的反正切值

ceil(x)

返回一个浮点值，表示大于或等于x的最小整数

cos(x)

返回x的余弦值

exp(x)

返回float参数x的指数值

fabs(x)

返回x作为float的绝对值

floor(x)

返回一个浮点值，表示小于或等于x的最大整数

log(x)

返回x的自然对数

log10(x)

回x的对数基数-10

pow(x, y)

将x提升到y的幂

rand()

返回0到RAND_MAX范围内的伪随机整数

sin(x)

返回x的正弦值

sqrt(x)

返回x的平方根

srand(seed)

设置生成一系列伪随机整数的起点

tan(x)

返回x的正切值

RAND_MAX

rand（）函数可以返回的最大值

PI

数值常数pi（3.141592）是圆周长与直径之比

 

 

4.2. C API

SQRESULT sqstd_register_mathlib(HSQUIRRELVM v)

Parameters:	v (HSQUIRRELVM) – 目标 VM
Returns:	SQRESULT
Remarks:	函数详情是栈顶部的一个表，用于注册全局库函数。

在给定的VM中初始化并注册数学库。

 

 

5. 系统库

系统库公开了操作系统功能，如环境变量，日期时间操作等。

5.1. Squirrel API

5.1.1. 全局符号

clock()

返回一个浮点数，表示自进程启动以来经过的秒数

date([time[, format]])

返回一个表，其中包含在槽中拆分的日期/时间：

sec	秒(0 – 59).
min	分钟 (0 – 59).
hour	小时(0 – 23).
day	日 (1 – 31).
month	月 (0 – 11; 一月= 0).
year	年 (当前年).
wday	星期 (0 – 6; 星期日 = 0).
yday	一年的天数 (0 – 365; 1月1日  = 0).

如果省略time，则使用当前时间。

如果format是’l’本地时间 或 ‘u’UTC时间，如果省略则默认为’l’（本地时间）。

getenv(varaname)

返回包含环境变量varname值的字符串

remove(path)

删除path指定的文件

rename(oldname, newname)

将oldname指定的文件或目录重命名为newname指定的名称

system(cmd)

通过os命令解释器执行字符串cmd。

time()

返回自1970年1月1日午夜00:00:00起经过的秒数。

这个函数的结果可以通过函数date（）格式化

 

5.2. C API

SQRESULT sqstd_register_systemlib(HSQUIRRELVM v)

Parameters:	v (HSQUIRRELVM) – 目标 VM
Returns:	SQRESULT
Remarks:	函数详情是栈顶部的一个表，用于注册全局库函数。

在给定的VM中初始化并注册系统库。

 

 

6. 字符串库

字符串lib实现字符串格式化和正则表达式匹配例程。

6.1. Squirrel API

6.1.1. 全局符号

endswith(str, cmp)

如果字符串str的结尾与字符串cmp匹配则返回true，否则返回false

ecape(str)

在需要转义的字符(”,a,b,t,n,v,f,r,\,”,‘,0,xnn).之前添加反斜线返回

format(formatstr, …)

返回根据formatstr格式化的字符串以及其后的可选参数。 格式字符串遵循与标准C函数的printf系列相同的规则（不支持“*”）。

sq> print(format(“%s %d 0x%02X\n”,”this is a test :”,123,10));

this is a test : 123 0x0A

 

 

 

strip(str)

删首空，并返回删除后字符串。

rstrip(str)

删尾空，并返回删除后字符串。

split(str, separtators)

返回在str中出现分隔符的每个点处拆分的字符串数组。 分隔符不会作为任何数组元素的一部分返回。 参数分隔符是一个字符串，用于指定要用于拆分的字符。

local a = split(“1.2-3;4/5″,”.-/;”);

// 返回将是 [1,2,3,4,5]

startswith(str, cmp)

如果字符串str的开头与字符串cmp匹配则返回true，否则返回false

strip(str)

删首尾空，并返回删除后字符串。

 

6.1.2.正则表达式类

Class regexp(pattern)

regexp对象表示预编译的正则表达式模式。 该对象是通过regexp（patern）创建的。

\	引用下一个元字符
^	匹配字符串的开头
.	匹配任意字符
$	匹配字符串的结尾
|	或
(subexp)	子表达式（创建捕获）
(?:subexp)	不捕获的子表达式（不捕获）
[]	字符类

GREEDY CLOSURES

*	匹配0次或多次
+	匹配1次或多次
?	匹配1或0次
{n}	匹配n次
{n,}	至少匹配n次
{n,m}	匹配至少n次但不超过m次

ESCAPE CHARACTERS

\t	制表符(HT, TAB)
\n	换行符(LF, NL)
\r	回车符(CR)
\f	分页符(FF)

PREDEFINED CLASSES

\l	小写下一个字符
\u	大写的下一个字符
\a	字母
\A	非字母
\w	字母和数字[_0-9a-zA-Z]
\W	非字母和数字 [^_0-9a-zA-Z]
\s	空格
\S	非空格
\d	数字
\D	非数字
\x	十六进制数字
\X	非十六进制数字
\c	控制字符
\C	非控制字符
\p	标点符号
\P	非标点符号
\b	单词的边界
\B	非单词的边界

regexp.capture(str[, start])

返回一个table数组，其中包含字符串str中正则表达式的第一个匹配项的两个索引（“begin”和“end”）。 为每个捕获的子表达式创建一个数组条目。 如果不匹配，则返回null。 搜索从start索引开始的字符串，如果省略start，则从字符串的开头开始搜索。

返回数组的第一个元素（索引0）始终包含完整匹配。

local ex = regexp(@”(\d+) ([a-zA-Z]+)(\p)”);

local string = “stuff 123 Test;”;

local res = ex.capture(string);

foreach(i,val in res)

{

print(format(“match number[%02d] %s\n”,

i,string.slice(val.begin,val.end))); //prints “Test”

}

 

…

will print

match number[00] 123 Test;

match number[01] 123

match number[02] Test

match number[03] ;

regexp.match(str)

如果正则表达式匹配字符串str，则返回true，否则返回false。

regexp.search(str[, start])

返回一个table，其中包含字符串str中正则表达式的第一个匹配项的两个索引（“begin”和“end”），否则如果不匹配，则返回null。 搜索从start索引开始的字符串，如果省略start，则从字符串的开头开始搜索。

local ex = regexp(“[a-zA-Z]+”);

local string = “123 Test;”;

local res = ex.search(string);

print(string.slice(res.begin,res.end)); //prints “Test”

 

6.2. C API

SQRESULT sqstd_register_stringlib(HSQUIRRELVM v)

Parameters:	v (HSQUIRRELVM) – 目标 VM
Returns:	SQRESULT
Remarks:	函数详情是栈顶部的一个表，用于注册全局库函数。

在给定的VM中初始化并注册字符串库。

 

6.2.1. 格式化

SQRESULT sqstd_format(HSQUIRRELVM v, SQInteger nformatstringidx, SQInteger* outlen, SQChar** output)

Parameters:	v (HSQUIRRELVM) – 目标 VM nformatstringidx (SQInteger) –格式字符串栈中的索引outlen (SQInteger*) –一个指向整数的指针，该整数将填充新创建的字符串的长度 output (SQChar**) –指向将接收新创建的字符串指针的指针
Returns:	SQRESULT
Remarks:	新创建的字符串在暂存器中分配。

根据nformatstringidx位置的对象和后面的可选参数创建一个新的字符串。 格式字符串遵循与标准C函数的printf系列相同的规则（不支持“*”）。

 

6.2.2. 正则表达式

SQRex* sqstd_rex_compile(const SQChar *pattern, const SQChar ** error)

Parameters:	pattern (SQChar*) – 指向包含要编译的零终止字符串的指针。 error (SQChar**) –指向字符串指针的指针，如果发生错误，将使用错误字符串进行设置。
Returns:	指向已编译正则的指针

编译表达式并返回指向编译版本的指针。如果失败，则返回NULL。必须通过函数sqstd_rex_free（）删除返回的对象。

void sqstd_rex_free(SQRex * exp)

Parameters:

exp (SQRex*) – 要删除的表达式结构指针。

删除用sqstd_rex_compile（）创建的表达式结构指针

SQBool sqstd_rex_match(SQRex * exp, const SQChar * text)

Parameters:	exp (SQRex*) – 已编译的表达式 text (SQChar*) – 要测试的字符串
Returns:	SQTrue如果成功，否则SQFalse

如果参数文本中指定的字符串与表达式完全匹配，则返回SQTrue，否则返回SQFalse。

SQBool sqstd_rex_search(SQRex * exp, const SQChar * text, const SQChar ** out_begin, const SQChar ** out_end)

Parameters:	exp (SQRex*) –已编译的表达式 text (SQChar*) – 要测试的字符串 out_begin (SQChar**) –指向将在匹配开始时设置的字符串指针的指针 out_end (SQChar**) –指向将在匹配结束时设置的字符串指针的指针
Returns:	SQTrue如果成功，否则SQFalse

在参数text中指定的字符串中搜索表达式的第一个匹配项。 如果找到匹配，则返回SQTrue并将out_begin设置为匹配的开头，并将out_end设置为匹配的结尾; 否则返回SQFalse。

SQBool sqstd_rex_searchrange(SQRex * exp, const SQChar * text_begin, const SQChar * text_end, const SQChar ** out_begin, const SQChar ** out_end)

Parameters:	exp (SQRex*) –已编译的表达式 text_begin (SQChar*) – 指向要测试的字符串开头的指针text_end (SQChar*) – 指向要测试的字符串末尾的指针out_begin (SQChar**) –指向将在匹配开始时设置的字符串指针的指针 out_end (SQChar**) –指向将在匹配结束时设置的字符串指针的指针
Returns:	SQTrue如果成功，否则SQFalse

在由参数text_begin和text_end分隔的字符串中搜索表达式的第一个匹配项。 如果找到匹配，则返回SQTrue并将out_begin设置为匹配的开头，并将out_end设置为匹配的结尾; 否则返回SQFalse

SQInteger sqstd_rex_getsubexpcount(SQRex * exp)

Parameters:	exp (SQRex*) –已编译的表达式
Returns:	表达式匹配的子表达式的数量

返回表达式匹配的子表达式的数量

SQBool sqstd_rex_getsubexp(SQRex * exp, SQInteger n, SQRexMatch *subexp)

Parameters:	exp (SQRex*) – 已编译的表达式 n (SQInteger) –子匹配的索引（0是完全匹配） subexp (SQRexMatch*) –指向将存储结果的结构的指针
Returns:	如果n是有效索引，则函数返回SQTrue，否则返回SQFalse。

获取begin和指向由n索引的子表达式长度的指针。 结果通过struct SQRexMatch传递。

 

7. 辅助库

aux库为编译器和运行时错误以及栈转储实现默认处理程序。

7.1. C API

void sqstd_seterrorhandlers(HSQUIRRELVM v)

Parameters:

v (HSQUIRRELVM) – 目标 VM

初始化编译器和运行时错误处理程序，处理程序使用通过（sq_setprintfunc）设置的print函数来输出错误。

void sqstd_printcallstack(HSQUIRRELVM v)

Parameters:

v (HSQUIRRELVM) –目标VM

print调用栈和栈内容。 该函数使用通过（sq_setprintfunc）设置的print函数来输出

stack dump