Home

Awesome

Penlight Lua Libraries

Unix build AppVeyor build status Coveralls code coverage Luacheck SemVer

Why a new set of libraries?

Penlight brings together a set of generally useful pure Lua modules, focusing on input data handling (such as reading configuration files), functional programming (such as map, reduce, placeholder expressions, etc), and OS path management. Much of the functionality is inspired by the Python standard libraries.

Module Overview

Paths, Files and Directories

Application Support

Extra String Operations

Extra Table Operations

Iterators, OOP and Functional

Versioning

Penlight is strictly versioned according to Semantic Versioning.

In scope of the version:

Not in scope of the version:

Deprecating functionality

Any version may deprecate functionality. So new deprecation notices may appear in major, minor, and patch releases. Final removal of functionality (assuming it is a breaking change) will only be done in a major version.

It is strongly suggested to use the deprecation warning mechanism to test usage of deprecated functionalities when upgrading. This is done by enabling the warning system (in Lua 5.4, or the Penlight compatibility function for earlier versions):

require "pl.compat"
warn "@on"

See pl.utils.raise_deprecation for more info.

License

Penlight is distributed under the MIT license.

Installation

Using LuaRocks: simply run luarocks install penlight.

Manually: copy lua/pl directory into your Lua module path. It's typically /usr/local/share/lua/5.x on a Linux system and C:\Program Files\Lua\5.x\lua for Lua for Windows.

Dependencies

The file and directory functions depend on LuaFileSystem, which is installed automatically if you are using LuaRocks. Additionally, if you want dir.copyfile to work elegantly on Windows, then you need Alien. Both libraries are present in Lua for Windows.

Building the Documentation

Requires ldoc, which is available through LuaRocks. Then it's a simple matter of running ldoc . from the repo.

Contributing

Contributions are most welcome, please check the contribution guidelines.

Running tests

Execute lua run.lua tests to run the tests. Execute lua run.lua examples to run examples.

History

For a complete history of the development of Penlight, please check the changelog.