update CHANGES and use classmod for classes

CHANGES.md

@@ -1,3 +1,29 @@
+## 1.3.0
+
+### Changes
+
+  - class: RIP base method - not possible to implement correctly
+  - lapp: short flags can now always be followed directly by their value, for instance,
+`-I/usr/include/lua/5.1`
+  - Date: new explicit `Date.Interval` class; `toUTC/toLocal` return new object; `Date.__tostring`
+always returns ISO 8601 times for exact serialization.  `+/-` explicit operators. Date objects
+are explicitly flagged as being UTC or not.
+
+### Fixes
+
+  - class: super method fixed.
+  - Date: DST is now accounted for properly.
+  - Date: weekday calculation borked.
+
+### Features
+
+  - All tests pass with no-5.1-compatible Lua 5.2; now always uses `utils.load` and
+`utils.unpack` is always available.
+  - types: new module containing `utils.is_xxx` methods plus new `to_bool`.
+  - class: can be passed methods in a table (see `test=klass.lua`). This is
+particularly convenient for using from Moonscript.
+  - general documentation improvements, e.g `class`
+
 ## 1.2.1
 
 ### Changes
@@ -18,7 +44,7 @@
   - 5.2 compatible load now respects mode
   - tablex.difference thought that a value of `false` meant 'not present' (Andrew Starke)
 
-## Features
+### Features
 
   - tablex.sort(t) iterates over sorted keys, tablex.sortv(t) iterates over sorted values (Pete Kazmier)
   - tablex.readonly(t) creates a read-only proxy for a table (John Schember)

lua/pl/Date.lua

@@ -2,7 +2,7 @@
 -- See  @{05-dates.md|the Guide}.
 --
 -- Dependencies: `pl.class`, `pl.stringx`
--- @module pl.Date
+-- @classmod pl.Date
 -- @pragma nostrip
 
 local class = require 'pl.class'

lua/pl/List.lua

@@ -15,7 +15,7 @@
 -- Written for Lua version Nick Trout 4.0; Redone for Lua 5.1, Steve Donovan.
 --
 -- Dependencies: `pl.utils`, `pl.tablex`
--- @module pl.List
+-- @classmod pl.List
 -- @pragma nostrip
 
 local tinsert,tremove,concat,tsort = table.insert,table.remove,table.concat,table.sort
@@ -328,6 +328,7 @@ function List:slice_assign(i1,i2,seq)
 end
 
 --- concatenation operator.
+-- @within metamethods
 -- @param L another List
 -- @return a new list consisting of the list with the elements of the new list appended
 function List:__concat(L)
@@ -338,6 +339,7 @@ function List:__concat(L)
 end
 
 --- equality operator ==.  True iff all elements of two lists are equal.
+-- @within metamethods
 -- @param L another List
 -- @return true or false
 function List:__eq(L)
@@ -375,6 +377,7 @@ local function tostring_q(val)
 end
 
 --- how our list should be rendered as a string. Uses join().
+-- @within metamethods
 -- @see List:join
 function List:__tostring()
     return '{'..self:join(',',tostring_q)..'}'

lua/pl/Map.lua

@@ -7,7 +7,7 @@
 --    true
 --
 -- Dependencies: `pl.utils`, `pl.class`, `pl.tablex`, `pl.pretty`
--- @module pl.Map
+-- @classmod pl.Map
 
 local tablex = require 'pl.tablex'
 local utils = require 'pl.utils'
@@ -100,11 +100,16 @@ end
 -- @function Map:update
 Map.update = tablex.update
 
+--- equality between maps.
+-- @within metamethods
+-- @param m another map.
 function Map:__eq (m)
     -- note we explicitly ask deepcompare _not_ to use __eq!
     return deepcompare(self,m,true)
 end
 
+--- string representation of a map.
+-- @within metamethods
 function Map:__tostring ()
     return pretty_write(self,'')
 end

lua/pl/MultiMap.lua

@@ -1,7 +1,7 @@
 --- MultiMap, a Map which has multiple values per key.
 --
 -- Dependencies: `pl.utils`, `pl.class`, `pl.tablex`, `pl.List`
--- @module pl.MultiMap
+-- @classmod pl.MultiMap
 
 local classes = require 'pl.class'
 local tablex = require 'pl.tablex'

lua/pl/OrderedMap.lua

