expose LPeg patterns

Signed-off-by: Asbjørn Sloth Tønnesen <ast@2e8.dk>

1 files changed, 24 insertions, 0 deletions

diff --git a/README.rst b/README.rst
index 207b1d9..b227b1a 100644
--- a/README.rst
+++ b/README.rst
@@ -76,6 +76,7 @@ API                     Description
 ``inet.is_set(foo)``    is ``set`` table?
 ``inet.set()``          get new empty ``set`` instance.
 ``inet.mixed_networks`` IPv6 mixed notation ``set``
+``inet.lpeg``           LPeg_ patterns
 ``inet.version``        API version (currently ``1``)
 ======================= =====================================================
 
@@ -188,6 +189,29 @@ There is a multitude of different ways to create ``inet*`` instances.
   inet('192.0.2.0', 33)     -- returns nil, 'invalid mask'
   inet('2001:db8::', 129)   -- returns nil, 'invalid mask'
 
+Usable in LPeg patterns
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Internally ``inet`` uses LPeg_ to parse IP adresses, but the
+LPeg patterns are also available for embedding into your
+own LPeg patterns.
+
+::
+
+  local lpeg = require 'lpeg'
+  local P = lpeg.P
+  local http_host_v6 = P('[') * inet.lpeg.ipv6 * P(']')
+  local http_host = http_host_v6 + inet.lpeg.ipv4
+  local my_http_uri = P('https://') * http_host * P('/') * -1
+
+  my_http_uri:match('https://192.0.2.0/')     -- returns inet('192.0.2.0')
+  my_http_uri:match('https://[2001:db8::1]/') -- returns inet('2001:db8::1')
+
+  inet.lpeg.ipv6:match('2001:db8::/64')       -- returns inet('2001:db8::/64')
+  inet.lpeg.ipv4:match('192.0.2.0/24')        -- returns inet('192.0.2.0/24')
+  inet.lpeg.ip:match('2001:db8::/64')         -- returns inet('2001:db8::/64')
+  inet.lpeg.ip:match('192.0.2.0/24')          -- returns inet('192.0.2.0/24')
+
 Mangling
 --------