chore(repo): generate docs, add makefile

Changes the repo to generate documentation from the code using
ldoc. Also adds a Makefile for all common operations.

.github/workflows/lua.yml

@@ -45,11 +45,7 @@ jobs:
     - uses: leafo/gh-actions-luarocks@v4
 
     - name: dependencies
-      run: |
-        luarocks make
-        luarocks install lua-cjson
-        luarocks install busted
+      run: make dev
 
     - name: test
-      run: |
-        busted --lua=lua
+      run: busted --lua=lua

.github/workflows/luacheck.yml

@@ -24,8 +24,7 @@ jobs:
         uses: actions/checkout@v3
       - uses: leafo/gh-actions-lua@v9
       - uses: leafo/gh-actions-luarocks@v4
-      - name: Lint rockspecs
-        run: |
-          for i in $(find . -type f -name "*.rockspec"); do echo $i; luarocks lint $i || exit 1; done
-      - name: Luacheck
-        uses: lunarmodules/luacheck@v0
+      - name: dependencies
+        run: make dev
+      - name: Lint
+        run: make lint

.github/workflows/openresty.yml

@@ -44,9 +44,7 @@ jobs:
         withLuaPath: "/usr/local/openresty/luajit/"
 
     - name: dependencies
-      run: |
-        luarocks make
-        luarocks install busted
+      run: make dev
 
     - name: test
       run: busted

CHANGELOG.md

