xref: /dports/devel/lua-stdlib/lua-stdlib-release-v41.2.2/lib/std/string.lua

--[[--
 Additions to the core string module.

 The module table returned by `std.string` also contains all of the entries
 from the core string table.  An hygienic way to import this module, then, is
 simply to override the core `string` locally:

    local string = require "std.string"

 @module std.string
]]

local base   = require "std.base"
local debug  = require "std.debug"

local StrBuf = require "std.strbuf" {}

local copy          = base.copy
local getmetamethod = base.getmetamethod
local insert, len   = base.insert, base.len
local pairs         = base.pairs
local render        = base.render

local M



local _tostring = base.tostring

local function __concat (s, o)
  return _tostring (s) .. _tostring (o)
end


local function __index (s, i)
  if type (i) == "number" then
    return s:sub (i, i)
  else
    -- Fall back to module metamethods
    return M[i]
  end
end


local _format   = string.format

local function format (f, arg1, ...)
  return (arg1 ~= nil) and _format (f, arg1, ...) or f
end


local function tpack (from, to, ...)
  return from, to, {...}
end

local function tfind (s, ...)
  return tpack (s:find (...))
end


local function finds (s, p, i, ...)
  i = i or 1
  local l = {}
  local from, to, r
  repeat
    from, to, r = tfind (s, p, i, ...)
    if from ~= nil then
      insert (l, {from, to, capt = r})
      i = to + 1
    end
  until not from
  return l
end


local function monkey_patch (namespace)
  namespace = namespace or _G
  namespace.string = base.copy (namespace.string or {}, M)

  local string_metatable = getmetatable ""
  string_metatable.__concat = M.__concat
  string_metatable.__index = M.__index

  return M
end


local function caps (s)
  return (s:gsub ("(%w)([%w]*)", function (l, ls) return l:upper () .. ls end))
end


local function escape_shell (s)
  return (s:gsub ("([ %(%)%\\%[%]\"'])", "\\%1"))
end


local function ordinal_suffix (n)
  n = math.abs (n) % 100
  local d = n % 10
  if d == 1 and n ~= 11 then
    return "st"
  elseif d == 2 and n ~= 12 then
    return "nd"
  elseif d == 3 and n ~= 13 then
    return "rd"
  else
    return "th"
  end
end


local function pad (s, w, p)
  p = string.rep (p or " ", math.abs (w))
  if w < 0 then
    return string.sub (p .. s, w)
  end
  return string.sub (s .. p, 1, w)
end


local function wrap (s, w, ind, ind1)
  w = w or 78
  ind = ind or 0
  ind1 = ind1 or ind
  assert (ind1 < w and ind < w,
          "the indents must be less than the line width")
  local r = StrBuf { string.rep (" ", ind1) }
  local i, lstart, lens = 1, ind1, len (s)
  while i <= lens do
    local j = i + w - lstart
    while len (s[j]) > 0 and s[j] ~= " " and j > i do
      j = j - 1
    end
    local ni = j + 1
    while s[j] == " " do
      j = j - 1
    end
    r:concat (s:sub (i, j))
    i = ni
    if i < lens then
      r:concat ("\n" .. string.rep (" ", ind))
      lstart = ind
    end
  end
  return r:tostring ()
end


local function numbertosi (n)
  local SIprefix = {
    [-8] = "y", [-7] = "z", [-6] = "a", [-5] = "f",
    [-4] = "p", [-3] = "n", [-2] = "mu", [-1] = "m",
    [0] = "", [1] = "k", [2] = "M", [3] = "G",
    [4] = "T", [5] = "P", [6] = "E", [7] = "Z",
    [8] = "Y"
  }
  local t = format("% #.2e", n)
  local _, _, m, e = t:find(".(.%...)e(.+)")
  local man, exp = tonumber (m), tonumber (e)
  local siexp = math.floor (exp / 3)
  local shift = exp - siexp * 3
  local s = SIprefix[siexp] or "e" .. tostring (siexp)
  man = man * (10 ^ shift)
  return format ("%0.f", man) .. s
end


local function trim (s, r)
  r = r or "%s+"
  return (s:gsub ("^" .. r, ""):gsub (r .. "$", ""))
