feat: ability to extend the default patterns

* Feature - Ability to extend the default patterns

Cliff notes (will expand in more detail in PR):

1. Added ability to pass in a patterns table and a overrideDefaults boolean.
2. Backwards compatible.
3. Updated README.

* fixed formatting

---------

Co-authored-by: roy.crippen4 <[email protected]>

README.md

@@ -91,6 +91,18 @@ call.
 			"<cmd>lua require('spider').motion('e')<CR>",
 			mode = { "n", "o", "x" },
 		},
+		{ -- example using an explicit function
+			"w",
+			function()
+				require('spider').motion('w', {
+					customPatterns = {
+							patterns = { ('%x'):rep(6) .. '+' },
+							overrideDefault = true,
+					},
+				})
+			end,
+			mode = { 'n', 'o', 'x' },
+		},
 	},
 },
 
@@ -138,7 +150,7 @@ The `.setup()` call is optional.
 require("spider").setup {
 	skipInsignificantPunctuation = true,
 	subwordMovement = true,
-	customPatterns = {}, -- overrides other settings if not-empty. See README.
+	customPatterns = {}, -- check Custom Movement Patterns for details
 }
 ```
 
@@ -179,8 +191,14 @@ require("spider").motion("w", {
 
 -- The motion stops only at hashes like `ef82a2`, avoiding repetition by using
 -- `string.rep()`.
+-- Extend default patterns by passing a `patterns` table and
+-- setting `overrideDefault` to false.
 require("spider").motion("w", {
-	customPatterns = { ("%x"):rep(6) .. "+" },
+	customPatterns = {
+		patterns = {
+			("%x"):rep(6) .. "+" },
+		},
+		overrideDefault = false,
 })
 
 -- The motion stops at the next declaration of a variable in -- javascript.
@@ -192,10 +210,12 @@ require("spider").motion("e", {
 ```
 
 > [!NOTE]
-> Setting the option overrides `nvim-spider`'s default behavior, meaning subword
+> The `customPatterns` option overrides `nvim-spider`'s default behavior, meaning subword
 > movement and skipping of punctuation are disabled. You can add
-> `customPatterns` as an option to the `.motion` call to create extra motions,
+> `customPatterns` as an option to the `.motion` call to create new motions,
 > while still having access `nvim-spider`'s default behavior.
+> Pass a patterns table and set overrideDefault to false to extend
+> `nvim-spider`'s default behavior with a new pattern.
 
 ## Special Cases
 
@@ -270,7 +290,7 @@ compatibility. If you are interested in this subject, feel free to get in touch.
 __Blog__  
 I also occasionally blog about vim: [Nano Tips for Vim](https://nanotipsforvim.prose.sh)
 
-__Profiles__  
+__Profiles__
 - [reddit](https://www.reddit.com/user/pseudometapseudo)
 - [Discord](https://discordapp.com/users/462774483044794368/)
 - [Academic Website](https://chris-grieser.de/)

lua/spider/init.lua

@@ -38,17 +38,24 @@ else
 end
 
 --------------------------------------------------------------------------------
+---@class customPatterns
+---@field patterns string[]? string array of lua patterns to match against.
+---@field overrideDefault boolean? set to false to extend the default patterns with customPatterns. Defaults to true.
+
 -- CONFIG
 ---@class (exact) optsObj
----@field skipInsignificantPunctuation boolean
----@field subwordMovement boolean
----@field customPatterns string[]
+---@field skipInsignificantPunctuation boolean?
+---@field subwordMovement boolean? determines movement through camelCase and snake_case. Defaults to true.
+---@field customPatterns customPatterns|string[]? user defined patterns to match for motion movement
 
 ---@type optsObj
 local defaultOpts = {
 	skipInsignificantPunctuation = true,
 	subwordMovement = true,
-	customPatterns = {},
+	customPatterns = {
+		patterns = {},
+		overrideDefault = true,
+	},
 }
 local globalOpts = defaultOpts
 

lua/spider/pattern-variants.lua

@@ -8,7 +8,7 @@ local M = {}
 
 ---@type patternList
 local subwordPatterns = {
-	number = "%d+", 
+	number = "%d+",
 	camelCaseWordForward = "%u?%l+",
 	camelCaseWordBackward = "%l+%u?",
 	ALL_UPPER_CASE_WORD = "%u%u+",
@@ -37,15 +37,41 @@ local allPunctuationPatterns = {
 	punctuation = "%p+",
 }
 
+---@param table table table to verify.
+---@return boolean
+local function isStringArray(table)
+	if type(table) ~= "table" then return false end
+
+	for _, value in ipairs(table) do
+		if type(value) ~= "string" then return false end
+	end
+
+	return true
+end
+
 --------------------------------------------------------------------------------
 
 ---@param opts optsObj configuration table as in setup()
 ---@param backwards boolean whether to adjust patterns for backward motions
 ---@return patternList
 ---@nodiscard
 function M.get(opts, backwards)
+	-- opts.customPatterns.overrideDefault will default to true if it is not passed in.
+	-- This preserves the original behavior of spider.
+	-- Users can set overrideDefault to true, but spider will behave the same as the original behavior.
+	-- Behavior will change if a user sets the overrideDefault key to true within a customPatterns.patterns table.
 	-- any custom patterns take precedence
-	if opts.customPatterns and #opts.customPatterns > 0 then return opts.customPatterns end
+
+	-- need to check if opts.customPatterns is a string array to avoid breaking changes.
+	if opts.customPatterns and isStringArray(opts.customPatterns) then
+		if #opts.customPatterns > 0 then return opts.customPatterns end
+	end
+
+	-- this checks if a user set a custom pattern in the patterns table
+	-- then it checks if overrideDefault was set
+	if opts.customPatterns.patterns and #opts.customPatterns.patterns > 0 then
+		if opts.customPatterns.overrideDefault then return opts.customPatterns.patterns end
+	end
 
 	local punctuationPatterns = opts.skipInsignificantPunctuation and skipPunctuationPatterns
 		or allPunctuationPatterns
@@ -54,7 +80,10 @@ function M.get(opts, backwards)
 	if backwards then wordPatterns.camelCaseWordForward = nil end
 	if not backwards then wordPatterns.camelCaseWordBackward = nil end
 
-	local patternsToUse = vim.tbl_extend("force", wordPatterns, punctuationPatterns)
+	-- user patterns default to {}
+	-- user patterns table only changes patterntsToUse if patterns has a pattern and overrideDefaults was set to false.
+	local patternsToUse =
+		vim.tbl_extend("force", wordPatterns, punctuationPatterns, opts.customPatterns.patterns)
 	return patternsToUse
 end