From: Aurelien DARRAGON <adarragon@haproxy.com>
Date: Thu, 28 Nov 2024 16:39:00 +0000 (+0100)
Subject: DOC: lua: prefer Patref:{set,add}() over legacy methods for acl and maps
X-Git-Tag: v3.2-dev1~66
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=e5acb031373a041269a8bb47a26a9f6c593b91f0;p=thirdparty%2Fhaproxy.git

DOC: lua: prefer Patref:{set,add}() over legacy methods for acl and maps

Patref:set() can achieve the same thing as core.set_map()
Patref:add() can achieve the same thing as core.add_acl()
Patref:del() can achieve the same thing as core.del_map() and
core.del_acl()

As a bonus, Patref:{set,add} are more efficient than their core
legacy equivalent, because they don't require systematic pattern
reference lookup for each individual operation.

Let's mention that in the doc to encourage Patref methods adoption.
---

diff --git a/doc/lua-api/index.rst b/doc/lua-api/index.rst
index 6ca26c7373..c16a07e6c7 100644
--- a/doc/lua-api/index.rst
+++ b/doc/lua-api/index.rst
@@ -360,6 +360,8 @@ Core class
 
 .. js:function:: core.add_acl(name, key)
 
+  **LEGACY**
+
   **context**: init, task, action, sample-fetch, converter
 
   Add the ACL *key* in the ACLs list referenced by *name*.
@@ -367,8 +369,14 @@ Core class
   :param string name: the name that reference the ACL entries.
   :param string key: the key which will be added.
 
+  .. Note::
+     This function is not optimal due to systematic Map reference lookup.
+     It is recommended to use :js:func:`Patref.add()` instead.
+
 .. js:function:: core.del_acl(name, key)
 
+  **LEGACY**
+
   **context**: init, task, action, sample-fetch, converter
 
   Delete the ACL entry referenced by the key *key* in the list of ACLs
@@ -377,8 +385,14 @@ Core class
   :param string name: the name that reference the ACL entries.
   :param string key: the key which will be deleted.
 
+  .. Note::
+     This function is not optimal due to systematic Map reference lookup.
+     It is recommended to use :js:func:`Patref.del()` instead.
+
 .. js:function:: core.del_map(name, key)
 
+  **LEGACY**
+
   **context**: init, task, action, sample-fetch, converter
 
   Delete the map entry indexed with the specified key in the list of maps
@@ -387,6 +401,10 @@ Core class
   :param string name: the name that reference the map entries.
   :param string key: the key which will be deleted.
 
+  .. Note::
+     This function is not optimal due to systematic Map reference lookup.
+     It is recommended to use :js:func:`Patref.del()` instead.
+
 .. js:function:: core.get_info()
 
   **context**: body, init, task, action, sample-fetch, converter
@@ -840,6 +858,8 @@ Core class
 
 .. js:function:: core.set_map(name, key, value)
 
+  **LEGACY**
+
   **context**: init, task, action, sample-fetch, converter
 
   Set the value *value* associated to the key *key* in the map referenced by
@@ -849,6 +869,10 @@ Core class
   :param string key: the key to set or replace
   :param string value: the associated value
 
+  .. Note::
+     This function is not optimal due to systematic Map reference lookup.
+     It is recommended to use :js:func:`Patref.set()` instead.
+
 .. js:function:: core.sleep(int seconds)
 
   **context**: task, action