end


local function prettytostring (x, indent, spacing)
  indent = indent or "\t"
  spacing = spacing or ""
  return render (x,
                 function ()
                   local s = spacing .. "{"
                   spacing = spacing .. indent
                   return s
                 end,
                 function ()
                   spacing = string.gsub (spacing, indent .. "$", "")
                   return spacing .. "}"
                 end,
                 function (x)
                   if type (x) == "string" then
                     return format ("%q", x)
                   else
                     return tostring (x)
                   end
                 end,
                 function (x, k, v, ks, vs)
                   local s = spacing
		   if type (k) ~= "string" or k:match "[^%w_]" then
		     s = s .. "["
                     if type (k) == "table" then
                       s = s .. "\n"
                     end
                     s = s .. ks
                     if type (k) == "table" then
                       s = s .. "\n"
                     end
                     s = s .. "]"
		   else
		     s = s .. k
		   end
		   s = s .. " ="
                   if type (v) == "table" then
                     s = s .. "\n"
                   else
                     s = s .. " "
                   end
                   s = s .. vs
                   return s
                 end,
                 function (_, k)
                   local s = "\n"
                   if k then
                     s = "," .. s
                   end
                   return s
                 end)
end


local function pickle (x)
  if type (x) == "string" then
    return format ("%q", x)
  elseif type (x) == "number" or type (x) == "boolean" or
    type (x) == "nil" then
    return tostring (x)
  else
    x = copy (x) or x
    if type (x) == "table" then
      local s, sep = "{", ""
      for i, v in pairs (x) do
        s = s .. sep .. "[" .. M.pickle (i) .. "]=" .. M.pickle (v)
        sep = ","
      end
      s = s .. "}"
      return s
    else
      die ("cannot pickle " .. tostring (x))
    end
  end
end



--[[ ================= ]]--
--[[ Public Interface. ]]--
--[[ ================= ]]--


local function X (decl, fn)
  return debug.argscheck ("std.string." .. decl, fn)
end

