Lua: add methods insert, remove, and sort to pandoc.List

The functions `table.insert`, `table.remove`, and `table.sort` are added
to pandoc.List elements.  They can be used as methods, e.g.

    local numbers = pandoc.List {2, 3, 1}
    numbers:sort()     -- numbers is now {1, 2, 3}

data/pandoc.List.lua

@@ -104,6 +104,12 @@ function List:includes (needle, init)
   return not (List.find(self, needle, init) == nil)
 end
 
+--- Insert an element into the list. Alias for `table.insert`.
+-- @param list list
+-- @param[opt] pos position at which the new element is to be inserted
+-- @param value value to insert
+List.insert = table.insert
+
 --- Returns a copy of the current list by applying the given function to
 -- all elements.
 -- @param fn function which is applied to all list items.
@@ -115,6 +121,17 @@ function List:map (fn)
   return res
 end
 
+--- Remove element from list (alias for `table.remove`)
+-- @param list list
+-- @param[opt] pos position of the element to be removed (default: #list)
+-- @return the removed element
+List.remove = table.remove
+
+--- Sort list in-place (alias for `table.sort`)
+-- @param list list
+-- @param[opt] comp comparison function; default to `<` operator.
+List.sort = table.sort
+
 -- Set metatable with __call metamethod. This allows the use of `List`
 -- as a constructor function.
 local ListMT = {

doc/lua-filters.md

@@ -2734,6 +2734,22 @@ methods and convenience functions.
     Returns: true if a list item is equal to the needle, false
     otherwise
 
+[`pandoc.List:insert ([pos], value)`]{#pandoc.list:insert}
+
+:   Inserts element `value` at position `pos` in list, shifting
+    elements to the next-greater indix if necessary.
+
+    This function is identical to
+    [`table.insert`](https://www.lua.org/manual/5.3/manual.html#6.6).
+
+    Parameters:
+
+    `pos`:
+    :   index of the new value; defaults to length of the list + 1
+
+    `value`:
+    :   value to insert into the list
+
 [`pandoc.List:map (fn)`]{#pandoc.list:map}
 
 :   Returns a copy of the current list by applying the given
@@ -2757,6 +2773,49 @@ methods and convenience functions.
 
     Returns: the updated input value
 
+[`pandoc.List:remove ([pos])`]{#pandoc.list:remove}
+
+:    Removes the element at position `pos`, returning the value
+     of the removed element.
+
+     This function is identical to
+     [`table.remove`](https://www.lua.org/manual/5.3/manual.html#6.6).
+
+    Parameters:
+
+    `pos`:
+    :   position of the list value that will be remove; defaults
+        to the index of the last element
+
+    Returns: the removed element
+
+[`pandoc.List:sort ([comp])`]{#pandoc.list:sort}
+
+:   Sorts list elements in a given order, in-place. If `comp` is
+    given, then it must be a function that receives two list
+    elements and returns true when the first element must come
+    before the second in the final order (so that, after the
+    sort, `i < j` implies `not comp(list[j],list[i]))`. If comp
+    is not given, then the standard Lua operator `<` is used
+    instead.
+
+    Note that the comp function must define a strict partial
+    order over the elements in the list; that is, it must be
+    asymmetric and transitive. Otherwise, no valid sort may be
+    possible.
+
+    The sort algorithm is not stable: elements considered equal
+    by the given order may have their relative positions changed
+    by the sort.
+
+    This function is identical to
+    [`table.sort`](https://www.lua.org/manual/5.3/manual.html#6.6).
+
+    Parameters:
+
+    `comp`:
+    :   Comparison function as described above.
+
 # Module pandoc.system
 
 Access to system information and functionality.

test/lua/module/pandoc-list.lua

@@ -15,33 +15,6 @@ return {
     end)
   },
 
-  group 'new' {
-    test('make table usable as list', function ()
-      local test = List:new{1, 1, 2, 3, 5}
-      assert.are_same(
-        {1, 1, 4, 9, 25},
-        test:map(function (x) return x^2 end)
-      )
-    end),
-    test('return empty list if no argument is given', function ()
-       assert.are_same({}, List:new())
-    end),
-    test('metatable of result is pandoc.List', function ()
-      local test = List:new{5}
-      assert.are_equal(List, getmetatable(test))
-    end)
-  },
-
-  group 'includes' {
-    test('finds elements in list', function ()
-      local lst = List:new {'one', 'two', 'three'}
-      assert.is_truthy(lst:includes('one'))
-      assert.is_truthy(lst:includes('two'))
-      assert.is_truthy(lst:includes('three'))
-      assert.is_falsy(lst:includes('four'))
-    end)
-  },
-
   group 'clone' {
     test('changing the clone does not affect original', function ()
       local orig = List:new {23, 42}
@@ -54,7 +27,25 @@ return {
       local orig = List:new {23, 42}
       assert.are_equal(List, getmetatable(orig:clone()))
     end),
-                },
+  },
+
+  group 'extend' {
+    test('extends list with other list', function ()
+      local primes = List:new {2, 3, 5, 7}
+      primes:extend {11, 13, 17}
+      assert.are_same({2, 3, 5, 7, 11, 13, 17}, primes)
+    end)
+  },
+
+  group 'filter' {
+    test('keep elements for which property is truthy', function ()
+      local is_small_prime = function (x)
+        return List.includes({2, 3, 5, 7}, x)
+      end
+      local numbers = List:new {4, 7, 2, 9, 5, 11}
+      assert.are_same({7, 2, 5}, numbers:filter(is_small_prime))
+    end),
+  },
 
   group 'find' {
     test('returns element and index if found', function ()
@@ -87,11 +78,26 @@ return {
     end),
   },
 
-  group 'extend' {
-    test('extends list with other list', function ()
-      local primes = List:new {2, 3, 5, 7}
-      primes:extend {11, 13, 17}
-      assert.are_same({2, 3, 5, 7, 11, 13, 17}, primes)
+  group 'includes' {
+    test('finds elements in list', function ()
+      local lst = List:new {'one', 'two', 'three'}
+      assert.is_truthy(lst:includes('one'))
+      assert.is_truthy(lst:includes('two'))
+      assert.is_truthy(lst:includes('three'))
+      assert.is_falsy(lst:includes('four'))
+    end)
+  },
+
+  group 'insert' {
+    test('insert value at end of list.', function ()
+      local count_norsk = List {'en', 'to', 'tre'}
+      count_norsk:insert('fire')
+      assert.are_same({'en', 'to', 'tre', 'fire'}, count_norsk)
+    end),
+    test('insert value in the middle of list.', function ()
+      local count_norsk = List {'fem', 'syv'}
+      count_norsk:insert(2, 'seks')
+      assert.are_same({'fem', 'seks', 'syv'}, count_norsk)
     end)
   },
 
@@ -108,13 +114,47 @@ return {
     end)
   },
 
-  group 'filter' {
-    test('keep elements for which property is truthy', function ()
-      local is_small_prime = function (x)
-        return List.includes({2, 3, 5, 7}, x)
-      end
-      local numbers = List:new {4, 7, 2, 9, 5, 11}
-      assert.are_same({7, 2, 5}, numbers:filter(is_small_prime))
+  group 'new' {
+    test('make table usable as list', function ()
+      local test = List:new{1, 1, 2, 3, 5}
+      assert.are_same(
+        {1, 1, 4, 9, 25},
+        test:map(function (x) return x^2 end)
+      )
     end),
+    test('return empty list if no argument is given', function ()
+       assert.are_same({}, List:new())
+    end),
+    test('metatable of result is pandoc.List', function ()
+      local test = List:new{5}
+      assert.are_equal(List, getmetatable(test))
+    end)
+  },
+
+  group 'remove' {
+    test('remove value at end of list.', function ()
+      local understand = List {'jeg', 'forstår', 'ikke'}
+      local norsk_not = understand:remove()
+      assert.are_same({'jeg', 'forstår'}, understand)
+      assert.are_equal('ikke', norsk_not)
+    end),
+    test('remove value at beginning of list.', function ()
+      local count_norsk = List {'en', 'to', 'tre'}
+      count_norsk:remove(1)
+      assert.are_same({'to', 'tre'}, count_norsk)
+    end)
+  },
+
+  group 'sort' {
+    test('sort numeric list', function ()
+      local numbers = List {71, 5, -1, 42, 23, 0, 1}
+      numbers:sort()
+      assert.are_same({-1, 0, 1, 5, 23, 42, 71}, numbers)
+    end),
+    test('reverse-sort numeric', function ()
+      local numbers = List {71, 5, -1, 42, 23, 0, 1}
+      numbers:sort(function (x, y) return x > y end)
+      assert.are_same({71, 42, 23, 5, 1, 0, -1}, numbers)
+    end)
   },
 }