Skip to content

Commit 40c518e

Browse files
derek-millerderek-miller
committed
Initial release
1 parent d893217 commit 40c518e

15 files changed

Lines changed: 3112 additions & 0 deletions

File tree

‎.emmyrc.json‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{
2+
"$schema": "https://raw.githubusercontent.com/EmmyLuaLs/emmylua-analyzer-rust/refs/heads/main/crates/emmylua_code_analysis/resources/schema.json",
3+
"runtime": {
4+
"version": "LuaJIT"
5+
},
6+
"workspace": {
7+
"userThirdParty": [
8+
"/Users/demiller/git/lua-addons"
9+
],
10+
"library": [
11+
],
12+
"useGitIgnore": false,
13+
"ignoreDir": [
14+
".claude",
15+
".git",
16+
".idea",
17+
".venv",
18+
"build",
19+
"dist",
20+
"node_modules"
21+
]
22+
},
23+
"diagnostics": {
24+
"disable": [
25+
"unnecessary-assert"
26+
]
27+
}
28+
}

‎.github/workflows/build.yml‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
name: Lua Tests
2+
3+
on:
4+
push:
5+
branches: [ main, master ]
6+
pull_request:
7+
branches: [ main, master ]
8+
9+
concurrency:
10+
group: ${{ github.workflow }}-${{ github.ref }}
11+
cancel-in-progress: true
12+
13+
jobs:
14+
check:
15+
runs-on: ubuntu-latest
16+
name: Check
17+
steps:
18+
- uses: actions/checkout@v4
19+
20+
- name: Setup Lua
21+
uses: leafo/gh-actions-lua@v11
22+
with:
23+
luaVersion: '5.4'
24+
25+
- name: Setup LuaRocks
26+
uses: leafo/gh-actions-luarocks@v5
27+
with:
28+
luarocksVersion: "3.12.2"
29+
30+
- name: Install luacheck
31+
run: luarocks install luacheck
32+
33+
- name: Install stylua
34+
uses: JohnnyMorganz/stylua-action@v4
35+
with:
36+
token: ${{ secrets.GITHUB_TOKEN }}
37+
version: v2.1.0
38+
args: false # Will be run as part of `make check`
39+
40+
- name: Check
41+
run: make check
42+
43+
test:
44+
needs: check
45+
runs-on: ubuntu-latest
46+
continue-on-error: false
47+
strategy:
48+
fail-fast: true
49+
matrix:
50+
lua-version: ['5.1', '5.2', '5.3', '5.4', 'luajit-2.0', 'luajit-2.1']
51+
52+
name: Lua ${{ matrix.lua-version }}
53+
steps:
54+
- uses: actions/checkout@v4
55+
56+
- name: Setup Lua
57+
uses: leafo/gh-actions-lua@v11
58+
with:
59+
luaVersion: ${{ matrix.lua-version }}
60+
61+
- name: Setup tests
62+
run: |
63+
# Set the correct binary name based on the Lua version
64+
if [[ "${{ matrix.lua-version }}" == luajit* ]]; then
65+
LUA_BINARY=luajit
66+
else
67+
LUA_BINARY=lua
68+
fi
69+
70+
echo "LUA_BINARY=$LUA_BINARY" >> "$GITHUB_ENV"
71+
${LUA_BINARY} -v
72+
73+
- name: Run tests
74+
run: |
75+
make test-all
76+
77+
build:
78+
needs: test
79+
runs-on: ubuntu-latest
80+
name: Build Combined Module
81+
steps:
82+
- uses: actions/checkout@v4
83+
84+
- name: Setup Lua
85+
uses: leafo/gh-actions-lua@v11
86+
with:
87+
luaVersion: '5.4'
88+
89+
- name: Setup LuaRocks
90+
uses: leafo/gh-actions-luarocks@v5
91+
with:
92+
luarocksVersion: "3.12.2"
93+
94+
- name: Install amalg
95+
run: luarocks install amalg
96+
97+
- name: Build combined module
98+
run: make build
99+
100+
- name: Verify build
101+
run: |
102+
# Check default build
103+
if [ -f "build/bitn.lua" ]; then
104+
echo "✅ build/bitn.lua exists ($(wc -c < "build/bitn.lua") bytes)"
105+
# Quick sanity check - make sure it contains expected content
106+
if grep -q "bitn" build/bitn.lua; then
107+
echo "✅ Build contains expected content"
108+
else
109+
echo "❌ Build seems corrupted"
110+
exit 1
111+
fi
112+
else
113+
echo "❌ build/bitn.lua missing"
114+
exit 1
115+
fi
116+
117+
- name: Upload artifacts
118+
uses: actions/upload-artifact@v4
119+
with:
120+
name: bitn.lua
121+
path: build/bitn.lua
122+
retention-days: 30

