diff --git a/lib/gears/string.lua b/lib/gears/string.lua index a5c2eec0..159981ed 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 00000000..7cddc51e --- /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 00000000..da29283a --- /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 00000000..a0101995 --- /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 00000000..7ddc01ee --- /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 00000000..55cd3f9b --- /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 00000000..8d661591 --- /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 00000000..69e32df9 --- /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 00000000..636b1799 --- /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 00000000..f6254389 --- /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 00000000..da29283a --- /dev/null +++ b/tests/examples/text/gears/string/startswith.output.txt @@ -0,0 +1,2 @@ +true +false