From d05b7d80f195df9c206c4e2e581a6f1f6ce614bd Mon Sep 17 00:00:00 2001 From: Seth Barberee Date: Fri, 13 Dec 2019 14:19:38 -0600 Subject: [PATCH] gears.string doc revamp --- lib/gears/string.lua | 25 +++++++++++++------ tests/examples/text/gears/string/endswith.lua | 12 +++++++++ .../text/gears/string/endswith.output.txt | 2 ++ .../examples/text/gears/string/linecount.lua | 11 ++++++++ .../text/gears/string/linecount.output.txt | 2 ++ tests/examples/text/gears/string/linewrap.lua | 6 +++++ .../text/gears/string/linewrap.output.txt | 2 ++ .../text/gears/string/quote_pattern.lua | 6 +++++ .../gears/string/quote_pattern.output.txt | 1 + .../examples/text/gears/string/startswith.lua | 11 ++++++++ .../text/gears/string/startswith.output.txt | 2 ++ 11 files changed, 72 insertions(+), 8 deletions(-) create mode 100644 tests/examples/text/gears/string/endswith.lua create mode 100644 tests/examples/text/gears/string/endswith.output.txt create mode 100644 tests/examples/text/gears/string/linecount.lua create mode 100644 tests/examples/text/gears/string/linecount.output.txt create mode 100644 tests/examples/text/gears/string/linewrap.lua create mode 100644 tests/examples/text/gears/string/linewrap.output.txt create mode 100644 tests/examples/text/gears/string/quote_pattern.lua create mode 100644 tests/examples/text/gears/string/quote_pattern.output.txt create mode 100644 tests/examples/text/gears/string/startswith.lua create mode 100644 tests/examples/text/gears/string/startswith.output.txt diff --git a/lib/gears/string.lua b/lib/gears/string.lua index a5c2eec09..159981ed1 100644 --- a/lib/gears/string.lua +++ b/lib/gears/string.lua @@ -11,7 +11,7 @@ local xml_entity_names = { ["'"] = "'", ["\""] = """, ["<"] = "<", --- Escape a string from XML char. -- Useful to set raw text in textbox. -- @param text Text to escape. --- @return Escape text. +-- @treturn string Escaped text. -- @staticfct gears.string.xml_escape function gstring.xml_escape(text) return text and text:gsub("['&<>\"]", xml_entity_names) or nil @@ -22,13 +22,14 @@ local xml_entity_chars = { lt = "<", gt = ">", nbsp = " ", quot = "\"", apos = " --- Unescape a string from entities. -- @param text Text to unescape. --- @return Unescaped text. +-- @treturn string Unescaped text. -- @staticfct gears.string.xml_unescape function gstring.xml_unescape(text) return text and text:gsub("&(%a+);", xml_entity_chars) or nil end ---- Count number of lines in a string +--- Count number of lines in a string. +-- @DOC_text_gears_string_linecount_EXAMPLE@ -- @tparam string text Input string. -- @treturn int Number of lines. -- @staticfct gears.string.linecount @@ -37,10 +38,11 @@ function gstring.linecount(text) end --- Split a string into multiple lines. --- @param text String to wrap. --- @param width Maximum length of each line. Default: 72. --- @param indent Number of spaces added before each wrapped line. Default: 0. --- @return The string with lines wrapped to width. +-- @DOC_text_gears_string_linewrap_EXAMPLE@ +-- @tparam string text String to wrap. +-- @tparam number width Maximum length of each line. Default: 72. +-- @tparam number indent Number of spaces added before each wrapped line. Default: 0. +-- @treturn string The string with lines wrapped to width. -- @staticfct gears.string.linewrap function gstring.linewrap(text, width, indent) text = text or "" @@ -60,6 +62,9 @@ end --- Escape all special pattern-matching characters so that lua interprets them -- literally instead of as a character class. -- Source: http://stackoverflow.com/a/20778724/15690 +-- @DOC_text_gears_string_quote_pattern_EXAMPLE@ +-- @tparam string s String to generate pattern for +-- @treturn string string with escaped characters -- @staticfct gears.string.quote_pattern function gstring.quote_pattern(s) -- All special characters escaped in a string: %%, %^, %$, ... @@ -68,7 +73,7 @@ function gstring.quote_pattern(s) end --- Generate a pattern matching expression that ignores case. --- @param s Original pattern matching expression. +-- @tparam string q Original pattern matching expression. -- @staticfct gears.string.query_to_pattern function gstring.query_to_pattern(q) local s = gstring.quote_pattern(q) @@ -102,7 +107,9 @@ function gstring.split(str, delimiter) end --- Check if a string starts with another string. +-- @DOC_text_gears_string_startswith_EXAMPLE@ -- @tparam string str String to search +-- @treturn boolean `true` if string starts with specified string -- @tparam string sub String to check for. -- @staticfct gears.string.startswith function gstring.startswith(str, sub) @@ -110,8 +117,10 @@ function gstring.startswith(str, sub) end --- Check if a string ends with another string. +-- @DOC_text_gears_string_endswith_EXAMPLE@ -- @tparam string str String to search -- @tparam string sub String to check for. +-- @treturn boolean `true` if string ends with specified string -- @staticfct gears.string.endswith function gstring.endswith(str, sub) return sub == "" or string.sub(str,-string.len(sub)) == sub diff --git a/tests/examples/text/gears/string/endswith.lua b/tests/examples/text/gears/string/endswith.lua new file mode 100644 index 000000000..7cddc51e1 --- /dev/null +++ b/tests/examples/text/gears/string/endswith.lua @@ -0,0 +1,12 @@ +--DOC_GEN_OUTPUT --DOC_HIDE +local gears = require("gears") --DOC_HIDE + +local test = "do.it" +local res = gears.string.endswith(test,"it") +print(tostring(res)) +assert(res == true) --DOC_HIDE + +res = gears.string.endswith(test,"do") +print(tostring(res)) +assert(res == false) --DOC_HIDE + diff --git a/tests/examples/text/gears/string/endswith.output.txt b/tests/examples/text/gears/string/endswith.output.txt new file mode 100644 index 000000000..da29283aa --- /dev/null +++ b/tests/examples/text/gears/string/endswith.output.txt @@ -0,0 +1,2 @@ +true +false diff --git a/tests/examples/text/gears/string/linecount.lua b/tests/examples/text/gears/string/linecount.lua new file mode 100644 index 000000000..a0101995c --- /dev/null +++ b/tests/examples/text/gears/string/linecount.lua @@ -0,0 +1,11 @@ +--DOC_GEN_OUTPUT --DOC_HIDE +local gears = require("gears") --DOC_HIDE + +local test = "do.t" +local res = gears.string.linecount(test) +print("Count is: " .. res) + +local test2 = "do\nit\nnow" +local res2 = gears.string.linecount(test2) +print("Count is: " .. res2) + diff --git a/tests/examples/text/gears/string/linecount.output.txt b/tests/examples/text/gears/string/linecount.output.txt new file mode 100644 index 000000000..7ddc01ee1 --- /dev/null +++ b/tests/examples/text/gears/string/linecount.output.txt @@ -0,0 +1,2 @@ +Count is: 1 +Count is: 3 diff --git a/tests/examples/text/gears/string/linewrap.lua b/tests/examples/text/gears/string/linewrap.lua new file mode 100644 index 000000000..55cd3f9bd --- /dev/null +++ b/tests/examples/text/gears/string/linewrap.lua @@ -0,0 +1,6 @@ +--DOC_GEN_OUTPUT --DOC_HIDE +local gears = require("gears") --DOC_HIDE + +local test = "do it" +local res = gears.string.linewrap(test, 2, 0) +print(res) diff --git a/tests/examples/text/gears/string/linewrap.output.txt b/tests/examples/text/gears/string/linewrap.output.txt new file mode 100644 index 000000000..8d661591f --- /dev/null +++ b/tests/examples/text/gears/string/linewrap.output.txt @@ -0,0 +1,2 @@ +do +it diff --git a/tests/examples/text/gears/string/quote_pattern.lua b/tests/examples/text/gears/string/quote_pattern.lua new file mode 100644 index 000000000..69e32df94 --- /dev/null +++ b/tests/examples/text/gears/string/quote_pattern.lua @@ -0,0 +1,6 @@ +--DOC_GEN_OUTPUT --DOC_HIDE +local gears = require("gears") --DOC_HIDE + +local test = "do.it" +local res = gears.string.quote_pattern(test) +print(res) diff --git a/tests/examples/text/gears/string/quote_pattern.output.txt b/tests/examples/text/gears/string/quote_pattern.output.txt new file mode 100644 index 000000000..636b1799e --- /dev/null +++ b/tests/examples/text/gears/string/quote_pattern.output.txt @@ -0,0 +1 @@ +do%.it diff --git a/tests/examples/text/gears/string/startswith.lua b/tests/examples/text/gears/string/startswith.lua new file mode 100644 index 000000000..f62543892 --- /dev/null +++ b/tests/examples/text/gears/string/startswith.lua @@ -0,0 +1,11 @@ +--DOC_GEN_OUTPUT --DOC_HIDE +local gears = require("gears") --DOC_HIDE + +local test = "do.it" +local res = gears.string.startswith(test,"do") +print(tostring(res)) -- Print boolean value +assert(res == true) --DOC_HIDE + +res = gears.string.startswith(test,"it") +print(tostring(res)) -- print boolean value +assert(res == false) --DOC_HIDE diff --git a/tests/examples/text/gears/string/startswith.output.txt b/tests/examples/text/gears/string/startswith.output.txt new file mode 100644 index 000000000..da29283aa --- /dev/null +++ b/tests/examples/text/gears/string/startswith.output.txt @@ -0,0 +1,2 @@ +true +false