README.md

CLAF

Library for Garry's Mod addons

CLAF is a set of wrappers and libraries for the standard API which makes the Garry's Mod addons development easier.
See wiki for the documentation.

Why to use?

CLAF provides functional programming, aliases and shortcuts for the standard API to make the addon programming easier.

Features

Functional programming

Quickly modify tables with functional programming features:

-- Filtering numbers in traditional way...
local numbers = { 1, 2, 3, 4, 5 }
for k, number in pairs(numbers) do
    if number % 2 != 0 then
        numbers[k] = nil
    end
end

-- ...and in functional way

local numbers = { 1, 2, 3, 4, 5 }
numbers = Filter(numbers, function(x) return IsOdd(x) end)

local inp = {
    { { x = 1 }, { x = 2 } },
    { { x = 3 }, { x = 4 } },
}

local result = Pipe(inp)
    :Flatten()
    :Map('x')
    :Sum()

assert(result == 10)

Popular language features simulation

Try-catch

Run code that can cause errors in Try():

Try(function()
    -- some error-potential code
end,
-- error handler
function(errorMessage)
    print('something went wrong: '..errorMessage)
end)

Enums and flags

LiquidType = Enum { 'WATER', 'LAVA', 'OIL' }
bottle = { liquid = LiquidType.WATER }

Settings = Flags { 'SHOW_WELCOME', 'SHOW_HELP', 'SHOW_HINTS' }

-- Combining flags
userSettings = bit.bor(Settings.SHOW_WELCOME, Settings.SHOW_HELP)

-- Reading flags
welcome = bit.band(userSettings, Settings.SHOW_WELCOME) -- true
help = bit.band(userSettings, Settings.SHOW_HELP)    -- true
hints = bit.band(userSettings, Settings.SHOW_HINTS) -- false

String interpolation

Easily insert variables' values into strings using the string interpolation:

local name = 'John'
str = fmt'My name is {name}'
-- 'My name is John'

How to use?

While the addon development

1. Subscribe to CLAF addon in Steam Workshop.
2. Add the following line to the beginning of the source files where CLAF is used:

include 'claf.lua'

When it's time to publish

Add dependency of CLAF Steam Workshop addon on your addon. Alternatively, you can copy the library files into your addon, but don't forget to include a license notice (see LICENSE).

Setting up for development

1. Install WSL or MinGW, because running Lua natively on Windows is sort of a nightmare.

2. Install Lua.

   For WSL (assuming you have Ubuntu chosen as your WSL distribution):

   sudo apt install lua5.2

   For MinGW:

   pacman -S mingw-w64-x86_64-lua

3. Clone the repository.

4. Install LuaRocks.

   For WSL (assuming you have Ubuntu chosen as your WSL distribution):

   sudo apt install luarocks

   For MinGW:

   pacman -S mingw-w64-lua-luarocks

5. Run lua maint.lua prepare-dev in the root directory of the project. This will install development dependencies such as tools for formatting, testing and linting the code.

maint.lua

maint.lua is a script that helps with the development of the library. It can be used to run tests, format the code, etc.
It can be invoked by running lua maint.lua <task> in the root directory of the project, where <task> is one of the following:

• prepare-dev - installs development dependencies.
• prepare-ci - used in CI; installs development dependencies globally with sudo. This makes the tools available system-wide.
• test - runs tests.
• generate-coverage-data - runs busted -c which geneates coverage data in luacov.stats.out file. Use the cover task to generate a humar-readable HTML report.
• cover - runs tests and generates a coverage report in HTML format.
• check-coverage-percentage - checks if the coverage percentage is above the threshold. The threshold is defined in tools/check-coverage-percentage.sh.
• lint - scans for potential errors in the code.
• format - reformats the code.
• format-check - checks if the code is formatted according to a standard.
• ci - runs all the checks that are run on the CI server. If the command fails, it means that the code is not ready to be committed.