Extensions

SSK2 extends a number of Lua and Corona libraries/functions.

display.*

Function	Summary
`isValid( obj )`	Returns `true` if `obj` is a valid display object.
`newContainer( ... )`	Adds flags `__isContainer = true` and `__isGroup = true` to returned container.
`newGroup( )`	Adds flags `__isContainer = false` and `__isGroup = true` to returned group.

io.*

Note: Unless otherwise specified, if a function takes the (optional) argument base, it defaults to system.DocumentsDirectory

Function	Summary
`appendFile( dataToWrite, fileName [ , base ] )`	Append the contents of string `dataToWrite` to the file `fileName`, creating file if it does not exist.
`cleanFileName( filename )`	Cleans the string `filename` to ensure it is safe for use as a file name in all OSes targeted by Corona SDK.
`exists( fileName [, base ] )`	Returns `true` if path exists.
`mkdir( dirName [, base ] )`	Make a new directory with the name `dirName`. (Warning: Parent folders must be created first for compound paths.)
`readFile( fileName [, base ] )`	Returns contents of file at `fileName` as string.
`readFileTable( fileName [, base ] )`	Read the contens of fileName and return it as a table, where each entry is a line from the file. Lines are separated by newline (`\n`).
`repairPath( path )`	Changes 'slashes' in path to match current OS specifications.
`writeFile( dataToWrite, fileName [ , base ] )`	Write the contents of string `dataToWrite` to the file `fileName`.

math.*

Function	Summary
`getUID( rlen )`	Generates and returns a unique ID of length `rlen`. Warning: With a `rlen` of 12 or higher, it is extremely unlikely you will get an id collision, but it is your responsibility to track your prior IDs and verify no collision occurs.
`haversine_dist( lat1, lng1, lat2, lng2 [, R ] )`	Calculate the distance from GPS position to another. Distance is a multiple of R (default is 6373 kilometers == 3961 miles.)
`normRot( toNorm )` (number)	Modifies number `toNorm` and returns equivalent angle in range [0,360).
`normRot( toNorm )` (display object)	Modifies display object `toNorm`, such that `rotation` is an equivalent value in range [0,360).

string.*

Function	Summary
`comma_value( num )`	Returns a nicely comma-separated string version of number `num`.
`endsWith( str, piece)`	Return `true` if `str` ends with `piece`. Credit: Sergey Lerg
`first_upper( str )`	Convert first letter in `str` to upper-case.
`lpad( str, len [, char] )`	Places padding on left side of a string, such that the new string is at least len characters long.
`merge( t )`	Return a string containing all entries in an indexed table concatenated together.
`printf( ... )`	Replicates C-language printf().
`rpad( str, len [, char] )`	Places padding on right side of a string, such that the new string is at least len characters long.
`spaces2underbars( str )`	Returns string converting all spaces () in `str` to underbars (`_`).
`split( str, tok)`	Split `str` into a table, where elements in the string are separated by the token `tok`.
`startsWith( str, piece)`	Return `true` if `str` starts with `piece`. Credit: Sergey Lerg
`trim( str )`	Remove all whitespace from beginning and end of `str`.
`truncate( str, maxLen [, appendMe ] )`	Shorten `str` to maxLen and optionally append `appendMe` to indicate string has been truncated.
`underbars2spaces( str )`	Returns string converting all underbars (`_`) in `str` to spaces ().
`url_decode( str )`	Returns URL decoded version of `str`.
`url_encode( str )`	Returns URL encoded version of `str`.

Torque Derived String Functions

I added a number of functions to string.* based on same-named functions from Torque. These functions operate on:

Words - Strings containing elements separated by a space ().
Fields - Strings containing elements separated by a tab (\t)
Records - Strings containing elements separated by a newline (\n)

Function	Summary
`getWord( str [, index ] )`	Returns `index` (`1`) word in `str`.
`getWordCount( str )`	Counts words in `str`.
`getWords( str, [ index [, endindex ]] )`	Returns a string containing all words in `str` between `index` (`1`) and `endindex` (last word).
`setWord( str, [ index [, replace ]] )`	Returns a string where the word in `str` at `index` (`1`) has been replaced with the string `replace` (`nil`).
`getField( str [, index ] )`	Field equivalent of `getWord()`
`getFieldCount( str )`	Field equivalent of `getWordCount()`
`getFields( str, [ index [, endindex ]] )`	Field equivalent of `getWords()`
`setField( str, [ index [, replace ]] )`	Field equivalent of `setWord()`
`getRecord( str [, index ] )`	Record equivalent of `getWord()`
`getRecordCount( str )`	Record equivalent of `getWordCount()`
`getRecords( str, [ index [, endindex ]] )`	Record equivalent of `getWords()`
`setRecord( str, [ index [, replace ]] )`	Record equivalent of `setWord()`

