Awesome
Penlight Lua Libraries
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
path
: queries likeisdir
,isfile
,exists
, splitting paths likedirname
andbasename
dir
: listing files in directories (getfiles
,getallfiles
) and creating/removing directory pathsfile
:copy
,move
; read/write contents withread
andwrite
Application Support
app
:require_here
to rebaserequire
to work with main script path; simple argument parsingparse_args
lapp
: sophisticated usage-text-driven argument parsing for applicationsconfig
: flexibly read Unix config files and Windows INI filesstrict
: check for undefined global variables - can usestrict.module
for modulesutils
,compat
: Penlight support for unified Lua 5.1/5.2 codebasestypes
: predicates likeis_callable
andis_integer
; extendedtype
function.
Extra String Operations
utils
: can split a string with a delimiter usingutils.split
stringx
: extended string functions covering the Pythonstring
typestringio
: open strings for reading, and creating strings using standard Lua IO methodslexer
: lexical scanner for splitting text into tokens; special cases for Lua and Ctext
: indenting and dedenting text, wrapping paragraphs; optionally make%
work as in Pythontemplate
: small but powerful template expansion enginesip
: Simple Input Patterns - higher-level string patterns for parsing text
Extra Table Operations
tablex
: copying, comparing and mapping overpretty
: pretty-printing Lua tables, and various safe ways to load Lua as dataList
: implementation of Python 'list' type - slices, concatenation and partitioningMap
,Set
,OrderedMap
: classes for specialized kinds of tablesdata
: reading tabular data into 2D arrays and efficient queriesarray2d
: operations on 2D arrayspermute
: generate permutations
Iterators, OOP and Functional
seq
: working with iterator pipelines; collecting iterators as tablesclass
: a simple reusable class frameworkfunc
: symbolic manipulation of expressions and lambda expressionsutils
:utils.string_lambda
converts short strings like '|x| x^2' into functionscomprehension
: list comprehensions:C'x for x=1,4'()=={1,2,3,4}
Versioning
Penlight is strictly versioned according to Semantic Versioning.
In scope of the version:
- functionality provided by Penlight modules/classes
- based on stock Lua PuC-Rio or LuaJIT
Not in scope of the version:
- Documentation
- Error messages (textual changes)
- Deprecation warnings (by default to
stderr
)
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.