@@ -3,7 +3,7 @@
 -- Derived from `pl.Map`.
 --
 -- Dependencies: `pl.utils`, `pl.tablex`, `pl.List`
--- @module pl.OrderedMap
+-- @classmod pl.OrderedMap
 
 local tablex = require 'pl.tablex'
 local utils = require 'pl.utils'
@@ -140,8 +140,13 @@ function OrderedMap:iter ()
     end
 end
 
+--- iterate over an ordered map (5.2).
+-- @within metamethods
+-- @function OrderedMap:__pairs
 OrderedMap.__pairs = OrderedMap.iter
 
+--- string representation of an ordered map.
+-- @within metamethods
 function OrderedMap:__tostring ()
     local res = {}
     for i,v in ipairs(self._keys) do

lua/pl/Set.lua

@@ -17,7 +17,7 @@
 --     [orange]
 --
 -- Depdencies: `pl.utils`, `pl.tablex`, `pl.class`, (`pl.List` if __tostring is used)
--- @module pl.Set
+-- @classmod pl.Set
 
 local tablex = require 'pl.tablex'
 local utils = require 'pl.utils'
@@ -52,6 +52,8 @@ function Set:_init (t)
     end
 end
 
+--- string representation of a set.
+-- @within metamethods
 function Set:__tostring ()
     return '['..concat(array_tostring(Set.values(self)),',')..']'
 end
@@ -82,6 +84,10 @@ end
 function Set.union (self,set)
     return merge(self,set,true)
 end
+
+--- union of sets.
+-- @within metamethods
+-- @function Set.__add
 Set.__add = Set.union
 
 --- intersection of two sets (also *).
@@ -91,6 +97,10 @@ Set.__add = Set.union
 function Set.intersection (self,set)
     return merge(self,set,false)
 end
+
+--- intersection of sets.
+-- @within metamethods
+-- @function Set.__mul
 Set.__mul = Set.intersection
 
 --- new set with elements in the set that are not in the other (also -).
@@ -100,6 +110,11 @@ Set.__mul = Set.intersection
 function Set.difference (self,set)
     return difference(self,set,false)
 end
+
+
+--- difference of sets.
+-- @within metamethods
+-- @function Set.__sub
 Set.__sub = Set.difference
 
 -- a new set with elements in _either_ the set _or_ other but not both (also ^).
@@ -109,6 +124,10 @@ Set.__sub = Set.difference
 function Set.symmetric_difference (self,set)
     return difference(self,set,true)
 end
+
+--- symmetric difference of sets.
+-- @within metamethods
+-- @function Set.__pow
 Set.__pow = Set.symmetric_difference
 
 --- is the first set a subset of the second (also <)?.
@@ -121,6 +140,10 @@ function Set.issubset (self,set)
     end
     return true
 end
+
+--- first set subset of second?
+-- @within metamethods
+-- @function Set.__lt
 Set.__lt = Set.issubset
 
 --- is the set empty?.
@@ -145,8 +168,13 @@ end
 -- @function Set.len
 Set.len = tablex.size
 
+--- cardinality of set (5.2).
+-- @within metamethods
+-- @function Set.__len
 Set.__len = Set.len
 
+--- equality between sets.
+-- @within metamethods
 function Set.__eq (s1,s2)
     return Set.issubset(s1,s2) and Set.issubset(s2,s1)
 end

lua/pl/app.lua

@@ -95,11 +95,11 @@ function app.lua ()
 end
 
 --- parse command-line arguments into flags and parameters.
--- Understands GNU-style command-line flags; short (-f) and long (--flag).
--- These may be given a value with either '=' or ':' (-k:2,--alpha=3.2,-n2);
+-- Understands GNU-style command-line flags; short (`-f`) and long (`--flag`).
+-- These may be given a value with either '=' or ':' (`-k:2`,`--alpha=3.2`,`-n2`);
 -- note that a number value can be given without a space.
--- Multiple short args can be combined like so: (-abcd).
--- @param args an array of strings (default is the global 'arg')
+-- Multiple short args can be combined like so: ( `-abcd`).
+-- @param args an array of strings (default is the global `arg`)
 -- @param flags_with_values any flags that take values, e.g. <code>{out=true}</code>
 -- @return a table of flags (flag=value pairs)
 -- @return an array of parameters