diff --git a/docs/index.html b/docs/index.html index f6646370..587ccdc0 100644 --- a/docs/index.html +++ b/docs/index.html @@ -114,7 +114,7 @@

Examples

-

Penlight Lua Libraries 1.12.0

+

Penlight Lua Libraries 1.13.0

Penlight is a set of pure Lua libraries for making it easier to work with common tasks like iterating over directories, reading configuration files and the like. Provides functional operations on tables and sequences. Visit the GitHub project to review the code or file issues. Skip to the introduction.

Libraries

diff --git a/docs/libraries/pl.app.html b/docs/libraries/pl.app.html index 4417e8fc..737840bc 100644 --- a/docs/libraries/pl.app.html +++ b/docs/libraries/pl.app.html @@ -131,7 +131,7 @@

Functions

return the name of the current script running. - require_here (base) + require_here (base, nofollow) prefixes the current script's path to the Lua module path. @@ -181,7 +181,7 @@

Returns:

- require_here (base) + require_here (base, nofollow)
prefixes the current script's path to the Lua module path. @@ -200,6 +200,10 @@

Parameters:

string optional base directory (absolute, or relative path). +
  • nofollow + bool + always use the invocation's directory, even if the invoked file is a symlink +

    • Returns:

    diff --git a/docs/libraries/pl.tablex.html b/docs/libraries/pl.tablex.html index 2e070805..f9e82d07 100644 --- a/docs/libraries/pl.tablex.html +++ b/docs/libraries/pl.tablex.html @@ -1794,7 +1794,7 @@

    Parameters:

    @@ -1815,7 +1815,7 @@

    Parameters:

    diff --git a/docs/libraries/pl.utils.html b/docs/libraries/pl.utils.html index 2870781e..678907bb 100644 --- a/docs/libraries/pl.utils.html +++ b/docs/libraries/pl.utils.html @@ -170,6 +170,10 @@

    Functions

    npairs (t[, i_start=1[, i_end=t.n or #t[, step=1]]]) an iterator with indices, similar to ipairs, but with a range. + + kpairs (t) + an iterator over all non-integer keys (inverse of ipairs). +

    Tables

    @@ -190,7 +194,7 @@

    Error handling

    - + @@ -606,6 +610,63 @@

    Usage:

    -- t = { n = 3, [2] = "123", [3] = "nil" } + +
    + + kpairs (t) +
    +
    + an iterator over all non-integer keys (inverse of ipairs). + It will skip any key that is an integer number, so negative indices or an + array with holes will not return those either (so it returns slightly less than + 'the inverse of ipairs').

    + +

    This uses pairs under the hood, so any value that is iterable using pairs + will work with this function. + + +

    Parameters:

    +
      +
    • t + table + the table to iterate over +
      • +
    + +

    Returns:

    +
      +
    1. + key + + +
      2. +
    2. + value + + +
      3. +
    + + + +

    Usage:

    +
      + 
      local t = {
+  "hello",
+  "world",
+  hello = "hallo",
+  world = "Welt",
+}
+
+for k, v in utils.kpairs(t) do
+  print("German: ", v)
+end
+
+-- output;
+-- German: hallo
+-- German: Welt
      +
    +

    Tables

    @@ -726,34 +787,38 @@

    Usage:

    enum (...)
    - creates an Enum table. + creates an Enum or constants lookup table for improved error handling. This helps prevent magic strings in code by throwing errors for accessing - non-existing values.

    + non-existing values, and/or converting strings/identifiers to other values.

    -

    Calling on the object does the same, but returns a soft error; nil + err.

    +

    Calling on the object does the same, but returns a soft error; nil + err, if + the call is succesful (the key exists), it will return the value.

    -

    The values are equal to the keys. The enum object is - read-only. +

    When calling with varargs or an array the values will be equal to the keys. + The enum object is read-only.

    Parameters:

    • ... - strings that make up the enumeration. + table or vararg + the input for the Enum. If varargs or an array then the + values in the Enum will be equal to the names (must be strings), if a hash-table + then values remain (any type), and the keys must be strings.

    Returns:

      - Enum object + Enum object (read-only table/object)

    Usage:

      - 
    • -- accessing at runtime
+        
    • -- Enum access at runtime
 local obj = {}
 obj.MOVEMENT = utils.enum("FORWARD", "REVERSE", "LEFT", "RIGHT")
 
@@ -765,12 +830,40 @@ 
      Usage:
      
   -- "'REVERES' is not a valid value (expected one of: 'FORWARD', 'REVERSE', 'LEFT', 'RIGHT')"
 
 end
      • 
-        
    • -- validating user-input
-local parameter = "...some user provided option..."
-local ok, err = obj.MOVEMENT(parameter) -- calling on the object
-if not ok then
-  print("bad 'parameter', " .. err)
-  os.exit(1)
+        
    • -- standardized error codes
+local obj = {
+  ERR = utils.enum {
+    NOT_FOUND = "the item was not found",
+    OUT_OF_BOUNDS = "the index is outside the allowed range"
+  },
+
+  some_method = function(self)
+    return self.ERR.OUT_OF_BOUNDS
+  end,
+}
+
+local result, err = obj:some_method()
+if not result then
+  if err == obj.ERR.NOT_FOUND then
+    -- check on error code, not magic strings
+
+  else
+    -- return the error description, contained in the constant
+    return nil, "error: "..err  -- "error: the index is outside the allowed range"
+  end
+end
      • 
+        
    • -- validating/converting user-input
+local color = "purple"
+local ansi_colors = utils.enum {
+  black     = 30,
+  red       = 31,
+  green     = 32,
+}
+local color_code, err = ansi_colors(color) -- calling on the object, returns the value from the enum
+if not color_code then
+  print("bad 'color', " .. err)
+  -- "bad 'color', 'purple' is not a valid value (expected one of: 'black', 'red', 'green')"
+  os.exit(1)
 end
      •
    enum (...)creates an Enum table.creates an Enum or constants lookup table for improved error handling.
    function_arg (idx, f, msg)