From dbb4eb38c96972c6a14eba5b31bbbaaecc889adc Mon Sep 17 00:00:00 2001 From: Berwyn Hoyt Date: Mon, 15 Jul 2024 21:51:22 +1000 Subject: [PATCH] Add @deprecated tag to relevant functions --- docs/config/main.ld | 13 ++++- docs/config/private.ld | 13 ++++- docs/config/ydb.ld | 13 ++++- docs/yottadb.html | 117 +++++++++++++++++++++++++++++++---------- yottadb.h | 10 +++- yottadb.lua | 12 +++++ 6 files changed, 147 insertions(+), 31 deletions(-) diff --git a/docs/config/main.ld b/docs/config/main.ld index 15604ed..0588e67 100644 --- a/docs/config/main.ld +++ b/docs/config/main.ld @@ -14,5 +14,16 @@ sort = true --readme = 'README.md' -- ldoc's rendering isn't very pretty so instead link to README.md on github --examples = 'examples' -- ldoc doesn't support .ci and .m files so examples are instead links to github +-- format @deprecated tag +custom_display_name_handler = function(item, default_handler) + if item.tags.deprecated then + return default_handler(item) .. (' [deprecated %s]:'):format(item.tags.deprecated[1]) + end + return default_handler(item) +end + alias('example', 'usage') -custom_tags = {{'invocation', title='Invocation', hidden=true}} +custom_tags = { + {'invocation', title='Invocation', hidden=true}, + {'deprecated', title='Deprecated', hidden=true}, +} diff --git a/docs/config/private.ld b/docs/config/private.ld index dc009c6..e74101c 100644 --- a/docs/config/private.ld +++ b/docs/config/private.ld @@ -15,5 +15,16 @@ merge = true --readme = 'README.md' -- ldoc's rendering isn't very pretty so instead link to README.md on github --examples = 'examples' -- ldoc doesn't support .ci and .m files so examples are instead links to github +-- format @deprecated tag +custom_display_name_handler = function(item, default_handler) + if item.tags.deprecated then + return default_handler(item) .. (' [deprecated %s]:'):format(item.tags.deprecated[1]) + end + return default_handler(item) +end + alias('example', 'usage') -custom_tags = {{'invocation', title='Invocation', hidden=true}} +custom_tags = { + {'invocation', title='Invocation', hidden=true}, + {'deprecated', title='Deprecated', hidden=true}, +} diff --git a/docs/config/ydb.ld b/docs/config/ydb.ld index 6ca2969..75a945b 100644 --- a/docs/config/ydb.ld +++ b/docs/config/ydb.ld @@ -15,5 +15,16 @@ backtick_references = true format = 'markdown' sort = true +-- format @deprecated tag +custom_display_name_handler = function(item, default_handler) + if item.tags.deprecated then + return default_handler(item) .. (' [deprecated %s]:'):format(item.tags.deprecated[1]) + end + return default_handler(item) +end + alias('example', 'usage') -custom_tags = {{'invocation', title='Invocation', hidden=true}} +custom_tags = { + {'invocation', title='Invocation', hidden=true}, + {'deprecated', title='Deprecated', hidden=true}, +} diff --git a/docs/yottadb.html b/docs/yottadb.html index b8c6360..e14b8d1 100644 --- a/docs/yottadb.html +++ b/docs/yottadb.html @@ -38,8 +38,8 @@

