This is a guest post by long time Corona user Matthew Webster.
While Corona is simple, powerful and has many useful APIs, there’s always that one extra thing. Often, the one thing is apparently simple enough to be incorporated into an existing Lua API, but may appear forgotten about.
This tutorial will show you how to:
- Add new functionality to the existing libraries
- Extend the existing functionality
Corona library APIs
All functionality in Corona are provided by library APIs. The documentation for which is found here.
If we take a look at the 'string.*' API we can see a collection of functions such as:
- string.find()
- string.format()
- string.gsub()
- string.len()
- string.lower()
It happens that all of these functions are not written in Lua, they are handles into lower level functions provided in either C++ (cross platform), Objective-C (for iOS) or Java (for Android.) The same is true for libraries like the 'math.*' APIs.
Some APIs, however, are provided completely in Lua, for example Corona’s 'widget.*' API is entirely written in Lua. Corona Labs have even made the original source code available!
Whichever implementation the Corona Labs engineers have chosen to go with their code, the fact still stands that in our Lua world each function has its hands firmly tied to the rules of Lua. In fact, every library (including the 'string.*' API) is actually a table. That’s right: 'string' is a table and all the functions defined above are members of that table.
This allows us to do some really clever things quite easily.
A Useful Function
The first thing we’ll learn is how to add our own functions to Corona SDKs own API Libraries. Why would we want to do that? Well, let’s say you’ve written a really useful function which removes the leading and trailing spaces from a string. In most languages this is usually called 'trim()':
local function trim( str ) return (str:gsub("^%s\*(.-)%s\*$", "%1")) end
Don’t worry about what is actually happening inside the function. Just know that you’ve written it, it’s awesome and works really well when you want have a string which has really annoying spaces at the startand end:
print( trim( " Hello World! " ) )
Outputs:
Hello World!
The normal practice for many Corona developers is to put this 'trim()' function into a library file, such as
“utils.lua“. What we want to do is make it a bit more memorable and categorically accurate… This function is
a string function, so it should be accessed like the other string functions.
Adding to Corona’s APIs
To be clear, our function is in a file called "utils.lua" so we want all the work done in that file. Of course, "utils.lua" will be loaded into memory in our "main.lua" with a standard 'require' call:
require("utils")
The function in the "utils.lua" looks like this:
local function trim( str ) return (str:gsub("^%s\*(.-)%s\*$", "%1")) end
So let’s add this function to the 'string.*' API. In "utils.lua" after we define our function we follow it with a standard table value assignment (this is the magic bit):
string.trim = trim
And that’s it. Easy.
You can now call 'string.trim(" Hello World! ")' from anywhere in your code and it will print:
Hello World!
The Beauty of a Library
Let’s say we have a string defined:
local str = " Hello World! "
What’s great about having the 'trim()' function in the string API is that we can now call the function as a member of any string variable:
print( str:trim() )
Will output:
Hello World!
This is because the 'string' library represents string variables in general.
It’s important to note, that this does not add your trim function to everyone’s Corona string.* library nor will it make it available to your next project. You will need to continue require your util.lua file. But the idea here that:
string.trim()
makes more semantical sense than:
util.trim()
Hopefully this simple trick will make your development with Corona a bit more easy.