From fe1c16604491c16532ddb52ac4bf78119ffd2565 Mon Sep 17 00:00:00 2001
From: Jon Michael Aanes <jonjmaa@gmail.com>
Date: Tue, 25 Jul 2017 15:37:37 +0200
Subject: [PATCH] Minor documentation and restructure.

---
 pretty.lua | 67 ++++++++++++++++++++++++++++++------------------------
 1 file changed, 37 insertions(+), 30 deletions(-)

diff --git a/pretty.lua b/pretty.lua
index 4e260b2..f114757 100644
--- a/pretty.lua
+++ b/pretty.lua
@@ -136,31 +136,39 @@ local function get_key_value_pairs_in_proper_order (t)
     -- Error checking
     assert(type(t) == 'table')
 
-    -- Do stuff
-    local key_value_pairs = {}
+    -- Find Key-Value Pairs
+    local kv_pairs = {}
+    for key, value in pairs(t) do  kv_pairs[#kv_pairs+1] = { key, value }  end
 
-    for key, value in pairs(t) do
-        key_value_pairs[#key_value_pairs+1] = { key, value }
-    end
+    -- Sort them into the correct order
+    table.sort(kv_pairs, compare_key_value_pair)
 
-    table.sort(key_value_pairs, compare_key_value_pair)
-
-    return key_value_pairs
+    -- Return them
+    return kv_pairs
 end
 
-local function fill_holes_in_key_value_pairs (key_value_pairs)
-    -- NOTE: Assumes that all keys are numbers
+local function fill_holes_in_key_value_pairs (kv_pairs)
+    -- Fills holes in key-value pairs for a sequences with `nil` values. All
+    -- keys must be numbers, and key-value pairs must be sorted already.
+
+    -- Holes can sometimes appear in otherwise nicely structured sequences. We
+    -- want to avoid displaying a sequence as `{[1] = 1, [3] = 3}` when
+    -- `{1, nil, 3}` would work nicely.
 
     -- Error checking
-    assert(type(key_value_pairs) == 'table')
+    assert(type(kv_pairs) == 'table')
 
-    -- Do stuff
-    for i = 2, #key_value_pairs do
-        for j = key_value_pairs[i-1][1] + 1, key_value_pairs[i][1] - 1 do
-            key_value_pairs[#key_value_pairs+1] = { j, nil }
+    -- Add hole filling value
+    assert(type(kv_pairs[1][1]) == 'number')
+    for i = 2, #kv_pairs do
+        assert(type(kv_pairs[i][1]) == 'number')
+        for j = kv_pairs[i-1][1] + 1, kv_pairs[i][1] - 1 do
+            kv_pairs[#kv_pairs+1] = { j, nil }
         end
     end
-    table.sort(key_value_pairs, compare_key_value_pair)
+
+    -- Sort key-value pairs, to place above pairs into their correct locations.
+    table.sort(kv_pairs, compare_key_value_pair)
 end
 
 --------------------------------------------------------------------------------
@@ -378,20 +386,16 @@ local analyze_structure  =  import 'analyze_structure'
 local TABLE_TYPE         =  import 'table_type'
 
 --------------------------------------------------------------------------------
--- Formatting stuff
+-- Key-value pair formatting.
 
-local format_value
-
--- Ways to format keys
-
-local function format_key_and_value_string_map (l, key, value, depth)
+local function format_key_and_value_string_map (key, value, depth, l, format_value)
     l[#l+1] = key
     l[#l+1] = { 'align', 'key', #key }
     l[#l+1] = ' = '
     return format_value(value, depth, l)
 end
 
-local function format_key_and_value_arbitr_map (l, key, value, depth)
+local function format_key_and_value_arbitr_map (key, value, depth, l, format_value)
     local index_before_key = #l+1
     l[#l+1] = '['
     format_value(key, math.huge, l)
@@ -401,7 +405,7 @@ local function format_key_and_value_arbitr_map (l, key, value, depth)
     return format_value(value, depth, l)
 end
 
-local function format_key_and_value_sequence (l, key, value, depth)
+local function format_key_and_value_sequence (key, value, depth, l, format_value)
     return format_value(value, depth, l)
 end
 
@@ -414,9 +418,10 @@ local TABLE_TYPE_TO_PAIR_FORMAT = {
     [TABLE_TYPE.PURE_MAP]   = format_key_and_value_arbitr_map,
 }
 
--- Formatting tables
+-------------------------------------------------------------------------------
+-- Table formatting
 
-local function format_table (t, depth, l)
+local function format_table (t, depth, l, format_value)
     -- Error Checking
     assert(type(t) == 'table')
     assert(type(depth) == 'number' and type(l) == 'table')
@@ -455,7 +460,7 @@ local function format_table (t, depth, l)
     l[#l+1] = {'indent', '{'}
     if l.options._table_addr_comment then  l[#l+1], l[#l+2]  =  '--[['..table_info.address..']]', {'seperator'}  end
     for _, pair in ipairs(key_value_pairs) do
-        pair_format_func(l, pair[1], pair[2], depth + 1)
+        pair_format_func(pair[1], pair[2], depth + 1, l, format_value)
         l[#l+1] = {'seperator', ','}
     end
     if l[#l][1] == 'seperator' then  l[#l] = nil  end
@@ -480,7 +485,8 @@ local function format_table (t, depth, l)
     end
 end
 
--- Formatting coroutine
+-------------------------------------------------------------------------------
+-- Coroutine formatting
 
 local function format_coroutine (value, depth, l)
     -- Formats a coroutine. Unfortunantly we cannot gather a lot of information
@@ -496,7 +502,8 @@ local function format_coroutine (value, depth, l)
     l[#l+1] = tostring(value):sub(9)
 end
 
--- Formatting primitive
+-------------------------------------------------------------------------------
+-- Primitive formatting
 
 local function format_primitive (value, depth, l)
     -- Error check
@@ -518,7 +525,7 @@ local TYPE_TO_FORMAT_FUNC = {
     ['cdata']    =  format_primitive,  -- TODO & Luajit only
 }
 
-function format_value (value, depth, l)
+local function format_value (value, depth, l)
     assert(type(depth) == 'number' and type(l) == 'table')
     local formatting = TYPE_TO_FORMAT_FUNC[type(value)]
     --print(value, formatting)