‎.github/workflows/release.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
8+
permissions:
9+
contents: write
10+
11+
jobs:
12+
release:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- name: Checkout code
16+
uses: actions/checkout@v4
17+
with:
18+
fetch-depth: 0
19+
20+
- name: Setup Lua
21+
uses: leafo/gh-actions-lua@v11
22+
with:
23+
luaVersion: '5.4'
24+
25+
- name: Setup LuaRocks
26+
uses: leafo/gh-actions-luarocks@v5
27+
with:
28+
luarocksVersion: "3.12.2"
29+
30+
- name: Install amalg
31+
run: luarocks install amalg
32+
33+
- name: Build combined module
34+
run: |
35+
# The make build command will automatically inject the version from the git tag
36+
make build
37+
38+
- name: Create Release
39+
uses: softprops/action-gh-release@v1
40+
with:
41+
draft: false
42+
prerelease: ${{ contains(github.ref_name, '-rc') || contains(github.ref_name, '-beta') || contains(github.ref_name, '-alpha') }}
43+
name: Release ${{ github.ref_name }}
44+
tag_name: ${{ github.ref }}
45+
generate_release_notes: true
46+
files: |
47+
build/bitn.lua

‎.gitignore‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Compiled Lua sources
2+
luac.out
3+
4+
# luarocks build files
5+
*.src.rock
6+
*.zip
7+
*.tar.gz
8+
9+
# Object files
10+
*.o
11+
*.os
12+
*.ko
13+
*.obj
14+
*.elf
15+
16+
# Precompiled Headers
17+
*.gch
18+
*.pch
19+
20+
# Libraries
21+
*.lib
22+
*.a
23+
*.la
24+
*.lo
25+
*.def
26+
*.exp
27+
28+
# Shared objects (inc. Windows DLLs)
29+
*.dll
30+
*.so
31+
*.so.*
32+
*.dylib
33+
34+
# Executables
35+
*.exe
36+
*.out
37+
*.app
38+
*.i*86
39+
*.x86_64
40+
*.hex
41+
42+
# Build artifacts
43+
build/

‎.luacheckrc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
std = "min"
2+
globals = {
3+
unpack = {}
4+
}
5+
ignore = {
6+
"212/_.*",
7+
"211/_.*",
8+
"213/_.*",
9+
}
10+
compat = true
11+
unused_args = false
12+
max_line_length = false

‎CLAUDE.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# lua-bitn Development Guide
2+
3+
## Project Structure
4+
5+
```
6+
lua-bitn/
7+
├── src/bitn/
8+
│ ├── init.lua # Module aggregator, exports bit16/bit32/bit64
9+
│ ├── bit16.lua # 16-bit bitwise operations
10+
│ ├── bit32.lua # 32-bit bitwise operations
11+
│ └── bit64.lua # 64-bit bitwise operations (uses {high, low} pairs)
12+
├── tests/
13+
│ ├── test_bit16.lua # 16-bit test vectors
14+
│ ├── test_bit32.lua # 32-bit test vectors
15+
│ └── test_bit64.lua # 64-bit test vectors
16+
├── .github/workflows/
17+
│ ├── build.yml # CI: lint, test matrix, build
18+
│ └── release.yml # Release automation
19+
├── run_tests.sh # Main test runner
20+
├── run_tests_matrix.sh # Multi-version test runner
21+
└── Makefile # Build automation
22+
```
23+
24+
## Key Commands
25+
26+
```bash
27+
# Run tests
28+
make test
29+
30+
# Run specific module tests
31+
make test-bit32
32+
33+
# Run across Lua versions
34+
make test-matrix
35+
36+
# Format code
37+
make format
38+
39+
# Lint code
40+
make lint
41+
42+
# Build single-file distribution
43+
make build
44+
```
45+
46+
## Architecture
47+
48+
### Module Design
49+
50+
Each bit module (bit16, bit32, bit64) provides the same API:
51+
- Bitwise: band, bor, bxor, bnot
52+
- Shifts: lshift, rshift, arshift
53+
- Rotates: rol, ror
54+
- Arithmetic: add, mask
55+
- Byte conversions: uN_to_be_bytes, uN_to_le_bytes, be_bytes_to_uN, le_bytes_to_uN
56+
57+
### 64-bit Representation
58+
59+
64-bit values use `{high, low}` pairs for Lua 5.1 compatibility:
60+
```lua
61+
-- 0x123456789ABCDEF0 represented as:
62+
local value = {0x12345678, 0x9ABCDEF0}
63+
```
64+
65+
### Pure Lua Implementation
66+
67+
All operations are implemented using basic Lua arithmetic to ensure
68+
compatibility across all Lua versions without native bit library dependencies.
69+
70+
## Testing
71+
72+
Tests use Lua table-based vectors for easy maintenance:
73+
74+
```lua
75+
local test_vectors = {
76+
{ name = "band(0xFF, 0x0F)", fn = bit32.band, inputs = {0xFF, 0x0F}, expected = 0x0F },
77+
-- ...
78+
}
79+
```
80+
81+
Run with: `./run_tests.sh` or `make test`
82+
83+
## Building
84+
85+
The build process uses `amalg` to create a single-file distribution:
86+
87+
```bash
88+
make build
89+
# Output: build/bitn.lua
90+
```
91+
92+
Version is automatically injected from git tags during release.
93+
94+
## CI/CD
95+
96+
- **build.yml**: Runs on push/PR to main
97+
- Format check with stylua
98+
- Lint with luacheck
99+
- Test matrix (Lua 5.1-5.4, LuaJIT 2.0/2.1)
100+
- Build single-file distribution
101+
102+
- **release.yml**: Runs on version tags (v*)
103+
- Builds and publishes release with bitn.lua artifact
104+
105+
## Code Style
106+
107+
- 2-space indentation
108+
- 120 column width
109+
- Double quotes preferred
110+
- LuaDoc annotations for all public functions

0 commit comments

Comments
 (0)