1
0

Bunch a' thoughts and documentation.

This commit is contained in:
Jon Michael Aanes 2017-07-17 21:33:11 +02:00
parent 00d3f653a8
commit d0d8e6476f
7 changed files with 110 additions and 2 deletions

View File

@ -1,4 +1,9 @@
-- pretty.analyze_structure
-- The datastructure analyzing module for pretty.
--------------------------------------------------------------------------------
local TABLE_TYPE
do
local thispath, was_loaded = ... and select('1', ...):match('.+%.') or ''

View File

@ -1,4 +1,8 @@
--[=[ The function formatting module for pretty.
-- pretty.function
-- The function formatting module for pretty.
--[=[ Thoughts on displaying functions in an informative way.
How is one supposed to pretty print functions? Well, there are many different
formats, and no "best" one, only "best for the purpose". Lets start at the

View File

@ -1,4 +1,9 @@
-- pretty.init
-- In case somebody loads `init.lua`. Just redirects to `pretty.lua`.
--------------------------------------------------------------------------------
local premodule = (...)
if premodule == 'init' then premodule = '' end
return require (premodule .. (premodule ~= '' and '.' or '') .. 'pretty')

View File

@ -1,5 +1,14 @@
-- TODO: Make lazy? It imports a lot of packages tbh.
-- pretty.library
-- Provides an API for accessing documentation for the Lua standard library, and
-- the LuaJIT extension libraries.
-- FIXME: This is a large module to load from `function.lua` when `pretty` is
-- loaded. Could probably loaded lazily.
-- FIXME: Currently this module imports a bunch of packages, even though it may
-- never need to use them. Could probably load those lazily.
--------------------------------------------------------------------------------
local function_library = {}

View File

@ -1,4 +1,78 @@
-- pretty.number
-- The number formatting module for pretty.
--[=[ Thoughts on displaying numbers in an informative way.
Numbers are such an intrinsic part of computer science, mathematics, science in
general and even finance industry, that it boggles they mind how different they
each treat numbers. This is one of the reasons that many programming languages
possess a huge number of number types: Integers both signed and unsigned,
rational number, floating point numbers, fixed point numbers, not to mention the
various Computer Algebra Systems (CAS), that exist.
Lua has historically used floating point numbers, which can represent numbers in
a huge range, at the cost of non-uniform precision across that range. How can we
represent numbers in a intuitive and useful way?
1. Native representation: We could use Lua's native way of representing
numbers. This is easy, as we just use the `tostring` function.
This is unsatifactory, if we're aiming for Lua-compatible output, as
`tostring` will produce `inf` (`1/0`) and `nan` (`0/0`), which are valid
identifiers, and does not guarentee that these variables are equal to their
respective values.
It's also unsatifactory when aiming for precision, as `tostring` truncate
the output if "close enough".
2. Unnecessary precision: We can use `string.format` with the format code
`%.99f`, to get a "precise" representation of the number. Unfortunantly, for
many "larger" (> 10¹³?) numbers, some of the right digits will be 0, due
to floating point precision issues. We also run against the fact that π is
rounded and is only accurate 15 decimal digits. Do we really care about the
remaining digits, most of which are 0?
3. As required representation: We use as many digits as necessary for the Lua
parser to read the exact same number. Involves invoking `string.format` and
`tonumber` a lot.
This approach improves on 2. as we not only discard all those 0s and the
confusing unaccurate digits. Indeed, many "nice" numbers won't even possess
any decimal digits. Numbers feed directly into the interpreter would look
identical to the input, barring removal of trailing 0s.
And with that we achieved precision and a reasonable amount of consiseness.
4. Fractions: One issue with floating points have always been that the
precision is sorely limited. Some languages possess fraction types, but
such systems suffer from pathological cases, where memory usage spikes.
We can still exploit fractions despite using floating point numbers. When we
type `13/7` into Lua, we get a number back. This is the "canonical"
floating point representation of `13/7`, and every time we encounter this
number, we can use `13/7` to represent it.
This allows more consise representation of certain numbers, for example
numbers with repeating digits. It will also highlight patterns that a
decimal representation might not.
Unfortunantly it might also hide patterns, and it reduces the usefulness of
pretty as a calculator.
5. Reverse engineered number: Remember the concept of "canonical"
representation from 4.? We can expand that concept to also talk about more
general expressions like `math.sqrt(2)` or `2^-5`. Discovering those
expressions from a single number is pretty complex.
Again, this allows for very consise representations of numbers, and can find
hidden patterns all over the place. It's much easier to see the relation to
radians when we see `0.5*math.pi`, rather than `0.78539816339745`.
But again we lose the calculator aspect.
6. TODO: Write about `inf` and `nan`.
7. TODO: Write about rounding.
8. TODO: Write about unicode.
We a bit of every one of the above methods. They each have their upsides and
their drawbacks. Which approach we use, depend on the number, and what is the
shortest representation.
If the chosen representation is different from the "as required approach", and
we're only pretty printing a single number value, then we also append the
approximate value given by the "as required approach" approach as a comment, in
case somebody was looking for that.
--]=]
--------------------------------------------------------------------------------
-- Constants
local MAXIMUM_INT = 2^53 -- The maximum double for where all integers can be represented exactly.
@ -61,6 +135,7 @@ local SPECIAL_NUMBER = {
repr = function (a) return ('math.exp(%.0f)'):format(a) end,
},
-- x = aπ
-- TODO: Add support for factions of π.
{ est = function (n) return n/math.pi end,
real = function (a) return a*math.pi end,
repr = function (a) return a == 1 and 'math.pi' or a..'*math.pi' end,

View File

@ -1,4 +1,11 @@
-- pretty.pretty
-- Main module of the `pretty` library.
-- TODO: Maybe move table formatting into its own file?
--------------------------------------------------------------------------------
-- Ensure loading library, if it exists, no matter where pretty.lua was loaded from.
-- Load the library component

View File

@ -1,4 +1,7 @@
-- TODO: I don't like to have such tiny modules. Either merge into another
-- module or provide the funtionallity with another approach.
--------------------------------------------------------------------------------
-- Enum