@@ -0,0 +1,109 @@
+# CHANGELOG
+
+## Versioning
+
+This library is versioned based on Semantic Versioning ([SemVer](https://semver.org/)).
+
+#### Version scoping
+
+The scope of what is covered by the version number excludes:
+
+- error messages; the text of the messages can change, unless specifically documented.
+
+#### Releasing new versions
+
+- update the changelog below
+- check copyright years in `LICENSE.md` and in the module level doc comments in `init.lua`
+- create new rockspec; `cp lua-resty-ljsonschema-scm-1.rockspec rockspecs/lua-resty-ljsonschema-X.Y.Z-1.rockspec`
+- edit the rockspec to match the new release
+- render the documentation; `ldoc .`
+- commit changes as `release X.Y.Z`, using `git add rockspecs/ && git commit -a`
+- tag the commit; `git tag X.Y.Z`
+- push the commit and the tag; `git push && git push --tags`
+- upload rockspec; `luarocks upload rockspecs/lua-resty-ljsonschema-X.Y.Z-1.rockspec --api-key=abcdef`
+
+## Version history
+
+### 1.1.6 (21-Sep-2023)
+
+- fix: properly check custom.array_mt
+  ([#22](https://github.com/Tieske/lua-resty-ljsonschema/pull/22))
+- improvement: use openresty table functions if available (`isarray` and `nkeys`)
+  ([#22](https://github.com/Tieske/lua-resty-ljsonschema/pull/22))
+- fix: add lua-cjson to the rockspec since it is required
+  ([#23](https://github.com/Tieske/lua-resty-ljsonschema/pull/23))
+
+### 1.1.5 (27-Jun-2023)
+
+- fix: using default Lua `tostring` on numbers when generating code can loose
+  precision. Implemented a non-lossy function.
+  ([#21](https://github.com/Tieske/lua-resty-ljsonschema/pull/21))
+
+### 1.1.4 (25-Apr-2023)
+
+- fix: typo in error message
+  ([#16](https://github.com/Tieske/lua-resty-ljsonschema/pull/16))
+- fix: update reported types in error messages (eg. 'userdata' instead of 'null')
+  ([#17](https://github.com/Tieske/lua-resty-ljsonschema/pull/17))
+- ci: switch CI to Github Actions
+  ([#18](https://github.com/Tieske/lua-resty-ljsonschema/pull/18))
+- ci: add plain Lua to the version matrix
+  ([#19](https://github.com/Tieske/lua-resty-ljsonschema/pull/19))
+
+### 1.1.3 (8-Dec-2022)
+
+- fix: reference properties can start with an "_"
+  ([#15](https://github.com/Tieske/lua-resty-ljsonschema/pull/15))
+
+### 1.1.2 (30-Apr-2021)
+
+- fix: fixes an issue where properties called "id" were mistaken for schema ids
+  ([#13](https://github.com/Tieske/lua-resty-ljsonschema/pull/13))
+
+### 1.1.1 (28-Oct-2020)
+
+- fix: fixes an error in the `maxItems` error message
+  ([#7](https://github.com/Tieske/lua-resty-ljsonschema/pull/7))
+- fix: date-time validation would error out on bad input
+  ([#10](https://github.com/Tieske/lua-resty-ljsonschema/pull/10))
+- improvement: anyOf failures now list what failed
+  ([#9](https://github.com/Tieske/lua-resty-ljsonschema/pull/9))
+
+### 1.1.0 (18-aug-2020)
+
+- fix: if a `schema.pattern` clause contained a `%` then the generated code
+  for error messages (invoking `string.format`) would fail because it tried
+  to substitute it (assuming it to be a format specifier). `%` is now properly
+  escaped.
+- feat: add `date`, `date-time`, and `time` Semantic validation for "format"
+  attribute. Validation follows the RFC3339 specification sections
+  [5.6][rfc3339-5.6] and [5.7][rfc3339-5.7] for dates and times.
+
+### 1.0 (15-may-2020)
+
+- fix: using a string-key containing only numbers would fail because it was
+  automatically converted to a number while looking up references.
+
+### 0.3 (18-dec-2019)
+
+- fix: use a table instead of local variables to work around the limitation of
+  a maximum of 200 local variables, which is being hit with complex schemas.
+
+### 0.2 (21-jul-2019)
+
+- feat: added automatic coercion option
+- refactor: remove all coroutine calls (by @davidor)
+- feat: add function to validate schemas against the jsonschema meta-schema
+
+### 0.1 (13-jun-2019)
+
+- fix: use PCRE regex if available instead of Lua patterns (better jsonschema
+  compliance)
+- fix: deal with broken coroutine override in OpenResty (by @jdesgats)
+- move array/object validation over to OpenResty based CJSON implementation
+  (using the `array_mt`)
+- fix: schema with only 'required' was not validated at all
+- updated testsuite to use Busted
+- fix: quoting/escaping
+
+### 7-Jun-2019 Forked from https://github.com/jdesgats/ljsonschema

LICENSE → LICENSE.md

@@ -1,6 +1,6 @@
-MIT License
+# MIT License
 
-Copyright (c) 2017 Julien Desgats, 2019-2023 Thijs Schreijer
+### Copyright (c) 2017 Julien Desgats, 2019-2023 Thijs Schreijer
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Makefile

@@ -0,0 +1,122 @@
+# additional Busted options to pass
+BUSTED:=
+
+# SCM rockspec label; scm/cvs/dev
+SCM_LABEL:=$(shell cat *.rockspec | grep "local package_version" | sed "s/ //g" | sed "s/localpackage_version=//g" | sed "s/\"//g")
+ROCK_REV:=$(shell cat *.rockspec | grep "local rockspec_revision" | sed "s/ //g" | sed "s/localrockspec_revision=//g" | sed "s/\"//g")
+ROCK_NAME:=$(shell cat *.rockspec | grep "local package_name" | sed "s/ //g" | sed "s/localpackage_name=//g" | sed "s/\"//g")
+ROCKSPEC:=${ROCK_NAME}-${SCM_LABEL}-${ROCK_REV}.rockspec
+TAB=$(shell printf "\t")
+
+# dev/test dependencies; versions can be pinned. Example: "ldoc 1.4.6"
+DEV_ROCKS = "busted" "luacheck" "ldoc" "luacov"
+
+
+target_not_specified: help
+	@exit 1
+
+
+help:
+	@echo "Available make targets for ${ROCK_NAME}:"
+	@echo ""
+	@echo "install:     uses LuaRocks to install ${ROCK_NAME}"
+	@echo "uninstall:   uninstalls ALL versions of ${ROCK_NAME} (using LuaRocks with"
+	@echo "             the '--force' flag)"
+	@echo "clean:       removes LuaCov output, packed rocks, and restores docs to the"
+	@echo "             last commited version"
+	@echo "test:        runs the test suite using Busted"
+	@echo "testinst:    installs ${ROCK_NAME} and runs tests using the installed version"
+	@echo "             (this modifies the local installation, but also tests the"
+	@echo "             .rockspec file). This is best used when testing in CI."
+	@echo "lint:        will validate all 'rockspec' files using LuaRocks, and the"
+	@echo "             '.lua' files with LuaCheck"
+	@echo "doc/docs:    regenerates the documentation using LDoc"
+	@echo "deps:        installs the module dependencies"
+	@echo "dev:         installs the development dependencies (Busted, LuaCheck, etc.)"
+	@echo "help:        displays this list of make targets"
+	@echo ""
+
+
+install: luarocks
+	luarocks make
+
+
+uninstall: luarocks
+	if (luarocks list --porcelain ${ROCK_NAME} | grep "^${ROCK_NAME}${TAB}" | grep -q "installed") ; then \
+	  luarocks remove ${ROCK_NAME} --force; \
+	fi;
+
+
+# note: restore the docs to the last committed version
+clean: clean_luacov clean_luarocks clean_doc
+	git checkout docs
+	$(RM) -r spec/JSON-Schema-Test-Suite
+	mkdir spec/JSON-Schema-Test-Suite
+
+
+.PHONY: test
+test: clean_luacov dev
+	busted ${BUSTED}
+
+
+# test while having the code installed; also tests the rockspec, but
+# this will modify the local luarocks installation/tree!!
+.PHONY: testinst
+testinst: clean_luacov dev uninstall install
+	busted --lpath="" --cpath="" ${BUSTED}
+
+
+.PHONY: lint
+lint: dev
+	@echo "luarocks lint ..."
+	@for spec in $(shell find . -type f -name "*.rockspec") ; do \
+	  (luarocks lint $$spec && echo "$$spec [OK]") || (echo "$$spec [NOK]"; exit 1); \
+	done
+	luacheck .
+
+
+.PHONY: doc
+doc: clean_doc dev
+	mkdir -p ./docs
+	ldoc . --date=""
+
+
+.PHONY: docs
+docs: doc
+
+
+.PHONY: deps
+deps: luarocks
+	luarocks install $(ROCKSPEC) --deps-only
+
+
+# submodule with the JSONscehma test suite
+spec/JSON-Schema-Test-Suite/.git:
+	git submodule update --init --recursive; \
+
+
+.PHONY: dev
+dev: luarocks deps spec/JSON-Schema-Test-Suite/.git
+	@for rock in $(DEV_ROCKS) ; do \
+	  (luarocks list --porcelain $$rock | grep -q "installed") || (luarocks install $$rock || exit 1); \
+	done;
+
+
+.PHONY: clean_doc
+clean_doc:
+	$(RM) -r docs
+
+
+.PHONY: clean_luarocks
+clean_luarocks:
+	$(RM) *.rock
+
+
+.PHONY: clean_luacov
+clean_luacov:
+	$(RM) luacov.report.out luacov.stats.out
+
+
+.PHONY: luarocks
+luarocks:
+	@which luarocks > /dev/null || (echo "LuaRocks was not found. Please install and/or make available in the path." && exit 1)