From e98487fcaeca5a93394750887ad55f9b4fd8d96c Mon Sep 17 00:00:00 2001
From: Jon Michael Aanes <jonjmaa@gmail.com>
Date: Mon, 5 Jun 2017 21:49:23 +0200
Subject: [PATCH] Added basic `README.md`

---
 README.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 97 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index cd0b596..d4c7c73 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,98 @@
 
-README is TODO
+# Pretty #
+
+## Introduction
+
+`pretty` is an advanced pretty printer for [Lua](lua.org). It attempts to
+understand your datastructures and return a pretty printed string
+representation. It's primary purpose is to be a good human-readable debugging
+tool, not a speedy serialization tool.
+
+Humans are flexible in their understanding of data, as long as certain
+underlying structural patterns can be found. `pretty` attempts to find those
+patterns and highlight them, often after performing huge analytical tasks.
+
+Sometimes just aligning elements are enough to easy the burden on the eyes.
+Contrast the two following pieces of code:
+
+```lua
+	bad = {
+		a = 'hello world',
+		hello = 'hi'
+	}
+	good = {
+		a      =  'hello world',
+		hello  =  'hi'
+	}
+```
+
+This project came out of the frustration with existing pretty printers, which
+would often employ simpler heuristics, each good at displaying some specific
+structure, but bad at others. See below for other pretty printers.
+
+Another aspect where `pretty` shines is in exploratory programming, when
+attempting to avoid reliance on outside documentation.
+
+## Features
+
+-	Written in good-old pureblood Lua, with support for PUC Lua 5.0 - 5.3 and
+	LuaJIT 2.0 and up.
+-	Redefining what it means to be "human readable":
+	*	Is multi-line centric, to aid readablitiy.
+	*	Indention and alignment of keys-value pairs.
+	*	Keys-value pairs are [properly](http://www.davekoelle.com/alphanum.html)
+		sorted by key type and thereafter alphabetically.
+	*	The format and structure of output changes depending upon the input.
+		Maps are displayed differently to deeply nested tables to long sequences
+		with short strings to short lists.
+	*	Uses the standard `debug` library to gain information about functions
+		and other advanced structures.
+
+## Performance
+
+As specified in the introduction, `pretty` is not a performance oriented
+library. Expected usage is in error conditions and debugging, not in tight
+inner loops.
+
+Don't use `pretty.lua` if you want fast serialization. Use one of the pretty
+printers specified below.
+
+## TODO
+
+I'm looking into implementing following features:
+
+-	Improve display of medium-long lists with short elements better. One option
+	would be to implement something analog to the default results of `ls` on
+	Linux.
+-	Add support for `setmetatable`, and exploring the values accessible through
+	it.
+-	Nice formatting for `cdata` datatype in LuaJIT.
+-	Add possibility of comments in output, for stuff like `__tostring` methods,
+	and global namespaces like `io` or `math`.
+-	Better support upvalues in functions. Complete support is impossible without
+	traversing the original code or inspecting the intermediate representation,
+	due to lexical scoping. (Pluto does it, but it's written in C.)
+-	Look more into `string.dump` in the core library.
+-	Look into using concat operation to improve appearance of overly long
+	non-breaking strings. Maybe even attempt to break near whitespace.
+-	Attempt to fit output within a predefined width limit. Default to 80(?)
+
+## Other pretty printers
+
+`pretty` is a large and slow library, and is not designed for serialization
+purposes, nor is `pretty` concerned with offering the same level of
+stabilizability as other libraries do.
+
+Luckily Lua has a large library of pretty printers and serialization libraries:
+
+-	[inspect.lua](github.com/kikito/inspect.lua): One of the classic debugging
+	pretty printers.
+-	[pprint.lua](github.com/jagt/pprint.lua): Reimplementation of `inspect.lua`
+-	[serpent](github.com/pkulchenko/serpent): Advanced and fast pretty printer.
+-	[pluto](lua-users.org/wiki/PlutoLibrary): Can serialize arbitrary parts of
+	Lua, including functions, upvalues, and proper lexical scoping. Not written
+	in native Lua.
+-	[binser](github.com/bakpakin/binser): Library for special purpose
+	serialization.
+
+Others can be found at [the lua-users wiki](lua-users.org/wiki/TableSerialization).