M = {
  --- String concatenation operation.
  -- @string s initial string
  -- @param o object to stringify and concatenate
  -- @return s .. tostring (o)
  -- @usage
  -- local string = require "std.string".monkey_patch ()
  -- concatenated = "foo" .. {"bar"}
  __concat = __concat,

  --- String subscript operation.
  -- @string s string
  -- @tparam int|string i index or method name
  -- @return `s:sub (i, i)` if i is a number, otherwise
  --   fall back to a `std.string` metamethod (if any).
  -- @usage
  -- getmetatable ("").__index = require "std.string".__index
  -- third = ("12345")[3]
  __index = __index,

  --- Capitalise each word in a string.
  -- @function caps
  -- @string s any string
  -- @treturn string *s* with each word capitalized
  -- @usage userfullname = caps (input_string)
  caps = X ("caps (string)", caps),

  --- Remove any final newline from a string.
  -- @function chomp
  -- @string s any string
  -- @treturn string *s* with any single trailing newline removed
  -- @usage line = chomp (line)
  chomp = X ("chomp (string)", function (s) return (s:gsub ("\n$", "")) end),

  --- Escape a string to be used as a pattern.
  -- @function escape_pattern
  -- @string s any string
  -- @treturn string *s* with active pattern characters escaped
  -- @usage substr = inputstr:match (escape_pattern (literal))
  escape_pattern = X ("escape_pattern (string)", base.escape_pattern),

  --- Escape a string to be used as a shell token.
  -- Quotes spaces, parentheses, brackets, quotes, apostrophes and
  -- whitespace.
  -- @function escape_shell
  -- @string s any string
  -- @treturn string *s* with active shell characters escaped
  -- @usage os.execute ("echo " .. escape_shell (outputstr))
  escape_shell = X ("escape_shell (string)", escape_shell),

  --- Repeatedly `string.find` until target string is exhausted.
  -- @function finds
  -- @string s target string
  -- @string pattern pattern to match in *s*
  -- @int[opt=1] init start position
  -- @bool[opt] plain inhibit magic characters
  -- @return list of `{from, to; capt = {captures}}`
  -- @see std.string.tfind
  -- @usage
  -- for t in std.elems (finds ("the target string", "%S+")) do
  --   print (tostring (t.capt))
  -- end
  finds = X ("finds (string, string, ?int, ?boolean|:plain)", finds),

  --- Extend to work better with one argument.
  -- If only one argument is passed, no formatting is attempted.
  -- @function format
  -- @string f format string
  -- @param[opt] ... arguments to format
  -- @return formatted string
  -- @usage print (format "100% stdlib!")
  format = X ("format (string, [any...])", format),

  --- Remove leading matter from a string.
  -- @function ltrim
  -- @string s any string
  -- @string[opt="%s+"] r leading pattern
  -- @treturn string *s* with leading *r* stripped
  -- @usage print ("got: " .. ltrim (userinput))
  ltrim = X ("ltrim (string, ?string)",
             function (s, r) return (s:gsub ("^" .. (r or "%s+"), "")) end),

  --- Overwrite core `string` methods with `std` enhanced versions.
  --
  -- Also adds auto-stringification to `..` operator on core strings, and
  -- integer indexing of strings with `[]` dereferencing.
  -- @function monkey_patch
  -- @tparam[opt=_G] table namespace where to install global functions
  -- @treturn table the module table
  -- @usage local string = require "std.string".monkey_patch ()
  monkey_patch = X ("monkey_patch (?table)", monkey_patch),

  --- Write a number using SI suffixes.
  -- The number is always written to 3 s.f.
  -- @function numbertosi
  -- @tparam number|string n any numeric value
  -- @treturn string *n* simplifed using largest available SI suffix.
  -- @usage print (numbertosi (bitspersecond) .. "bps")
  numbertosi = X ("numbertosi (number|string)", numbertosi),

  --- Return the English suffix for an ordinal.
  -- @function ordinal_suffix
  -- @tparam int|string n any integer value
  -- @treturn string English suffix for *n*
  -- @usage
  -- local now = os.date "*t"
  -- print ("%d%s day of the week", now.day, ordinal_suffix (now.day))
  ordinal_suffix = X ("ordinal_suffix (int|string)", ordinal_suffix),

  --- Justify a string.
  -- When the string is longer than w, it is truncated (left or right
  -- according to the sign of w).
  -- @function pad
  -- @string s a string to justify
  -- @int w width to justify to (-ve means right-justify; +ve means
  --   left-justify)
  -- @string[opt=" "] p string to pad with
  -- @treturn string *s* justified to *w* characters wide
  -- @usage print (pad (trim (outputstr, 78)) .. "\n")
  pad = X ("pad (string, int, ?string)", pad),

  --- Convert a value to a string.
  -- The string can be passed to `functional.eval` to retrieve the value.
  -- @todo Make it work for recursive tables.
  -- @param x object to pickle
  -- @treturn string reversible string rendering of *x*
  -- @see std.eval
  -- @usage
  -- function slow_identity (x) return functional.eval (pickle (x)) end
  pickle = pickle,

  --- Pretty-print a table, or other object.
  -- @function prettytostring
  -- @param x object to convert to string
  -- @string[opt="\t"] indent indent between levels
  -- @string[opt=""] spacing space before every line
  -- @treturn string pretty string rendering of *x*
  -- @usage print (prettytostring (std, "  "))
  prettytostring = X ("prettytostring (?any, ?string, ?string)", prettytostring),

  --- Turn tables into strings with recursion detection.
  -- N.B. Functions calling render should not recurse, or recursion
  -- detection will not work.
  -- @function render
  -- @param x object to convert to string
  -- @tparam opentablecb open open table rendering function
  -- @tparam closetablecb close close table rendering function
  -- @tparam elementcb elem element rendering function
  -- @tparam paircb pair pair rendering function
  -- @tparam separatorcb sep separator rendering function
  -- @tparam[opt] table roots accumulates table references to detect recursion
  -- @return string representation of *x*
  -- @usage
  -- function tostring (x)
  --   return render (x, lambda '="{"', lambda '="}"', tostring,
  --                  lambda '=_4.."=".._5', lambda '= _4 and "," or ""',
  --                  lambda '=","')
  -- end
  render = X ("render (?any, func, func, func, func, func, ?table)", render),

  --- Remove trailing matter from a string.
  -- @function rtrim
  -- @string s any string
  -- @string[opt="%s+"] r trailing pattern
  -- @treturn string *s* with trailing *r* stripped
  -- @usage print ("got: " .. rtrim (userinput))
  rtrim = X ("rtrim (string, ?string)",
             function (s, r) return (s:gsub ((r or "%s+") .. "$", "")) end),

  --- Split a string at a given separator.
  -- Separator is a Lua pattern, so you have to escape active characters,
  -- `^$()%.[]*+-?` with a `%` prefix to match a literal character in *s*.
  -- @function split
  -- @string s to split
  -- @string[opt="%s+"] sep separator pattern
  -- @return list of strings
  -- @usage words = split "a very short sentence"
  split = X ("split (string, ?string)", base.split),

  --- Do `string.find`, returning a table of captures.
  -- @function tfind
  -- @string s target string
  -- @string pattern pattern to match in *s*
  -- @int[opt=1] init start position
  -- @bool[opt] plain inhibit magic characters
  -- @treturn int start of match
  -- @treturn int end of match
  -- @treturn table list of captured strings
  -- @see std.string.finds
  -- @usage b, e, captures = tfind ("the target string", "%s", 10)
  tfind = X ("tfind (string, string, ?int, ?boolean|:plain)", tfind),

  --- Remove leading and trailing matter from a string.
  -- @function trim
  -- @string s any string
  -- @string[opt="%s+"] r trailing pattern
  -- @treturn string *s* with leading and trailing *r* stripped
  -- @usage print ("got: " .. trim (userinput))
  trim = X ("trim (string, ?string)", trim),

  --- Wrap a string into a paragraph.
  -- @function wrap
  -- @string s a paragraph of text
  -- @int[opt=78] w width to wrap to
  -- @int[opt=0] ind indent
  -- @int[opt=ind] ind1 indent of first line
  -- @treturn string *s* wrapped to *w* columns
  -- @usage
  -- print (wrap (copyright, 72, 4))
  wrap = X ("wrap (string, ?int, ?int, ?int)", wrap),
}



