Initial Readme

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):
+<jonjmaa@gmail.com> 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.
+```
+