MINOR: hlua: add core.get_patref method

core.get_patref() method may be used to get a reference to a pattern
object (pat_ref struct which is used for maps and acl storage) from
Lua by providing the reference name (filename for files, or prefix+name
for opt or virtual pattern references).

Lua documentation was updated.

doc/lua-api/index.rst

@@ -348,6 +348,16 @@ Core class
   end
 ..
 
+.. js:function:: core.get_patref(name)
+
+  **context**: init, task, action, sample-fetch, converter
+
+  Find the pattern object *name* used by HAProxy. It corresponds to the
+  generic pattern reference used to handle both ACL ands Maps.
+
+  :param string name: reference name
+  :returns: A :ref:`patref_class` object.
+
 .. js:function:: core.add_acl(name, key)
 
   **context**: init, task, action, sample-fetch, converter
@@ -3412,6 +3422,27 @@ Map class
   :param string str: Is the string used as key.
   :returns: a string containing the result or empty string if no match.
 
+.. _patref_class:
+
+Patref class
+=================
+
+.. js:class:: Patref
+
+  Patref object corresponds to the internal HAProxy pat_ref element which
+  is used to store ACL and MAP elements. It is identified by its name
+  (reference) which often is a filename, unless it is prefixed by 'virt@'
+  for virtual references or 'opt@' for references that don't necessarily
+  point to real file. From Lua, :ref:`patref_class` object may be used to
+  directly manipulate existing pattern reference storage.
+
+  Patref object is obtained using the :js:func:`core.get_patref()`
+  function
+
+.. js:function:: Patref.get_name(ref)
+
+  :returns: the name of the pattern reference object.
+
 .. _applethttp_class:
 
 AppletHTTP class

src/hlua.c

@@ -2301,6 +2301,28 @@ static int hlua_set_map(lua_State *L)
 	return 0;
 }
 
+/* This function is an LUA binding. It provides a function
+ * for retrieving a patref object from a reference name
+ */
+static int hlua_get_patref(lua_State *L)
+{
+	const char *name;
+	struct pat_ref *ref;
+
+	MAY_LJMP(check_args(L, 1, "get_patref"));
+
+	name = MAY_LJMP(luaL_checkstring(L, 1));
+
+	ref = pat_ref_lookup(name);
+	if (!ref)
+		WILL_LJMP(luaL_error(L, "'get_patref': unknown pattern reference '%s'", name));
+
+	/* push the existing patref object on the stack */
+	MAY_LJMP(hlua_fcn_new_patref(L, ref));
+
+	return 1;
+}
+
 /* This function is an LUA binding. It provides a function
  * for retrieving a var from the proc scope in core.
  */
@@ -13782,6 +13804,7 @@ lua_State *hlua_init_state(int thread_num)
 	hlua_class_function(L, "del_acl", hlua_del_acl);
 	hlua_class_function(L, "set_map", hlua_set_map);
 	hlua_class_function(L, "del_map", hlua_del_map);
+	hlua_class_function(L, "get_patref", hlua_get_patref);
 	hlua_class_function(L, "get_var", hlua_core_get_var);
 	hlua_class_function(L, "tcp", hlua_socket_new);
 	hlua_class_function(L, "httpclient", hlua_httpclient_new);