sugar

The sugar library is a set of sub-libraries that adds a ton of functional programming helper extensions to the various core objects of Lua.

Using The Library

Addons should require the common library if they wish to use the sugar library. It is included automatically with it.

1require 'common';

Below you can find some information regarding each sub-library of sugar.

Because of how many functions this collection of sub-libraries implements, full documentation will not be made for every function. Please refer to the actual source files for more information on all of the functions available.

boolean

Implements various helper functions used with boolean type values.

This sub-library also overrides the default boolean type metatable to expose these new functions directly onto boolean type values.

function

Implements various helper functions used with function type values.

This sub-library also overrides the default function type metatable to expose these new functions directly onto function type values.

math

Implements various helper functions that extend the default math. global table.

This sub-library also overrides the default number type metatable to expose these new functions directly onto number type values.

nil

This sub-library will override the default metatable for the nil type. This is considered dangerous because of what this will do to the default functionality of Lua.

Lua, by default, will raise an error if you attempt to call or index a nil value. This is good practice to avoid unintended situations in code and should generally ALWAYS be followed. This sub-library will remove those restrictions of Lua and allow you to attempt to call a nil function, inde a nil object/value, etc.

• This SHOULD NOT be used to avoid proper error handling.
• This SHOULD NOT be used to avoid fixing problems with code.

Please DO NOT use this sub-library unless you know what you’re doing!

If you do wish to use this feature, then you will need to adjust how you include the common library to call the enabler function for it:

1local common = require 'common';
2
3common.sugar.enable_nil_sugar();    -- Enables the nil metatable override..
4common.sugar.disable_nil_sugar();   -- Disables the nil metatable override..

string

Implements various helper functions that extend the default string. global table.

This sub-library also overrides the default string type metatable to expose these new functions directly onto string type values.

table

Implements various helper functions that extend the default table. global table.

Because of how Lua functions, it is not possible to fully override the table type metatable and have additional functionality applied to any table type. To get around this, sugar implements its own table initialization call. This wraps the given table with an enhanced metatable giving access to call all table functions directly on the type. You can use this function to either create a new or ‘upgrade’ an existing table.

1-- Normal Lua Table..
2local t1 = { };
3
4-- Sugar Enhanced Table..
5local t2 = T{ };
6
7-- Sugar Enhanced Table Upgrade..
8local t3 = T(t1);

When you create a sugar enhanced table, this enables all of sugar’s features that are extending the metatable of the table object.

Here is an example:

 1-- Normal Lua table usage example..
 2local t = { };
 3table.insert(t, 2);
 4table.insert(t, 3);
 5table.insert(t, 1);
 6table.sort(t);
 7
 8for k, v in pairs (t) do print(v); end
 9
10-- Sugar enhanced table usage example..
11local t = T{ };
12t:insert(2);
13t:insert(3);
14t:insert(1);
15t:sort();
16t:each(function (v) print(v); end);

Sugar is very powerful in how much it can allow you to transform normal Lua code into a functional programming syntax.