One of the neat features of Lua that we’ve leveraged in several of the Atlas addons is the ability to create a library system in which you can take code that is used frequently, compartmentalize it by placing it into a separate file and then utilize that code in multiple different places.

In a number of the Atlas addons, we were faced with the problem of generating URL fragments based on data available in request records. When we first approached this, we did so somewhat naively and just appended the necessary bits of data to the URL string. This of course caused problems when those pieces of data contained characters that aren’t valid as part of a URL and need to be encoded. To fix this, we created a method that takes a string and returns a URL encoded version. Since we needed that same functionality in several scripts, we extracted the method out into a separate file (which now also contains a couple other functions) which we called AtlasHelpers.lua. Once we did that, we were able to place that file in a central location in our addons folder (specifically, we placed it in the Atlas folder) and simply include it in any addons that need it. This simplified the addons that needed that functionality, since they didn’t all have to have that method in them. It also simplified the process of fine tuning and enhancing that method since we now only have to change it in one place.

So how does this work? Well, fortunately we didn’t actually have to do a whole lot to make this work, since Lua already supports a method for including files. The Lua language itself supports a command called “require”, which takes a single string argument; the string is formatted sort of like a C# or Java namespace and is used to locate and load a code library for use in the script that called require. For exact details on how the Lua system handles the require command, you can see the documentation here, but essentially the string you pass in is treated as a dot delimited file path to the file you are trying to include. Lua plugs the string into a search pattern defined by a global path variable, finds the file and loads it. All we’ve done is to change the loading process for addons so that before loading an addon’s script files, the path variable gets set to something more useful. Specifically, we set the path to “{CurrentAddonDirectory}\\?.lua;{HostAppPath}\\Addons\\?.lua” where HostAppPath is the folder the host application’s executable file resides in, and CurrentAddonDirectory is the base directory for the currently executing addon. What this means for addon developers is that we can now create Lua files inside of our addon folders and reference them just by using something to the effect of:

require "AtlasHelpers"

In addition, we can take those helper files, put all the ones you tend to use repeatedly into a single file in your Addons directory and reference those files with a call as simple as:

require "Atlas.AtlasHelpers"

Now some people may be thinking “Well Travis, that’s awesome and all, but how do I distribute my libraries from a network share if I don’t put them in an addon that will get pulled down automatically?”

Well, we thought of that. What we chose to do was make it so that you can add a config.xml file to your libraries that identifies them as such. The addon system will then see the config file, recognize that it is something it needs to deal with and handle it appropriately. Specifically, it will do all the same version checking that it does for actual addons, and if the network share has a new version, it will be pulled down just like any addon would. There are, however, a couple minor catches. First, while the config files are setup very similarly to the addon config files (in fact, they use the exact same schema definition and get loaded into the exact same class in the scripting system) there is one tag that is required for libraries, as well as some tags that are required for addons but are completely unnecessary for libraries. Below you can see an example of a library’s config.xml file.

	Atlas Library
	Atlas Systems, Inc.
	1.0
	false
	Library

	Contains helper methods for use with user addons.

The first thing you will probably notice is that there are several missing sections. The Forms, Settings, and Files sections are all optional sections in the xml schema and can be safely excluded when dealing with libraries. In addition, you may notice that there is a new tag named Type. The Type element can have one of two values: Library or Addon. These are pretty self explanatory. The only note I will make about this tag is that the tag itself is optional, and it defaults to Addon. This means the tag is unnecessary for addons, but required if you want to identify a library as a library.

So to recap: We can now use libraries in addons by creating the library code files in a separate folder in the addons directory, creating a config file for the library making sure to set the value of the Type element to “Library”, and then using the require statement to include the file in the addons that need it.