--[[ ============= ]]--
--[[ Deprecations. ]]--
--[[ ============= ]]--


local DEPRECATED = debug.DEPRECATED


M.assert = DEPRECATED ("41", "'std.string.assert'",
  "use 'std.assert' instead", base.assert)


M.require_version = DEPRECATED ("41", "'std.string.require_version'",
  "use 'std.require' instead", base.require)


M.tostring = DEPRECATED ("41", "'std.string.tostring'",
  "use 'std.tostring' instead", base.tostring)



return base.merge (M, string)



--- Types
-- @section Types

--- Signature of @{render} open table callback.
-- @function opentablecb
-- @tparam table t table about to be rendered
-- @treturn string open table rendering
-- @see render
-- @usage function open (t) return "{" end


--- Signature of @{render} close table callback.
-- @function closetablecb
-- @tparam table t table just rendered
-- @treturn string close table rendering
-- @see render
-- @usage function close (t) return "}" end


--- Signature of @{render} element callback.
-- @function elementcb
-- @param x element to render
-- @treturn string element rendering
-- @see render
-- @usage function element (e) return require "std".tostring (e) end


--- Signature of @{render} pair callback.
-- Trying to re-render *key* or *value* here will break recursion
-- detection, use *strkey* and *strvalue* pre-rendered values instead.
-- @function paircb
-- @tparam table t table containing pair being rendered
-- @param key key part of key being rendered
-- @param value value part of key being rendered
-- @string keystr prerendered *key*
-- @string valuestr prerendered *value*
-- @treturn string pair rendering
-- @see render
-- @usage
-- function pair (_, _, _, key, value) return key .. "=" .. value end


--- Signature of @{render} separator callback.
-- @function separatorcb
-- @tparam table t table currently being rendered
-- @param pk *t* key preceding separator, or `nil` for first key
-- @param pv *t* value preceding separator, or `nil` for first value
-- @param fk *t* key following separator, or `nil` for last key
-- @param fv *t* value following separator, or `nil` for last value
-- @treturn string separator rendering
-- @usage
-- function separator (_, _, _, fk) return fk and "," or "" end