From e5acb031373a041269a8bb47a26a9f6c593b91f0 Mon Sep 17 00:00:00 2001 From: Aurelien DARRAGON Date: Thu, 28 Nov 2024 17:39:00 +0100 Subject: [PATCH] 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. --- doc/lua-api/index.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/doc/lua-api/index.rst b/doc/lua-api/index.rst index 6ca26c737..c16a07e6c 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