|
1 | 1 | # Mods |
2 | 2 |
|
3 | | -**Mods** is a Lua utility library with predictable APIs, 💤 lazy-loaded |
4 | | -inter-module dependencies, and support for Lua 5.1, 5.2, 5.3, 5.4, and LuaJIT. |
| 3 | +[](https://luarocks.org/modules/BlueLua/mods) |
| 4 | +[](https://github.com/BlueLua/mods/actions/workflows/test.yml) |
| 5 | + |
| 6 | + |
| 7 | +[](https://github.com/BlueLua/mods/blob/main/LICENSE) |
5 | 8 |
|
6 | | -> [!IMPORTANT] |
7 | | -> |
8 | | -> This library is not stable yet, and APIs may change between releases. |
| 9 | +`mods` is a comprehensive Lua utility library featuring lazy-loaded modules and |
| 10 | +wide runtime compatibility. |
9 | 11 |
|
10 | | -This project is inspired by |
11 | | -[Penlight (pl)](https://github.com/lunarmodules/Penlight). |
| 12 | +See the [documentation] for full API references and guides. |
12 | 13 |
|
13 | | -If this project helps you, consider starring the repo ⭐. |
| 14 | +## ✨ Features |
14 | 15 |
|
15 | | -## Table of Contents |
| 16 | +- **Predictable APIs**: A cohesive collection of helper utilities for common |
| 17 | + programming tasks and data structures. |
| 18 | +- **Lazy Loading**: Automatic lazy loading of sub-modules to keep startup times |
| 19 | + fast. |
| 20 | +- **Cross-Platform**: Works consistently across Windows, macOS, and Linux. |
| 21 | +- **Multiple Lua Versions**: Compatible with LuaJIT, Lua 5.1, 5.2, 5.3, 5.4, and |
| 22 | + 5.5. |
| 23 | +- **Lightweight**: Pure Lua with no dependencies, except optional [LFS] for file |
| 24 | + operations. |
| 25 | +- **Autocomplete**: [LuaLS] type annotations. |
16 | 26 |
|
17 | | -- [Documentation](#documentation) |
18 | | -- [Installation](#installation) |
19 | | -- [Modules](#modules) |
20 | | -- [Development Status](#development-status) |
21 | | -- [Acknowledgments](#acknowledgments) |
22 | | - |
23 | | -## Documentation |
24 | | - |
25 | | -Guides, module overviews, and examples live in the |
26 | | -[docs](https://luamod.github.io/mods). |
27 | | - |
28 | | -## Installation |
29 | | - |
30 | | -### LuaRocks |
| 27 | +## 📦 Installation |
31 | 28 |
|
32 | 29 | ```sh |
33 | 30 | luarocks install mods |
34 | 31 | ``` |
35 | 32 |
|
36 | | -### Manual |
37 | | - |
38 | | -- **Unix (🐧 Linux / 🍎 macOS)**: |
39 | | - |
40 | | - ```sh |
41 | | - git clone https://github.com/luamod/mods.git |
42 | | - cd mods |
43 | | - mkdir -p /usr/local/share/lua/5.x/ |
44 | | - cp -r src/mods /usr/local/share/lua/5.x/ |
45 | | - ``` |
46 | | - |
47 | | -- **🪟 Windows**: |
48 | | - |
49 | | - Copy all files from [`src/mods/`](src/mods/) to |
50 | | - `C:\Program Files\Lua\5.x\lua\mods\`. |
51 | | - |
52 | | -> [!IMPORTANT] |
53 | | -> |
54 | | -> Replace `5.x` with your Lua version (for example, `5.4`). |
| 33 | +## 🚀 Usage |
55 | 34 |
|
56 | | -## Modules |
| 35 | +```lua |
| 36 | +local mods = require "mods" |
57 | 37 |
|
58 | | -| Module | Description | |
59 | | -| -------------- | -------------------------------------------------------------------------- | |
60 | | -| [`fs`] | Filesystem I/O, metadata, and filesystem path operations. | |
61 | | -| [`is`] | Type predicates for Lua values and filesystem path types. | |
62 | | -| [`keyword`] | Helpers for Lua keywords and identifiers. | |
63 | | -| [`List`] | A list class for creating, transforming, and querying sequences of values. | |
64 | | -| [`ntpath`] | Windows/NT-style path operations. | |
65 | | -| [`operator`] | Lua operators exposed as functions. | |
66 | | -| [`path`] | Cross-platform path operations with host-platform semantics. | |
67 | | -| [`posixpath`] | POSIX-style path operations. | |
68 | | -| [`stringify`] | Readable string rendering for Lua values. | |
69 | | -| [`runtime`] | Lua runtime metadata and version compatibility flags. | |
70 | | -| [`Set`] | A set class for creating, combining, and querying unique values. | |
71 | | -| [`str`] | String operations for searching, splitting, trimming, and formatting text. | |
72 | | -| [`stringcase`] | String case conversion and word splitting. | |
73 | | -| [`tbl`] | Table operations for querying, copying, merging, and transforming tables. | |
74 | | -| [`template`] | String template rendering with `{{...}}` placeholders. | |
75 | | -| [`utils`] | Shared utility helpers used across the Mods library. | |
76 | | -| [`validate`] | Validation helpers for Lua values and filesystem path types. | |
| 38 | +local stripped = mods.str.strip(" hello world ") |
| 39 | +print(stripped) -- Output: "hello world" |
77 | 40 |
|
78 | | -> [!NOTE] |
79 | | -> |
80 | | -> We are still working on adding new modules and improving the docs. |
81 | | -
|
82 | | -## Development Status |
83 | | - |
84 | | -This project is still under active development. We are also building supporting |
85 | | -tools in parallel, including a type parser to improve autogenerated docs and a |
86 | | -better test toolchain. |
87 | | - |
88 | | -Since release `v0.6.0`, tests and documentation have been changing frequently. |
89 | | -That means contributors may occasionally run into bugs while working with the |
90 | | -latest commits. We also add new modules before each formal release, so the |
91 | | -repository may contain changes that are not available in the published version |
92 | | -yet. Please work from the most recent code in the repository, as the next |
93 | | -release will include fixes for issues discovered during this phase. |
94 | | - |
95 | | -**Mods** will act as a core helper library for our upcoming lua projects. |
96 | | - |
97 | | -## Acknowledgments |
98 | | - |
99 | | -Thanks to these Lua ecosystem projects: |
100 | | - |
101 | | -- [lfs](https://github.com/lunarmodules/luafilesystem) for filesystem utilities. |
102 | | -- [inspect](https://github.com/kikito/inspect.lua) for readable table |
103 | | - representation. |
104 | | -- [busted](https://github.com/lunarmodules/busted) for test framework support. |
| 41 | +local items = mods.list({ 1, 2, 3 }) |
| 42 | +local reversed = items:reverse() |
| 43 | +print(reversed:join(", ")) -- Output: "3, 2, 1" |
| 44 | +``` |
105 | 45 |
|
106 | | -[`fs`]: https://luamod.github.io/mods/modules/fs |
107 | | -[`is`]: https://luamod.github.io/mods/modules/is |
108 | | -[`keyword`]: https://luamod.github.io/mods/modules/keyword |
109 | | -[`List`]: https://luamod.github.io/mods/modules/list |
110 | | -[`ntpath`]: https://luamod.github.io/mods/modules/ntpath |
111 | | -[`operator`]: https://luamod.github.io/mods/modules/operator |
112 | | -[`path`]: https://luamod.github.io/mods/modules/path |
113 | | -[`posixpath`]: https://luamod.github.io/mods/modules/posixpath |
114 | | -[`stringify`]: https://luamod.github.io/mods/modules/stringify |
115 | | -[`runtime`]: https://luamod.github.io/mods/modules/runtime |
116 | | -[`Set`]: https://luamod.github.io/mods/modules/set |
117 | | -[`str`]: https://luamod.github.io/mods/modules/str |
118 | | -[`stringcase`]: https://luamod.github.io/mods/modules/stringcase |
119 | | -[`tbl`]: https://luamod.github.io/mods/modules/tbl |
120 | | -[`template`]: https://luamod.github.io/mods/modules/template |
121 | | -[`utils`]: https://luamod.github.io/mods/modules/utils |
122 | | -[`validate`]: https://luamod.github.io/mods/modules/validate |
| 46 | +[documentation]: https://bluelua.github.io/mods |
| 47 | +[LFS]: https://github.com/lunarmodules/luafilesystem |
| 48 | +[LuaLS]: https://github.com/LuaLS/lua-language-server |
0 commit comments