table.*

Table Debug Features

Function	Summary
`dump(theTable [ , padding [ , marker ]] )`	Dumps indexes and values inside single-level table (for debug) (SORTED).
`dumpu(theTable [ , padding [ , marker ]] )`	Dumps indexes and values inside single-level table (for debug) (UNSORTED).
`print_r( t )`	Dumps indexes and values inside multi-level table (for debug)

Saving & Loading Tables

Note: Unless otherwise specified, if a function takes the (optional) argument base, it defaults to system.DocumentsDirectory

Function	Summary
`load( fileName [ , base ] )`	Returns table loaded from file (Uses JSON library as intermediary)
`prettySave( theTable, fileName [ , base ] )`	Saves table to file as human readable JSON.
`repairIndicies( theTable )`	Repair numeric indicies in table that uses numbers and other values for indexing. Combining index types like this is bad practice if you are going to save() and load() the table. This function repairs the indices after a load.
`save( theTable, fileName [ , base ] )`	Saves table to file (Uses JSON library as intermediary)
`secure_save( theTable, fileName [ , base ] )`	Equivalent to save(), but uses ssk.security.* to obfuscate save.
`secure_load( fileName [ , base ] )`	Equivalent to load(), but uses ssk.security.* to obfuscate save.
`stripSave( theTable, fileName [ , base ] )`	Saves table to file (Uses JSON library as intermediary)

Table Utilities

Function	Summary
`combineUnique( ... )`	Combines n tables into a single table containing only unique members from each source table.
`combineUnique_i( ... )`	Combines n tables into a single table containing only unique members from each source table.
`count( t )`	Counts all entries in table (non-recursive).
`count_r( t )`	Counts all entries in table (recursive).
`deepCopy( src [ , dst ])`	Copies multi-level tables; handles non-integer indexes; does not copy metatable
`deepStripCopy( src [ , dst ])`	Copies multi-level tables, but strips out metatable(s) and Fields with these value types: functions or userdata; Fields with these these names: _class or __index.
`forEach( t, func )`	Calls `func( t, index)` for each entry in table `t`.
`forEachi( t, func )`	Calls `func( t, index)` for each non-sparse numerically-indexed entry in table `t`.
`getRandom( t )`	Return randomly selected entry from table `t`.
`maxIndex( t )`	Determine the maximum index of a sparse table.
`removeByRef( t, obj )`	Locate entry `obj` in numerically indexed table `t` and remove it. Credit: Sergey Lerg
`serialize( t )`	Table Serializer: https://github.com/EmmanuelOga/columns/blob/master/utils/serialize.lua
`shallowCopy( src [ , dst ])`	Copies single-level tables; handles non-integer indexes; does not copy metatable
`shallowStripCopy( src, dst )`	Copies single-level tables; handles non-integer indexes; does not copy metatable
`shuffle( t [, iter ] )`	Randomizes the order of a numerically indexed (non-sparse) table. Supply iteration value `iter` (`1`) for better randomizing.
`tokenize( t [, tok] )`	Combines all elements in a numerically indexed table into a single string separated by tokens `tok`, where the default token is a comma `,`.
`toString( t [, flat ]) )`	Converts table to string (serializes it). Credit: Jason Schroeder

transition.*

color

Adds ability to transition the color of display objects (including text objects) from fromColor to toColor.

transition.color( obj, params )

obj - Text or other display object that supports setFillColor().
params ({}) - Transition control parameters.
- fromColor (_W_) - Starting color.
- toColor (_W_) - Ending color.
- delay (nil) - Time to wait before transitioning in milliseconds.
- time (_W_) - Time to transition in milliseconds.
- transition (_W_) - Easing to use for transition.
- onComplete (nil) - Listener to call on completion of transition.


local tmp = ssk.display.newCircle( nil, centerX, centerY, { radius = 30, fill = _R_ } )

function tmp.onComplete( self )
   print("Done transitioning color.")
end

transition.color( tmp, { fromColor = _R_, toColor = _G_, time = 1000, 
                         transition = easing.outCirc, onComplete = tmp } )