From 9c49c1047079427ff0a2356cb37302934845108e Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 20 Mar 2023 08:12:33 +0100 Subject: feat(vim.gsplit): gain features of vim.split Problem: - vim.split has more features than vim.gsplit. - Cannot inspect the "separator" segments of vim.split or vim.gsplit. Solution: - Move common implementation from vim.split into vim.gsplit. - TODO: deprecate vim.split in favor of vim.totable(vim.gsplit())? - Introduce `keepsep` parameter. Related: 84f66909e4008a57da947f1640bfc24da5e41a72 --- runtime/doc/lua.txt | 35 ++++++++++++++++++++++------------- runtime/doc/news.txt | 2 ++ 2 files changed, 24 insertions(+), 13 deletions(-) (limited to 'runtime/doc') diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 4f56593491..a1fb7aa344 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -1649,14 +1649,25 @@ endswith({s}, {suffix}) *vim.endswith()* Return: ~ (boolean) `true` if `suffix` is a suffix of `s` -gsplit({s}, {sep}, {plain}) *vim.gsplit()* +gsplit({s}, {sep}, {opts}) *vim.gsplit()* Splits a string at each instance of a separator. + Example: >lua + + for s in vim.gsplit(':aa::b:', ':', {plain=true}) do + print(s) + end +< + Parameters: ~ - • {s} (string) String to split - • {sep} (string) Separator or pattern - • {plain} (boolean|nil) If `true` use `sep` literally (passed to - string.find) + • {s} (string) String to split + • {sep} (string) Separator or pattern + • {opts} (table|nil) Keyword arguments |kwargs|: + • keepsep: (boolean) Return segments matching `sep` instead of + discarding them. + • plain: (boolean) Use `sep` literally (as in string.find). + • trimempty: (boolean) Discard empty segments at start and end + of the sequence. Return: ~ (function) Iterator over the split components @@ -1729,7 +1740,7 @@ spairs({t}) *vim.spairs()* See also: ~ • Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua -split({s}, {sep}, {kwargs}) *vim.split()* +split({s}, {sep}, {opts}) *vim.split()* Splits a string at each instance of a separator. Examples: >lua @@ -1738,16 +1749,14 @@ split({s}, {sep}, {kwargs}) *vim.split()* split("axaby", "ab?") --> {'','x','y'} split("x*yz*o", "*", {plain=true}) --> {'x','yz','o'} split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'} + split("|x|y|z|", "|", {keepsep=true}) --> {'|', 'x', '|', 'y', '|', 'z', '|'} < Parameters: ~ - • {s} (string) String to split - • {sep} (string) Separator or pattern - • {kwargs} (table|nil) Keyword arguments: - • plain: (boolean) If `true` use `sep` literally (passed to - string.find) - • trimempty: (boolean) If `true` remove empty items from the - front and back of the list + • {s} (string) String to split + • {sep} (string) Separator or pattern + • {opts} (table|nil) Keyword arguments |kwargs| accepted by + |vim.gsplit()| Return: ~ string[] List of split components diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 57b3e00709..1499b9d742 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -132,6 +132,8 @@ The following new APIs or features were added. • |vim.fs.dir()| now has a `opts` argument with a depth field to allow recursively searching a directory tree. +• |vim.gsplit()| supports all features of |vim.split()|. + • |vim.secure.read()| reads a file and prompts the user if it should be trusted and, if so, returns the file's contents. -- cgit From e51139f5c1d70bef1424f29e63eb527514e42865 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 22 Mar 2023 15:14:51 +0100 Subject: refactor(vim.gsplit): remove "keepsep" string.gmatch() is superior, use that instead. --- runtime/doc/lua.txt | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) (limited to 'runtime/doc') diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index a1fb7aa344..2baae3a123 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -1659,12 +1659,18 @@ gsplit({s}, {sep}, {opts}) *vim.gsplit()* end < + If you want to also inspect the separator itself (instead of discarding + it), use |string.gmatch()|. Example: >lua + + for word, num in ('foo111bar222'):gmatch('([^0-9]*)(d*)') do + print(('word: s num: s'):format(word, num)) + end +< + Parameters: ~ - • {s} (string) String to split - • {sep} (string) Separator or pattern + • {s} string String to split + • {sep} string Separator or pattern • {opts} (table|nil) Keyword arguments |kwargs|: - • keepsep: (boolean) Return segments matching `sep` instead of - discarding them. • plain: (boolean) Use `sep` literally (as in string.find). • trimempty: (boolean) Discard empty segments at start and end of the sequence. @@ -1673,6 +1679,7 @@ gsplit({s}, {sep}, {opts}) *vim.gsplit()* (function) Iterator over the split components See also: ~ + • |string.gmatch()| • |vim.split()| • |luaref-patterns| • https://www.lua.org/pil/20.2.html @@ -1749,7 +1756,6 @@ split({s}, {sep}, {opts}) *vim.split()* split("axaby", "ab?") --> {'','x','y'} split("x*yz*o", "*", {plain=true}) --> {'x','yz','o'} split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'} - split("|x|y|z|", "|", {keepsep=true}) --> {'|', 'x', '|', 'y', '|', 'z', '|'} < Parameters: ~ @@ -1763,6 +1769,7 @@ split({s}, {sep}, {opts}) *vim.split()* See also: ~ • |vim.gsplit()| + • |string.gmatch()| startswith({s}, {prefix}) *vim.startswith()* Tests if `s` starts with `prefix`. @@ -2625,7 +2632,7 @@ cmp({v1}, {v2}) *vim.version.cmp()* (integer) -1 if `v1 < v2`, 0 if `v1 == v2`, 1 if `v1 > v2`. eq({v1}, {v2}) *vim.version.eq()* - Returns `true` if the given versions are equal. + Returns `true` if the given versions are equal. See |vim.version.cmp()| for usage. Parameters: ~ • {v1} Version|number[] @@ -2635,7 +2642,7 @@ eq({v1}, {v2}) *vim.version.eq()* (boolean) gt({v1}, {v2}) *vim.version.gt()* - Returns `true` if `v1 > v2` . + Returns `true` if `v1 > v2` . See |vim.version.cmp()| for usage. Parameters: ~ • {v1} Version|number[] @@ -2654,7 +2661,7 @@ last({versions}) *vim.version.last()* Version ?|ni lt({v1}, {v2}) *vim.version.lt()* - Returns `true` if `v1 < v2` . + Returns `true` if `v1 < v2` . See |vim.version.cmp()| for usage. Parameters: ~ • {v1} Version|number[] -- cgit