Cleaning up the Code using an API

In this section you will be converting the ASCII parser in to an API that can be required by your scripts. This will give you a way to separate code so it is modular, which prevents duplicate code that also helps tracking down bugs if all the code is in one place.

What is an API?

API is the acronym for Application Programming Interface. An API is a Lua script that is a collection of variables and functions that are used to split code up. An API is not added to the Hierarchy, it is required using the require keyword. Using an API is a great way to split code up so it is more modular and easier to manage. Other scripts in your Hierarchy would require the API and use the variables and functions.

Creating an API

Creating an API is very easy, because an API is just a Lua table. The only difference is that the table is inside a Lua script and must be returned at the end. For example, the code below is a very simple API that allows you to call the Say function to print your message out.

local API = {}

function API.Say(message)
	print(message)
end

return API
Code language: Lua (lua)

A script in your Hierarchy can then require the API. To do this, the script will need a custom property that contains a reference to the API. This can be done by adding the API from your Project Content as a custom property of the script that needs to require the API. In the Properties window, Core detects that a script has been added as a custom property, so the generated code already contains the require for you.

Using an API

Using the basic API example above, using the API is very easy. In your script you can paste in the generate code that requires the API and then make a call to the function inside of that API you created.

local MY_API = require(script:GetCustomProperty("My_API"))

MY_API.Say("My first API.")
Code language: Lua (lua)

If you play the game, in the Event Log (Window menu -> Event Log) you will see the string My first API printed.

---

Creating the ASCII Parser API

Change the existing ASCIIParser script into an API is fairly straight forward. Because this will be an API that is required in scripts, then it can be deleted from the Hierarchy.

Open up the ASCIIParser script to edit it. Add a variable at the top of the script called ASCIIParser, this will be the table that is returned at the end of the script and contains all the functions that can be accessed.

Notice the only other changes are placing ASCIIParser in front of all the functions, including the call to the Clean function inside the BuildMap function.

local ASCIIParser = {}

function ASCIIParser.Clean(map)
	for c = 1, string.len(map) do
		local character = string.sub(map, c, c)
	
		if not string.match(character, "[0-9a-zA-Z]+") then
			map = string.gsub(map, character, "")
		end
	end

	return map
end

function ASCIIParser.BuildMap(map, MAP_WIDTH, MAP_HEIGHT)
	local tableMap = {}
	local mapStr = ""

	map = ASCIIParser.Clean(map)

	for r = 1, MAP_HEIGHT do
		table.insert(tableMap, {})

		for c = 1, MAP_WIDTH do
			local character = string.sub(map, ((r - 1) * MAP_WIDTH) + c, ((r - 1) * MAP_WIDTH) + c)

			tableMap[r][c] = character
			mapStr = mapStr .. character
		end

		mapStr = mapStr .. "\n"
	end

	return tableMap, mapStr
end

return ASCIIParser
Code language: Lua (lua)

Test the ASCII Parser API

It is good practice to test often to make sure scripts work as intended. To make sure the ASCII Parser API is working correctly, you can do a quick test.

Create a Test Script

Create a script called Test and add the ASCIIParser script from Project Content as a custom property.

Edit Test Script

Open up the Test script to edit it and add the following code to make sure the ASCII Parser is working. The ASCII Parser is required at the top of the script, and you can call the BuildMap function which requires the ASCII string, the width, and height of the map.

The BuildMap function will return a table, and also the ASCII string which will verify if the map was built successfully by comparing the ASCII string passed in, and the mapStr value.

local ASCII_PARSER = require(script:GetCustomProperty("ASCIIParser"))

local map, mapStr = ASCII_PARSER.BuildMap([[

	111111
	100001
	111111

]], 6, 3)

print(mapStr)
Code language: Lua (lua)

Test the Game

Test the game by entering play mode and making sure the output that appears in the Event Log matches the input of the BuildMap function. If this matches, then the API is working correctly and is ready to use.