From 09c4e7a8c1e0c952110e2032d9304b0e1b8183d6 Mon Sep 17 00:00:00 2001 From: zeromus Date: Thu, 12 May 2016 11:22:41 -0500 Subject: [PATCH 01/14] fix docs for 'unsigned right shift operator' to reference >>> instead of <<< ! also minor tidying in same file --- doc/source/reference/language/expressions.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/source/reference/language/expressions.rst b/doc/source/reference/language/expressions.rst index d84367a..7b9683d 100644 --- a/doc/source/reference/language/expressions.rst +++ b/doc/source/reference/language/expressions.rst @@ -221,10 +221,10 @@ Bitwise Operators exp:= 'exp' op 'exp' exp := '~' exp -Squirrel supports the standard c-like bit wise operators ``&, |, ^, ~, <<, >>`` plus the unsigned -right shift operator ``<<<``. The unsigned right shift works exactly like the normal right shift operator(``<<``) +Squirrel supports the standard C-like bitwise operators ``&, |, ^, ~, <<, >>`` plus the unsigned +right shift operator ``>>>``. The unsigned right shift works exactly like the normal right shift operator(``>>``) except for treating the left operand as an unsigned integer, so is not affected by the sign. Those operators -only work on integers values, passing of any other operand type to these operators will +only work on integer values; passing of any other operand type to these operators will cause an exception. ^^^^^^^^^^^^^^^^^^^^^ @@ -255,7 +255,7 @@ Operators precedence +---------------------------------------+-----------+ | ``+=, =, -=`` | ... | +---------------------------------------+-----------+ -| ``,(comma operator)`` | lowest | +| ``, (comma operator)`` | lowest | +---------------------------------------+-----------+ .. _table_contructor: @@ -293,7 +293,7 @@ A new slot with exp1 as key and exp2 as value is created:: [1]="I'm the value" } -both syntaxes can be mixed:: +Both syntaxes can be mixed:: local table= { @@ -369,6 +369,6 @@ Creates a new array.:: a <- [] //creates an empty array -arrays can be initialized with values during the construction:: +Arrays can be initialized with values during the construction:: a <- [1,"string!",[],{}] //creates an array with 4 elements \ No newline at end of file From 2e346b54acf51fbe183258c8dcbe850c6ccc292e Mon Sep 17 00:00:00 2001 From: Dwachs Date: Wed, 8 Jun 2016 21:08:38 +0200 Subject: [PATCH 02/14] FIX: no warnings on unused arguments on non-gnu compilers --- include/squirrel.h | 2 +- sq/sq.c | 1 - squirrel/sqclass.cpp | 2 +- squirrel/sqstate.cpp | 2 +- 4 files changed, 3 insertions(+), 4 deletions(-) diff --git a/include/squirrel.h b/include/squirrel.h index 830a587..d936274 100644 --- a/include/squirrel.h +++ b/include/squirrel.h @@ -396,7 +396,7 @@ SQUIRREL_API void sq_setnativedebughook(HSQUIRRELVM v,SQDEBUGHOOK hook); #ifdef __GNUC__ # define SQ_UNUSED_ARG(x) __attribute__((unused)) x #else -# define SQ_UNUSED_ARG(x) x +# define SQ_UNUSED_ARG(x) #endif #ifdef __cplusplus diff --git a/sq/sq.c b/sq/sq.c index 3673293..ee5eabb 100644 --- a/sq/sq.c +++ b/sq/sq.c @@ -52,7 +52,6 @@ void printfunc(HSQUIRRELVM SQ_UNUSED_ARG(v),const SQChar *s,...) va_start(vl, s); scvprintf(stdout, s, vl); va_end(vl); - (void)v; /* UNUSED */ } void errorfunc(HSQUIRRELVM SQ_UNUSED_ARG(v),const SQChar *s,...) diff --git a/squirrel/sqclass.cpp b/squirrel/sqclass.cpp index ec64b3d..81e66a2 100644 --- a/squirrel/sqclass.cpp +++ b/squirrel/sqclass.cpp @@ -189,7 +189,7 @@ SQInstance::~SQInstance() if(_class){ Finalize(); } //if _class is null it was already finalized by the GC } -bool SQInstance::GetMetaMethod(SQVM SQ_UNUSED_ARG(*v),SQMetaMethod mm,SQObjectPtr &res) +bool SQInstance::GetMetaMethod(SQVM* SQ_UNUSED_ARG(v),SQMetaMethod mm,SQObjectPtr &res) { if(type(_class->_metamethods[mm]) != OT_NULL) { res = _class->_metamethods[mm]; diff --git a/squirrel/sqstate.cpp b/squirrel/sqstate.cpp index 2711306..8ad74b0 100644 --- a/squirrel/sqstate.cpp +++ b/squirrel/sqstate.cpp @@ -241,7 +241,7 @@ void SQSharedState::MarkObject(SQObjectPtr &o,SQCollectable **chain) } } -void SQSharedState::RunMark(SQVM SQ_UNUSED_ARG(*vm),SQCollectable **tchain) +void SQSharedState::RunMark(SQVM* SQ_UNUSED_ARG(vm),SQCollectable **tchain) { SQVM *vms = _thread(_root_vm); From 997c7aefd24e674848ebad7a9f99503e385a5552 Mon Sep 17 00:00:00 2001 From: zeromus Date: Sat, 11 Jun 2016 16:48:22 -0500 Subject: [PATCH 03/14] Update sqapi.cpp change comment "pop closure and args" to "pop args" in sq_call(). the code clearly pops only args. the docs say: "the function pops all the parameters and leave the closure in the stack" --- squirrel/sqapi.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/squirrel/sqapi.cpp b/squirrel/sqapi.cpp index c5a70d6..4dc2a82 100644 --- a/squirrel/sqapi.cpp +++ b/squirrel/sqapi.cpp @@ -1164,7 +1164,7 @@ SQRESULT sq_call(HSQUIRRELVM v,SQInteger params,SQBool retval,SQBool raiseerror) if(v->Call(v->GetUp(-(params+1)),params,v->_top-params,res,raiseerror?true:false)){ if(!v->_suspended) { - v->Pop(params);//pop closure and args + v->Pop(params);//pop args } if(retval){ v->Push(res); return SQ_OK; From 3c4098da84e4cbdb6591fd8d48b0f16bc1ccba3b Mon Sep 17 00:00:00 2001 From: zeromus Date: Mon, 13 Jun 2016 17:20:11 -0500 Subject: [PATCH 04/14] small docs fixes. small typo fixes in sqapi.cpp error messages --- doc/source/reference/api/object_manipulation.rst | 6 +++--- doc/source/reference/language/classes.rst | 4 ++-- squirrel/sqapi.cpp | 6 +++--- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/source/reference/api/object_manipulation.rst b/doc/source/reference/api/object_manipulation.rst index 4d5288d..099fc59 100644 --- a/doc/source/reference/api/object_manipulation.rst +++ b/doc/source/reference/api/object_manipulation.rst @@ -91,7 +91,7 @@ resizes the array at the position idx in the stack. :returns: a SQRESULT :remarks: Only works on arrays. -reverse an array in place. +reverses an array in place. @@ -106,7 +106,7 @@ reverse an array in place. :returns: a SQRESULT :remarks: Only works on tables and arrays. -clears all the element of the table/array at position idx in the stack. +clears all the elements of the table/array at position idx in the stack. @@ -120,7 +120,7 @@ clears all the element of the table/array at position idx in the stack. :param SQInteger idx: index of the target object in the stack :returns: a SQRESULT -Clones the table, array or class instance at the position idx, clones it and pushes the new object in the stack. +pushes a clone of the table, array, or class instance at the position idx. diff --git a/doc/source/reference/language/classes.rst b/doc/source/reference/language/classes.rst index 7637f5b..81ee4c4 100644 --- a/doc/source/reference/language/classes.rst +++ b/doc/source/reference/language/classes.rst @@ -46,7 +46,7 @@ For instance: :: } -the previous code examples is a syntactic sugar for: :: +the previous code example is a syntactic sugar for: :: Foo <- class { //constructor @@ -67,7 +67,7 @@ the previous code examples is a syntactic sugar for: :: } -in order to emulate namespaces, is also possible to declare something like this:: +in order to emulate namespaces, it is also possible to declare something like this:: //just 2 regular nested tables FakeNamespace <- { diff --git a/squirrel/sqapi.cpp b/squirrel/sqapi.cpp index 4dc2a82..034e7be 100644 --- a/squirrel/sqapi.cpp +++ b/squirrel/sqapi.cpp @@ -510,7 +510,7 @@ SQRESULT sq_setclosureroot(HSQUIRRELVM v,SQInteger idx) v->Pop(); return SQ_OK; } - return sq_throwerror(v, _SC("ivalid type")); + return sq_throwerror(v, _SC("invalid type")); } SQRESULT sq_getclosureroot(HSQUIRRELVM v,SQInteger idx) @@ -558,7 +558,7 @@ SQRESULT sq_setroottable(HSQUIRRELVM v) v->Pop(); return SQ_OK; } - return sq_throwerror(v, _SC("ivalid type")); + return sq_throwerror(v, _SC("invalid type")); } SQRESULT sq_setconsttable(HSQUIRRELVM v) @@ -569,7 +569,7 @@ SQRESULT sq_setconsttable(HSQUIRRELVM v) v->Pop(); return SQ_OK; } - return sq_throwerror(v, _SC("ivalid type, expected table")); + return sq_throwerror(v, _SC("invalid type, expected table")); } void sq_setforeignptr(HSQUIRRELVM v,SQUserPointer p) From 3b217e7e428eedf5b019bfab21362e7a99b0fabf Mon Sep 17 00:00:00 2001 From: zeromus Date: Tue, 14 Jun 2016 13:09:53 -0500 Subject: [PATCH 05/14] fix getstackinfos docs --- doc/source/reference/language/builtin_functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/reference/language/builtin_functions.rst b/doc/source/reference/language/builtin_functions.rst index 2c344e5..57ec785 100644 --- a/doc/source/reference/language/builtin_functions.rst +++ b/doc/source/reference/language/builtin_functions.rst @@ -105,7 +105,7 @@ returns the stack informations of a given call stack level. returns a table form } } -level = 0 is the current function, level = 1 is the caller and so on. If the stack level doesn't exist the function returns null. +level = 0 is getstackinfos() itself! level = 1 is the current function, level = 2 is the caller of the current function, and so on. If the stack level doesn't exist the function returns null. .. js:function:: newthread(threadfunc) From 7290b1fffedf9ccc550456ae0fe9ee97649c535b Mon Sep 17 00:00:00 2001 From: zeromus Date: Sat, 18 Jun 2016 23:41:05 -0500 Subject: [PATCH 06/14] docs & error message tidy --- .../reference/api/object_manipulation.rst | 2 +- .../reference/language/builtin_functions.rst | 43 +++++++++---------- squirrel/sqcompiler.cpp | 4 +- 3 files changed, 24 insertions(+), 25 deletions(-) diff --git a/doc/source/reference/api/object_manipulation.rst b/doc/source/reference/api/object_manipulation.rst index 099fc59..ea00240 100644 --- a/doc/source/reference/api/object_manipulation.rst +++ b/doc/source/reference/api/object_manipulation.rst @@ -446,6 +446,6 @@ pops a value from the stack and sets it as a free variable of the closure at the :param HSQUIRRELVM v: the target VM :param SQInteger idx: index to the target object in the stack :returns: a SQRESULT - :remarks: if the object at idx position is an integer,float,bool or null the object itself is pushed instead of a weak ref. + :remarks: if the object at idx position is one of (integer, float, bool, null), the object itself is pushed instead of a weak ref. pushes a weak reference to the object at position idx in the stack. \ No newline at end of file diff --git a/doc/source/reference/language/builtin_functions.rst b/doc/source/reference/language/builtin_functions.rst index 57ec785..01f02c5 100644 --- a/doc/source/reference/language/builtin_functions.rst +++ b/doc/source/reference/language/builtin_functions.rst @@ -16,8 +16,7 @@ Global Symbols .. js:function:: array(size,[fill]) -create and returns array of a specified size.if the optional parameter fill is specified its -value will be used to fill the new array's slots. If the fill parameter is omitted null is used instead. +creates and returns array of a specified size. If the optional parameter fill is specified its value will be used to fill the new array's slots. If the fill parameter is omitted, null is used instead. .. js:function:: seterrorhandler(func) @@ -76,11 +75,11 @@ compiles a string containing a squirrel script into a function and returns it:: .. js:function:: collectgarbage() - runs the garbage collector and returns the number of reference cycles found(and deleted) This function only works on garbage collector builds. + Runs the garbage collector and returns the number of reference cycles found (and deleted). This function only works on garbage collector builds. .. js:function:: resurrectunreachable() -runs the garbage collector and returns an array containing all unreachable object found. If no unreachable object is found, null is returned instead. This function is meant to help debugging reference cycles. This function only works on garbage collector builds. +Runs the garbage collector and returns an array containing all unreachable object found. If no unreachable object is found, null is returned instead. This function is meant to help debugging reference cycles. This function only works on garbage collector builds. .. js:function:: type(obj) @@ -113,7 +112,7 @@ creates a new cooperative thread object(coroutine) and returns it .. js:data:: _versionnumber_ -integer values describing the version of VM and compiler. eg. for Squirrel 3.0.1 this value will be 301 +integer values describing the version of VM and compiler. e.g. for Squirrel 3.0.1 this value will be 301 .. js:data:: _version_ @@ -153,7 +152,7 @@ converts the number to string and returns it .. js:function:: integer.tointeger() -returns the value of the integer(dummy function) +dummy function; returns the value of the integer. .. js:function:: integer.tochar() @@ -163,7 +162,7 @@ returns a string containing a single character represented by the integer. .. js:function:: integer.weakref() -dummy function, returns the integer itself. +dummy function; returns the integer itself. ^^^^^ Float @@ -191,7 +190,7 @@ returns a string containing a single character represented by the integer part o .. js:function:: float.weakref() -dummy function, returns the float itself. +dummy function; returns the float itself. ^^^^ Bool @@ -209,12 +208,12 @@ returns 1 for true 0 for false .. js:function:: bool.tostring() -returns "true" for true "false" for false +returns "true" for true and "false" for false .. js:function:: bool.weakref() -dummy function, returns the bool itself. +dummy function; returns the bool itself. ^^^^^^ String @@ -227,7 +226,7 @@ returns the string length .. js:function:: string.tointeger([base]) -converts the string to integer and returns it.An optional parameter base can be specified, if a base is not specified it defaults to base 10 +Converts the string to integer and returns it. An optional parameter base can be specified--if a base is not specified, it defaults to base 10. .. js:function:: string.tofloat() @@ -237,7 +236,7 @@ converts the string to float and returns it .. js:function:: string.tostring() -returns the string(dummy function) +returns the string (really, a dummy function) .. js:function:: string.slice(start,[end]) @@ -247,7 +246,7 @@ returns a section of the string as new string. Copies from start to the end (not .. js:function:: string.find(substr,[startidx]) -search a sub string(substr) starting from the index startidx and returns the index of its first occurrence. If startidx is omitted the search operation starts from the beginning of the string. The function returns null if substr is not found. +Searches a sub string (substr) starting from the index startidx and returns the index of its first occurrence. If startidx is omitted the search operation starts from the beginning of the string. The function returns null if substr is not found. .. js:function:: string.tolower() @@ -280,12 +279,12 @@ tries to get a value from the slot 'key' without employing delegation .. js:function:: table.rawset(key,val) -sets the slot 'key' with the value 'val' without employing delegation. If the slot does not exists , it will be created. +Sets the slot 'key' with the value 'val' without employing delegation. If the slot does not exists, it will be created. .. js:function:: table.rawdelete() -deletes the slot key without employing delegation and returns his value. if the slo does not exists returns always null. +Deletes the slot key without employing delegation and returns its value. If the slot does not exists, returns null. .. js:function:: table.rawin(key) @@ -300,17 +299,17 @@ returns a weak reference to the object. .. js:function:: table.tostring() -tries to invoke the _tostring metamethod, if failed. returns "(table : pointer)". +Tries to invoke the _tostring metamethod. If that fails, it returns "(table : pointer)". .. js:function:: table.clear() -removes all the slot from the table +removes all the slots from the table .. js:function:: table.setdelegate(table) -sets the delegate of the table, to remove a delegate 'null' must be passed to the function. The function returns the table itself (eg. a.setdelegate(b) in this case 'a' is the return value). +Sets the delegate of the table. To remove a delegate, 'null' must be passed to the function. The function returns the table itself (e.g. a.setdelegate(b) -- in this case 'a' is the return value). .. js:function:: table.getdelegate() @@ -363,12 +362,12 @@ removes the value at the position 'idx' in the array .. js:function:: array.resize(size,[fill]) -resizes the array, if the optional parameter fill is specified its value will be used to fill the new array's slots (if the size specified is bigger than the previous size). If the fill parameter is omitted null is used instead. +Resizes the array. If the optional parameter 'fill' is specified, its value will be used to fill the new array's slots when the size specified is bigger than the previous size. If the fill parameter is omitted, null is used instead. .. js:function:: array.sort([compare_func]) -sorts the array. A custom compare function can be optionally passed. The function prototype as to be the following.:: +Sorts the array. A custom compare function can be optionally passed. The function prototype as to be the following.:: function custom_compare(a,b) { @@ -390,7 +389,7 @@ reverse the elements of the array in place .. js:function:: array.slice(start,[end]) -returns a section of the array as new array. Copies from start to the end (not included). If start is negative the index is calculated as length + start, if end is negative the index is calculated as length + end. If end is omitted end is equal to the array length. +Returns a section of the array as new array. Copies from start to the end (not included). If start is negative the index is calculated as length + start, if end is negative the index is calculated as length + end. If end is omitted end is equal to the array length. .. js:function:: array.weakref() @@ -410,7 +409,7 @@ removes all the items from the array .. js:function:: array.map(func(a)) -creates a new array of the same size. for each element in the original array invokes the function 'func' and assigns the return value of the function to the corresponding element of the newly created array. +Creates a new array of the same size. For each element in the original array invokes the function 'func' and assigns the return value of the function to the corresponding element of the newly created array. .. js:function:: array.apply(func(a)) diff --git a/squirrel/sqcompiler.cpp b/squirrel/sqcompiler.cpp index 8a932f9..175459c 100644 --- a/squirrel/sqcompiler.cpp +++ b/squirrel/sqcompiler.cpp @@ -1337,11 +1337,11 @@ public: val._unVal.fFloat = -_lex._fvalue; break; default: - Error(_SC("scalar expected : integer,float")); + Error(_SC("scalar expected : integer, float")); } break; default: - Error(_SC("scalar expected : integer,float or string")); + Error(_SC("scalar expected : integer, float, or string")); } Lex(); return val; From 98b5cc434d4ccfb1800b716366f52a3bc9cad7af Mon Sep 17 00:00:00 2001 From: zeromus Date: Sun, 19 Jun 2016 18:48:01 -0500 Subject: [PATCH 07/14] support sq_getinteger() for bools (returns SQFalse or SQTrue in the SQInteger). Useful for format("%d",mybool) --- squirrel/sqapi.cpp | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/squirrel/sqapi.cpp b/squirrel/sqapi.cpp index 034e7be..419e218 100644 --- a/squirrel/sqapi.cpp +++ b/squirrel/sqapi.cpp @@ -657,6 +657,10 @@ SQRESULT sq_getinteger(HSQUIRRELVM v,SQInteger idx,SQInteger *i) *i = tointeger(o); return SQ_OK; } + if(sq_isbool(o)) { + *i = SQVM::IsFalse(o)?SQFalse:SQTrue; + return SQ_OK; + } return SQ_ERROR; } From 457f3b25bc3e29e4b147a7227a9bc95220a18fa9 Mon Sep 17 00:00:00 2001 From: zeromus Date: Mon, 20 Jun 2016 01:07:30 -0500 Subject: [PATCH 08/14] docs fix... all the builtin_functions for `function` were mislabeled as `array`? --- .../reference/language/builtin_functions.rst | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/source/reference/language/builtin_functions.rst b/doc/source/reference/language/builtin_functions.rst index 01f02c5..1da388f 100644 --- a/doc/source/reference/language/builtin_functions.rst +++ b/doc/source/reference/language/builtin_functions.rst @@ -435,52 +435,52 @@ Performs a linear search for the value in the array. Returns the index of the va Function ^^^^^^^^ -.. js:function:: array.call(_this,args...) +.. js:function:: function.call(_this,args...) calls the function with the specified environment object('this') and parameters -.. js:function:: array.pcall(_this,args...) +.. js:function:: function.pcall(_this,args...) calls the function with the specified environment object('this') and parameters, this function will not invoke the error callback in case of failure(pcall stays for 'protected call') -.. js:function:: array.acall(array_args) +.. js:function:: function.acall(array_args) calls the function with the specified environment object('this') and parameters. The function accepts an array containing the parameters that will be passed to the called function.Where array_args has to contain the required 'this' object at the [0] position. -.. js:function:: array.pacall(array_args) +.. js:function:: function.pacall(array_args) calls the function with the specified environment object('this') and parameters. The function accepts an array containing the parameters that will be passed to the called function.Where array_args has to contain the required 'this' object at the [0] position. This function will not invoke the error callback in case of failure(pacall stays for 'protected array call') -.. js:function:: array.weakref() +.. js:function:: function.weakref() returns a weak reference to the object. -.. js:function:: array.tostring() +.. js:function:: function.tostring() returns the string "(closure : pointer)". -.. js:function:: array.setroot(table) +.. js:function:: function.setroot(table) sets the root table of a closure -.. js:function:: array.getroot() +.. js:function:: function.getroot() returns the root table of the closure -.. js:function:: array.bindenv(env) +.. js:function:: function.bindenv(env) clones the function(aka closure) and bind the environment object to it(table,class or instance). the this parameter of the newly create function will always be set to env. Note that the created function holds a weak reference to its environment object so cannot be used to control its lifetime. -.. js:function:: array.getinfos() +.. js:function:: function.getinfos() returns a table containing informations about the function, like parameters, name and source name; :: From 87deb68c46bd027dde3a62eb69aa1531829a6e36 Mon Sep 17 00:00:00 2001 From: zeromus Date: Mon, 20 Jun 2016 01:51:44 -0500 Subject: [PATCH 09/14] rewrite docs for 'this' argument passing. I found some of the finer points to be confusing (I was led to believe indexing a function off an object would bindenv the object to it, but it doesnt). So I changed the language to 'immediately indexed' and then tried to elaborate that. --- doc/source/reference/language/functions.rst | 28 +++++++++++++++------ 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/doc/source/reference/language/functions.rst b/doc/source/reference/language/functions.rst index e7a07db..c66fc24 100644 --- a/doc/source/reference/language/functions.rst +++ b/doc/source/reference/language/functions.rst @@ -140,19 +140,31 @@ Function calls The expression is evaluated in this order: derefexp after the explist (arguments) and at the end the call. -Every function call in Squirrel passes the environment object *this* as hidden parameter -to the called function. The 'this' parameter is the object where the function was indexed -from. +A function call in Squirrel passes the current environment object *this* as a hidden parameter. +But when the function was immediately indexed from an object, *this* shall be the object +which was indexed, instead. -If we call a function with this syntax:: +If we call a function with the syntax:: - table.foo(a) + mytable.foo(x,y) -the environment object passed to foo will be 'table':: +the environment object passed to 'foo' as *this* will be 'mytable' (since 'foo' was immediately indexed from 'mytable') - foo(x,y) // equivalent to this.foo(x,y) +Whereas with the syntax:: -The environment object will be *this* (the same of the caller function). + foo(x,y) // implicitly equivalent to this.foo(x,y) + +the environment object will be the current *this* (that is, propagated from the caller's *this*). + +It may help to remember the rules in the following way: + + foo(x,y) ---> this.foo(x,y) + table.foo(x,y) ---> call foo with (table,x,y) + +It may also help to consider why it works this way: it's designed to assist with object-oriented style. +When calling 'foo(x,y)' it's assumed you're calling another member of the object (or of the file) and +so should operate on the same object. +When calling 'mytable.foo(x,y)' it's written plainly that you're calling a member of a different object. --------------------------------------------- Binding an environment to a function From ba338b145cf59339454a88de908e3a07206a2b2d Mon Sep 17 00:00:00 2001 From: zeromus Date: Tue, 21 Jun 2016 19:29:53 -0500 Subject: [PATCH 10/14] remove spurious 'previdx' from _tostring metamethod docs --- doc/source/reference/language/metamethods.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/reference/language/metamethods.rst b/doc/source/reference/language/metamethods.rst index cfaaa48..260b030 100644 --- a/doc/source/reference/language/metamethods.rst +++ b/doc/source/reference/language/metamethods.rst @@ -226,7 +226,7 @@ _nexti _nexti(previdx) -invoked when a userdata or class instance is iterated by a foreach loop +invoked when a userdata or class instance is iterated by a foreach loop. If previdx==null it means that it is the first iteration. The function has to return the index of the 'next' value. @@ -237,10 +237,10 @@ _tostring :: - _tostring(previdx) + _tostring() -invoked when during string concatenation or when the ``print`` function prints a table, instance, or userdata. -The method is also invoked by the sq_tostring() API +Invoked when during string concatenation or when the ``print`` function prints a table, instance, or userdata. +The method is also invoked by the sq_tostring() API. Must return a string representation of the object. From 90cd4bc2382554bfa808baca120ad6dc108b9e06 Mon Sep 17 00:00:00 2001 From: Allen Luce Date: Thu, 23 Jun 2016 14:48:20 -0700 Subject: [PATCH 11/14] Documentation cleanup, part one. --- doc/source/reference/introduction.rst | 10 +-- doc/source/reference/language/datatypes.rst | 79 ++++++++++--------- .../reference/language/lexical_structure.rst | 26 +++--- 3 files changed, 59 insertions(+), 56 deletions(-) diff --git a/doc/source/reference/introduction.rst b/doc/source/reference/introduction.rst index 348fcb6..bc83447 100644 --- a/doc/source/reference/introduction.rst +++ b/doc/source/reference/introduction.rst @@ -7,10 +7,10 @@ Introduction .. index:: single: introduction -Squirrel is a high level imperative-OO programming language, designed to be a powerful -scripting tool that fits in the size, memory bandwidth, and real-time requirements of +Squirrel is a high-level, imperative-OO programming language, designed to be a powerful +scripting tool that fits within the size, memory bandwidth, and real-time requirements of applications like games. -Although Squirrel offers a wide range of features like dynamic typing, delegation, higher +Squirrel offers a wide range of features like dynamic typing, delegation, higher order functions, generators, tail recursion, exception handling, automatic memory -management, both compiler and virtual machine fit together in about 6k lines of C++ -code. \ No newline at end of file +management while fitting both compiler and virtual machine into about 6k lines of C++ +code. diff --git a/doc/source/reference/language/datatypes.rst b/doc/source/reference/language/datatypes.rst index 4ffc34f..843ed8b 100644 --- a/doc/source/reference/language/datatypes.rst +++ b/doc/source/reference/language/datatypes.rst @@ -4,10 +4,11 @@ Values and Data types ===================== -Squirrel is a dynamically typed language so variables do not have a type, although they -refer to a value that does have a type. -Squirrel basic types are integer, float, string, null, table, array, function, generator, -class, instance, bool, thread and userdata. +While Squirrel is a dynamically typed language and variables do not +have a type, different operations may interpret the variable as +containing a type. Squirrel's basic types are integer, float, string, +null, table, array, function, generator, class, instance, bool, thread +and userdata. .. _userdata-index: @@ -15,7 +16,7 @@ class, instance, bool, thread and userdata. Integer -------- -An Integer represents a 32 bits (or better) signed number.:: +An Integer represents a 32 bit (or better) signed number.:: local a = 123 //decimal local b = 0x0012 //hexadecimal @@ -26,7 +27,7 @@ An Integer represents a 32 bits (or better) signed number.:: Float -------- -A float represents a 32 bits (or better) floating point number.:: +A float represents a 32 bit (or better) floating point number.:: local a=1.0 local b=0.234 @@ -35,24 +36,27 @@ A float represents a 32 bits (or better) floating point number.:: String -------- -Strings are an immutable sequence of characters to modify a string is necessary create a new one. +Strings are an immutable sequence of characters. In order to modify a +string is it necessary create a new one. -Squirrel's strings, behave like C or C++, are delimited by quotation marks(``"``) and can contain -escape sequences(``\t``, ``\a``, ``\b``, ``\n``, ``\r``, ``\v``, ``\f``, ``\\``, ``\"``, ``\'``, ``\0``, -``\x``, ``\u`` and ``\U``). +Squirrel's strings are similar to strings in C or C++. They are +delimited by quotation marks(``"``) and can contain escape +sequences (``\t``, ``\a``, ``\b``, ``\n``, ``\r``, ``\v``, ``\f``, +``\\``, ``\"``, ``\'``, ``\0``, ``\x``, ``\u`` and +``\U``). -Verbatim string literals begin with ``@"`` and end with the matching quote. -Verbatim string literals also can extend over a line break. If they do, they -include any white space characters between the quotes: :: +Verbatim string literals do not interpret escape sequences. They begin +with ``@"`` and end with the matching quote. Verbatim string literals +also can extend over a line break. If they do, they include any white +space characters between the quotes: :: local a = "I'm a wonderful string\n" // has a newline at the end of the string local x = @"I'm a verbatim string\n" - // the \n is copied in the string same as \\n in a regular string "I'm a verbatim string\n" + // the \n is literal, similar to "\\n" in a regular string. -The only exception to the "no escape sequence" rule for verbatim -string literals is that you can put a double quotation mark inside a -verbatim string by doubling it: :: +However, a doubled quotation mark within a verbatim string is replaced +by a single quotation mark: :: local multiline = @" this is a multiline string @@ -73,7 +77,7 @@ reference. The type Null has exactly one value, called null.:: Bool -------- -the bool data type can have only two. They are the literals ``true`` +Bool is a double-valued (Boolean) data type. Its literals are ``true`` and ``false``. A bool value expresses the validity of a condition (tells whether the condition is true or false).:: @@ -83,7 +87,8 @@ and ``false``. A bool value expresses the validity of a condition Table -------- -Tables are associative containers implemented as pairs of key/value (called a slot).:: +Tables are associative containers implemented as a set of key/value pairs +called slots.:: local t={} local test= @@ -96,7 +101,7 @@ Tables are associative containers implemented as pairs of key/value (called a sl Array -------- -Arrays are simple sequence of objects, their size is dynamic and their index starts always from 0.:: +Arrays are simple sequence of objects. Their size is dynamic and their index always starts from 0.:: local a = ["I'm","an","array"] local b = [null] @@ -106,46 +111,48 @@ Arrays are simple sequence of objects, their size is dynamic and their index sta Function -------- -Functions are similar to those in other C-like languages and to most programming -languages in general, however there are a few key differences (see below). +Functions are similar to those in other C-like languages with a few key differences (see below). -------- Class -------- -Classes are associative containers implemented as pairs of key/value. Classes are created through -a 'class expression' or a 'class statement'. class members can be inherited from another class object -at creation time. After creation members can be added until a instance of the class is created. +Classes are associative containers implemented as sets of key/value +pairs. Classes are created through a 'class expression' or a 'class +statement'. class members can be inherited from another class object +at creation time. After creation, members can be added until an +instance of the class is created. -------------- Class Instance -------------- -Class instances are created by calling a *class object*. Instances, as tables, are -implemented as pair of key/value. Instances members cannot be dynamically added or removed; however the value of the members can be changed. - - +Class instances are created by calling a *class object*. Instances, as +tables, are implemented as sets of key/value pairs. Instance members +cannot be dynamically added or removed; however the value of the +members can be changed. --------- Generator --------- -Generators are functions that can be suspended with the statement 'yield' and resumed -later (see :ref:`Generators `). +Generators are functions that can be suspended with the statement +'yield' and resumed later (see :ref:`Generators `). --------- Userdata --------- -Userdata objects are blobs of memory(or pointers) defined by the host application but -stored into Squirrel variables (See :ref:`Userdata and UserPointers `). - +Userdata objects are blobs of memory or pointers defined by the host +application but stored within Squirrel variables (See :ref:`Userdata +and UserPointers `). --------- Thread --------- -Threads are objects that represents a cooperative thread of execution, also known as coroutines. +Threads are objects representing a cooperative thread of execution, +also known as coroutines. -------------- Weak Reference @@ -153,5 +160,3 @@ Weak Reference Weak References are objects that point to another (non-scalar) object but do not own a strong reference to it. (See :ref:`Weak References `). - - diff --git a/doc/source/reference/language/lexical_structure.rst b/doc/source/reference/language/lexical_structure.rst index 05cba40..72e23f5 100644 --- a/doc/source/reference/language/lexical_structure.rst +++ b/doc/source/reference/language/lexical_structure.rst @@ -13,11 +13,11 @@ Identifiers .. index:: single: identifiers -Identifiers start with a alphabetic character or '_' followed by any number of alphabetic -characters, '_' or digits ([0-9]). Squirrel is a case sensitive language, this means that the -lowercase and uppercase representation of the same alphabetic character are considered -different characters. For instance "foo", "Foo" and "fOo" will be treated as 3 distinct -identifiers. +Identifiers start with an alphabetic character or the symbol '_' followed by any number +of alphabetic characters, '_' or digits ([0-9]). Squirrel is a case sensitive language +meaning that the lowercase and uppercase representation of the same alphabetic +character are considered different characters. For instance, "foo", "Foo" and "fOo" are +treated as 3 distinct identifiers. ----------- Keywords @@ -25,7 +25,7 @@ Keywords .. index:: single: keywords -The following words are reserved words by the language and cannot be used as identifiers: +The following words are reserved and cannot be used as identifiers: +------------+------------+-----------+------------+------------+-------------+ | base | break | case | catch | class | clone | @@ -69,7 +69,7 @@ Other tokens single: delimiters single: other tokens -Other used tokens are: +Other significant tokens are: +----------+----------+----------+----------+----------+----------+ | ``{`` | ``}`` | ``[`` | ``]`` | ``.`` | ``:`` | @@ -86,7 +86,7 @@ Literals single: string literals single: numeric literals -Squirrel accepts integer numbers, floating point numbers and strings literals. +Squirrel accepts integer numbers, floating point numbers and string literals. +-------------------------------+------------------------------------------+ | ``34`` | Integer number(base 10) | @@ -131,7 +131,7 @@ A comment is text that the compiler ignores but that is useful for programmers. Comments are normally used to embed annotations in the code. The compiler treats them as white space. -The ``/*`` (slash, asterisk) characters, followed by any +A comment can be ``/*`` (slash, asterisk) characters, followed by any sequence of characters (including new lines), followed by the ``*/`` characters. This syntax is the same as ANSI C.:: @@ -141,9 +141,9 @@ followed by the ``*/`` characters. This syntax is the same as ANSI C.:: this lines will be ignored by the compiler */ -The ``//`` (two slashes) characters, followed by any sequence of characters. -A new line not immediately preceded by a backslash terminates this form of comment. -It is commonly called a *"single-line comment."*:: +A comment can also be ``//`` (two slashes) characters, followed by any sequence of +characters. A new line not immediately preceded by a backslash terminates this form of +comment. It is commonly called a *"single-line comment."*:: //this is a single line comment. this line will be ignored by the compiler @@ -152,5 +152,3 @@ The character ``#`` is an alternative syntax for single line comment.:: # this is also a single line comment. This to facilitate the use of squirrel in UNIX-style shell scripts. - - From d81f7e1c9d2e9e17d2598be543f5497457d8fccd Mon Sep 17 00:00:00 2001 From: zeromus Date: Sun, 26 Jun 2016 20:19:51 -0500 Subject: [PATCH 12/14] fix typo in sq_writeclosure error message --- squirrel/sqapi.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/squirrel/sqapi.cpp b/squirrel/sqapi.cpp index 419e218..9c48af9 100644 --- a/squirrel/sqapi.cpp +++ b/squirrel/sqapi.cpp @@ -1243,7 +1243,7 @@ SQRESULT sq_writeclosure(HSQUIRRELVM v,SQWRITEFUNC w,SQUserPointer up) _GETSAFE_OBJ(v, -1, OT_CLOSURE,o); unsigned short tag = SQ_BYTECODE_STREAM_TAG; if(_closure(*o)->_function->_noutervalues) - return sq_throwerror(v,_SC("a closure with free valiables bound it cannot be serialized")); + return sq_throwerror(v,_SC("a closure with free variables bound cannot be serialized")); if(w(up,&tag,2) != 2) return sq_throwerror(v,_SC("io error")); if(!_closure(*o)->Save(v,up,w)) From e618271e1102cdec5272d58c653b5020ec1c8d14 Mon Sep 17 00:00:00 2001 From: zeromus Date: Tue, 12 Jul 2016 18:06:30 -0500 Subject: [PATCH 13/14] add mechanism for configuring squirrel by #including _SQ_CONFIG_INCLUDE, if it exists --- include/squirrel.h | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/include/squirrel.h b/include/squirrel.h index d936274..37332a9 100644 --- a/include/squirrel.h +++ b/include/squirrel.h @@ -22,6 +22,10 @@ THE SOFTWARE. #ifndef _SQUIRREL_H_ #define _SQUIRREL_H_ +#ifdef _SQ_CONFIG_INCLUDE +#include _SQ_CONFIG_INCLUDE +#endif + #ifdef __cplusplus extern "C" { #endif From 15e2c23eea330b385e8c924e4122138674de32fd Mon Sep 17 00:00:00 2001 From: msakuta Date: Tue, 19 Jul 2016 16:19:35 -0400 Subject: [PATCH 14/14] Minor spelling fix --- doc/source/reference/language/functions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/reference/language/functions.rst b/doc/source/reference/language/functions.rst index c66fc24..4323d61 100644 --- a/doc/source/reference/language/functions.rst +++ b/doc/source/reference/language/functions.rst @@ -196,7 +196,7 @@ Lambda Expressions exp := '@' '(' paramlist ')' exp -Lambda expressions are a synctactic sugar to quickly define a function that consists of a single expression. +Lambda expressions are a syntactic sugar to quickly define a function that consists of a single expression. This feature comes handy when functional programming patterns are applied, like map/reduce or passing a compare method to array.sort().