From c25676854a92b7bc62729fdd1782288159534fb0 Mon Sep 17 00:00:00 2001 From: Jon Michael Aanes Date: Sat, 28 Oct 2017 13:47:19 +0200 Subject: [PATCH] Initial Readme --- README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..00bcd15 --- /dev/null +++ b/README.md @@ -0,0 +1,48 @@ + +# Assert Gooder # + +_Lua_ library implementing an alternative version of Lua's `assert` function, +giving much better error messages, when asserts fails. It does this by analysing +the body of the assert, and figuring out what the failing assert call is +attempting to test against. + +## Example + +```lua +function f (a) + assert(type(a) == 'string') +end + +f(42) +``` + +Without `assert-gooder`, the above code would fail with the error message +`assertion failed!`. With `assert-gooder`, it will fail with this error message: +`assertion failed! bad argument #1 'a' to 'f' (string expected, but got number: 42)`, + +## Motivation + +Assertions are useful to ensure internal consistency, when you're writing code +in a hurry, but in Lua (and most other languages), these assert constructs never +produce useful error messages, but rather unhelpful `assert failed!` errors and +a stack trace. + +By making it a runtime library, instead of a "compile-time" rewrite, we gain +flexibility. It's much easier to import a library, than restructuring then +compile pipeline. It also means that we have access to runtime values, allowing +even more helpful messages. + +## Setup + +Download, and use `assert = require "assert-gooder"` to overwrite Lua's default +assert with `assert-gooder`. + +## License + +``` +"THE BEER-WARE LICENSE" (Revision 42): + wrote this library. As long as you retain this notice you +can do whatever you want with this stuff. If we meet some day, and you think +this stuff is worth it, you can buy me a beer in return. +``` +