Contents

  • Basic low level functions
  • block_M_signals (bool)
  • data (varname[, subsarray[, ...]])
    • -
  • delete_node (varname[, subsarray[, ...]])
    • -
  • delete_tree (varname[, subsarray[, ...]])
    • +
  • delete_node (varname[, subsarray[, ...]]) [deprecated v3.0]:
    • +
  • delete_tree (varname[, subsarray[, ...]]) [deprecated v3.0]:
  • get (varname[, subsarray[, ...]])
  • get_error_code (message)
  • grab (varname[, subsarray[, ...[, timeout]]])
    • @@ -79,7 +79,7 @@

    Contents

  • node:__ipairs ()
  • node:__pairs ([reverse])
  • node:__repr ()
    • -
  • node:delete_tree ()
    • +
  • node:delete_tree () [deprecated v3.0]:
  • node:dump ([maxlines=30])
  • node:get ([default])
  • node:gettree ([maxdepth[, filter[, _value[, _depth]]]])
    • @@ -105,12 +105,12 @@

    Contents

  • node:varname ()

  • Key class
    • -
  • _property_
    • -
  • key (varname[, subsarray])
    • -
  • key:delete_node ()
    • -
  • key:subscript_next ([reset[, reverse]])
    • -
  • key:subscript_previous ([reset])
    • -
  • key:subscripts ([reverse])
    • +
  • _property_ [deprecated v1.0]:
    • +
  • key (varname[, subsarray]) [deprecated v1.0]:
    • +
  • key:delete_node () [deprecated v1.0]:
    • +
  • key:subscript_next ([reset[, reverse]]) [deprecated v1.0]:
    • +
  • key:subscript_previous ([reset]) [deprecated v1.0]:
    • +
  • key:subscripts ([reverse]) [deprecated v1.0]:
    • @@ -138,11 +138,11 @@

    Basic low level functions

    Return whether a node has a value or subtree. - delete_node (varname[, subsarray[, ...]]) + delete_node (varname[, subsarray[, ...]]) [deprecated v3.0]: Deprecated and replaced by set(varname[, subsarray[, ...]], nil). - delete_tree (varname[, subsarray[, ...]]) + delete_tree (varname[, subsarray[, ...]]) [deprecated v3.0]: Deprecated and replaced by kill. @@ -282,7 +282,7 @@

    Node class

    Return raw representation of node's unique memory address. - node:delete_tree () + node:delete_tree () [deprecated v3.0]: Deprecated and replaced by kill. @@ -376,27 +376,27 @@

    Node class properties

    Key class

    - + - + - + - + - + - +
    _property__property_ [deprecated v1.0]: Properties of key object that are accessed with a dot.
    key (varname[, subsarray])key (varname[, subsarray]) [deprecated v1.0]: Creates an object that represents a YDB node; deprecated after v0.1.
    key:delete_node ()key:delete_node () [deprecated v1.0]: Deprecated way to delete database node value pointed to by node object.
    key:subscript_next ([reset[, reverse]])key:subscript_next ([reset[, reverse]]) [deprecated v1.0]: Deprecated way to get next sibling subscript.
    key:subscript_previous ([reset])key:subscript_previous ([reset]) [deprecated v1.0]: Deprecated way to get previous sibling subscript.
    key:subscripts ([reverse])key:subscripts ([reverse]) [deprecated v1.0]: Deprecated way to get same-level subscripts from this node onward.
    @@ -433,6 +433,7 @@

    Basic low le 2020s x86_64 CPU; see make benchmarks) +

    Parameters:

    Parameters:

    @@ -505,11 +507,12 @@

    Example:

    - delete_node (varname[, subsarray[, ...]]) + delete_node (varname[, subsarray[, ...]]) [deprecated v3.0]:
    Deprecated and replaced by set(varname[, subsarray[, ...]], nil). +

    Parameters:

    @@ -542,11 +545,12 @@

    Example:

    - delete_tree (varname[, subsarray[, ...]]) + delete_tree (varname[, subsarray[, ...]]) [deprecated v3.0]:
    Deprecated and replaced by kill. +

    Parameters:

    @@ -580,6 +584,7 @@

    See also:

    Gets and returns the value of a database variable or node; or nil if the variable or node does not exist. +

    Parameters:

    @@ -624,6 +629,7 @@

    Example:

    Get the YDB error code (if any) contained in the given error message. +

    Parameters:

    @@ -665,6 +671,7 @@

    Example:

    Otherwise lock_incr cannot tell whether it is a subscript or a timeout. +

    Parameters:

    +

    Parameters:

    +

    Parameters:

    Parameters:

    @@ -846,6 +856,7 @@

    Example:

    Raises an error yottadb.YDB_LOCK_TIMEOUT if a lock could not be acquired. +

    Parameters:

    +

    Parameters:

    +

    Parameters:

    +

    Parameters:

    +

    Parameters:

    +

    Parameters:

    Parameters:

    @@ -1163,6 +1180,7 @@

    Example:

    Returns the zwrite-formatted version of the given string. +

    Parameters:

    @@ -1198,6 +1216,7 @@

    Example:

    Returns the next subscript for a database variable or node; or nil if there isn't one. +

    Parameters:

    @@ -1242,6 +1261,7 @@

    Example:

    Returns the previous subscript for a database variable or node; or nil if there isn't one. +

    Parameters:

    @@ -1293,6 +1313,7 @@

    Example:

    and which you may consider to be preferable. +

    Parameters:

    +

    Returns:

    @@ -1356,6 +1378,7 @@

    See also:

    Returns the string described by the given zwrite-formatted string. +

    Parameters:

    @@ -1401,6 +1424,7 @@

    Transactions

    Restarts are subject to $ZMAXTPTIME after which they cause error %YDB-E-TPTIMEOUT +

    Parameters:

    +

    Parameters:

    + @@ -1604,6 +1630,7 @@

    Example:

    Make the currently running transaction function rollback immediately with a YDBTPROLLBACK error. + @@ -1622,6 +1649,7 @@

    High level functi
    Dump the specified node tree. +

    Parameters:

    @@ -1664,6 +1692,7 @@

    Examples:

    and matching M file arithmetic.m. +

    Parameters:

      @@ -1713,6 +1742,7 @@

      Node class opera explanation in the README.

    +

    Parameters:

      @@ -1761,6 +1791,7 @@

      Example:

      Tests whether object is a node object or inherits from a node object. +

    Parameters:

    @@ -1808,6 +1839,7 @@

    Returns:

    +

    Parameters:

    @@ -1872,6 +1904,7 @@

    Node class

    Alternatives using pairs() are as follows: + @@ -1914,6 +1947,7 @@

    Examples:

    +

    Parameters:

    @@ -1951,6 +1985,7 @@

    Example:

    Return raw representation of node's unique memory address. +

    Returns:

    @@ -1965,12 +2000,13 @@

    Returns:

    - node:delete_tree () + node:delete_tree () [deprecated v3.0]:
    Deprecated and replaced by kill. + @@ -1989,6 +2025,7 @@

    See also:

    Dump the specified node tree. +

    Parameters:

    @@ -2019,6 +2056,7 @@

    Returns:

    If node is subclassed, then node.__ invokes the subclass's node:__get() if it exists. +

    Parameters:

      @@ -2058,6 +2096,7 @@

      See also:

    +

    Parameters:

    @@ -2134,6 +2173,7 @@

    Example:

    If timeout is not supplied or is nil, wait forever; timeout of zero means try only once. +

    Parameters:

      @@ -2161,6 +2201,7 @@

      See also:

      Increment node's value. +

    Parameters:

    @@ -2193,6 +2234,7 @@

    See also:

    Delete database tree (node and subnodes) pointed to by node object. + @@ -2214,6 +2256,7 @@

    See also:

    If timeout is not supplied or is nil, wait forever; timeout of zero means try only once. +

    Parameters:

      @@ -2240,6 +2283,7 @@

      See also:

      Decrements a lock matching this node, releasing it if zero.
    + @@ -2263,6 +2307,7 @@

    See also:

    If timeout is not supplied or is nil, wait forever; timeout of zero means try only once. +

    Parameters:

      @@ -2291,6 +2336,7 @@

      See also:

      Alias for node:lock_decr to decrement a lock matching this node, releasing it if zero.
    + @@ -2314,6 +2360,7 @@

    See also:

    If node is subclassed, then node.__ = x invokes the subclass's node:__set(x) if it exists. +

    Parameters:

      @@ -2349,6 +2396,7 @@

      See also:

      +

    Parameters:

    @@ -2413,6 +2461,7 @@

    Examples:

    Note that subscripts() order is guaranteed to equal the M collation sequence. +

    Parameters:

      @@ -2454,6 +2503,7 @@

      Node class prope Fetch the 'data' bitfield of the node that describes whether the node has a data value or subtrees.

    +

    Returns:

    @@ -2477,6 +2527,7 @@

    Returns:

    Fetch the depth of the node: how many subscripts it has. + @@ -2492,6 +2543,7 @@

    Returns:

    Return true if the node has a tree; otherwise false. + @@ -2507,6 +2559,7 @@

    Returns:

    Return true if the node has a value; otherwise false. + @@ -2522,6 +2575,7 @@

    Returns:

    Return true if the node is mutable; otherwise false. + @@ -2537,6 +2591,7 @@

    Returns:

    Fetch the name of the node: the rightmost subscript. + @@ -2552,6 +2607,7 @@

    Returns:

    Return node's subsarray of subscript strings as a table. + @@ -2567,6 +2623,7 @@

    Returns:

    Fetch the varname of the node: the leftmost subscript. + @@ -2580,7 +2637,7 @@

    Key class

    - _property_ + _property_ [deprecated v1.0]:
    Properties of key object that are accessed with a dot. @@ -2590,6 +2647,7 @@

    Key class

    For example, access data property with: key.data +

    Fields:

      @@ -2623,7 +2681,7 @@

      Fields:

    - key (varname[, subsarray]) + key (varname[, subsarray]) [deprecated v1.0]:
    @@ -2643,6 +2701,7 @@

    Fields:

    +

    Parameters:

    @@ -2672,13 +2731,14 @@

    See also:

    - key:delete_node () + key:delete_node () [deprecated v1.0]:
    Deprecated way to delete database node value pointed to by node object. Prefer node:set(nil) + @@ -2693,7 +2753,7 @@

    See also:

    - key:subscript_next ([reset[, reverse]]) + key:subscript_next ([reset[, reverse]]) [deprecated v1.0]:
    @@ -2710,6 +2770,7 @@

    See also:

    +

    Parameters:

    @@ -2736,13 +2797,14 @@

    See also:

    - key:subscript_previous ([reset]) + key:subscript_previous ([reset]) [deprecated v1.0]:
    Deprecated way to get previous sibling subscript. See notes for subscript_previous() +

    Parameters:

      @@ -2765,7 +2827,7 @@

      See also:

    - key:subscripts ([reverse]) + key:subscripts ([reverse]) [deprecated v1.0]:
    @@ -2778,6 +2840,7 @@

    See also:

    +

    Parameters:

    diff --git a/yottadb.h b/yottadb.h index 03aacf8..8ea8c84 100644 --- a/yottadb.h +++ b/yottadb.h @@ -4,7 +4,15 @@ #define LUA_YOTTADB_H /* Version History -v3.0 Breaking change to lock() and lock_incr() which now wait forever with nil timeout, like the M LOCK command +v3.0 Introduce inheritable nodes using yottadb.inherit() + - Update examples/startup.lua to properly detect inherited nodes + - Breaking change to lock() and lock_incr() which now wait forever with nil timeout, like the M LOCK command + - Docs: + - Document `yottadb.inherit()` + - Update documentation with new node methods: `kill`, `grab`, `release`, and `__repr`. + - Add @deprecated tag per "Lua Language Server", compatible with Ldoc + - Fix makefile to build YDBDoc against the current directory's docs. + - Other minor documentation improvements. v2.2 First version to generate YDB docs for inclusion into Lua section of official YDB manual v2.1 Additional 3.6x speed improvement on node creation (now 47x v1.x) - PR #26 - Bugfix: yottadb.set(node, nil) now returns nil like its docs say it should diff --git a/yottadb.lua b/yottadb.lua index 2311dde..b3b867c 100644 --- a/yottadb.lua +++ b/yottadb.lua @@ -185,6 +185,7 @@ local node = {} -- Deprecated object that represents a YDB node. -- old name of YDB node object -- retains the deprecated syntax for backward compatibility +--- @deprecated v1.0 local key = {} --- Return whether a node has a value or subtree. @@ -213,6 +214,7 @@ M.data = _yottadb.data -- @param varname String of the database node (this can also be replaced by cachearray) -- @param[opt] subsarray Table of subscripts -- @param[opt] ... List of subscripts to append after any elements in optional subsarray table +--- @deprecated v3.0 -- @example -- ydb = require('yottadb') -- ydb.set('^Population', {'Belgium'}, 1367000) @@ -249,6 +251,7 @@ end -- @param[opt] subsarray Table of subscripts -- @param[opt] ... List of subscripts to append after any elements in optional subsarray table -- @see kill +--- @deprecated v3.0 M.delete_tree = M.kill --- Gets and returns the value of a database variable or node; or `nil` if the variable or node does not exist. @@ -980,6 +983,7 @@ function node:kill() return M.kill(self) end --- Deprecated and replaced by kill. -- @function node:delete_tree -- @see kill +--- @deprecated v3.0 node.delete_tree = node.kill --- Increment `node`'s value. @@ -1465,6 +1469,7 @@ end -- @param[opt] subsarray list of subscripts or table subscripts -- @return key object of the specified node with metatable `yottadb._key` -- @see node +--- @deprecated v1.0 function M.key(...) assert_type(..., 'string', 1, "key") assert_type(select(2, ...), _table_nil, 2, "key") @@ -1500,6 +1505,7 @@ for k, v in pairs(node) do key[k]=v if string.sub(k,1,2)~='__' then key['__'.. -- @field value equivalent to `node.__` -- @field __varname database variable name string -- for compatibility with a previous version -- @field __subsarray table array of database subscript name strings -- for compatibility with a previous version +--- @deprecated v1.0 key_properties = { name = key.name, -- equivalent to node::name() data = key.data, -- :name() @@ -1519,6 +1525,7 @@ local key_values = {} -- Simulate node attribute storage using another table of -- key[k] (i.e. look up in class named 'key' -- finds key.get, key.__call, etc.) -- if nothing found, returns `nil` -- @param k Node attribute to look up +--- @deprecated v1.0 function key:__index(k) local value_table = key_values[self] if value_table then @@ -1532,6 +1539,7 @@ end -- Sets dbase node value if k is 'value'; otherwise set self[k] = v -- Differs from node.__newindex() as this can also set fields of self +--- @deprecated v1.0 function key:__newindex(k, v) if k == 'value' then key.set(self, v) @@ -1549,6 +1557,7 @@ end --- Deprecated way to delete database node value pointed to by node object. -- Prefer `node:set(nil)` -- @see kill, set +--- @deprecated v1.0 function key:delete_node() M.delete_node(self) end --- Deprecated way to get next *sibling* subscript. @@ -1563,6 +1572,7 @@ function key:delete_node() M.delete_node(self) end -- @param[opt] reset If `true`, resets to the original subscript before any calls to `subscript_next()` -- @param[opt] reverse If `true` then get previous instead of next -- @see node:__pairs, subscript_previous +--- @deprecated v1.0 function key:subscript_next(reset, reverse) local actuator = reverse and M.subscript_previous or M.subscript_next if not self.__next_cachearray then @@ -1582,6 +1592,7 @@ end -- @param[opt] reset If `true`, resets to the original subscript before any calls to `subscript_next()` -- or `subscript_previous()` -- @see node:__pairs, subscript_next +--- @deprecated v1.0 function key:subscript_previous(reset) return self:subscript_next(reset, true) end @@ -1593,6 +1604,7 @@ end -- * It was non-intuitive that `key:subscripts()` iterates only subsequent subscripts, not all child subscripts. -- @param[opt] reverse When set to `true`, iterates in reverse -- @see subscripts +--- @deprecated v1.0 function key:subscripts(...) local cachearray = self if self:depth() == 0 then