deprecating with_visual_selection

README.md

@@ -219,7 +219,7 @@ Excluding seems to be necessary with copilot at the time of writing this.
 
 For more control, you can programmatically open a grug-far buffer like so:
 ```sh
-require('grug-far').grug_far(opts)
+require('grug-far').open(opts)
 ```
 If the above is called while in visual mode, it will pre-fill current visual selection as search text.
 (note, this will also set `--fixed-strings` flag as selection can contain special characters)
@@ -228,6 +228,7 @@ Note that if you want to pre-fill current visual selection from command mode, yo
 ```
 :lua require('grug-far').with_visual_selection(opts)
 ```
+(command mode is the only case where this is necessary in order to force using the visual selection)
 
 where `opts` will be merged with and override the global plugin options configured at setup time.
 
@@ -239,22 +240,22 @@ For more API, see [docs][docs]
 
 #### Launch with the current word under the cursor as the search string
 ```lua
-:lua require('grug-far').grug_far({ prefills = { search = vim.fn.expand("<cword>") } })
+:lua require('grug-far').open({ prefills = { search = vim.fn.expand("<cword>") } })
 ```
 
 #### Launch with ast-grep engine
 ```lua
-:lua require('grug-far').grug_far({ engine = 'astgrep' })
+:lua require('grug-far').open({ engine = 'astgrep' })
 ```
 
 #### Launch as a transient buffer which is both unlisted and fully deletes itself when not in use
 ```lua
-:lua require('grug-far').grug_far({ transient = true })
+:lua require('grug-far').open({ transient = true })
 ```
 
 #### Launch, limiting search/replace to current file
 ```lua
-:lua require('grug-far').grug_far({ prefills = { paths = vim.fn.expand("%") } })
+:lua require('grug-far').open({ prefills = { paths = vim.fn.expand("%") } })
 ```
 
 #### Launch with the current visual selection, searching only current file
@@ -331,7 +332,7 @@ return {
 
           -- instance check
           if not grugFar.has_instance("tree") then
-            grugFar.grug_far({
+            grugFar.open({
               instanceName = "tree",
               prefills = prefills,
               staticTitle = "Find and Replace from Tree",

doc/grug-far.txt

@@ -44,7 +44,7 @@ require('grug-far').setup({config})                  *grug-far.setup()*
             {config}(optional, table) Table of values; keys as described
                 above. Accept defaults by omitting the relevant key.
 
-require('grug-far').grug_far({config})                *grug-far.grug_far()*
+require('grug-far').open({config})                *grug-far.open()*
         Launches grug-far, where the given config overrides the global plugin
 	config that was passed to require('grug-far).setup(...). 
         Currently supported configuration options are the same as the global

lua/grug-far.lua

@@ -74,7 +74,7 @@ function M.setup(options)
     if params.mods and #params.mods > 0 then
       resolvedOpts.windowCreationCommand = params.mods .. ' split'
     end
-    M._grug_far_internal(resolvedOpts, { is_visual = is_visual })
+    M._open_internal(resolvedOpts, { is_visual = is_visual })
   end, {
     nargs = '?',
     range = true,
@@ -234,7 +234,7 @@ end
 --- launch grug-far with the given overrides
 ---@param options? GrugFarOptionsOverride
 ---@return string instanceName
-function M.grug_far(options)
+function M.open(options)
   ensure_configured()
   local resolvedOpts = opts.with_defaults(options or {}, globalOptions)
   local is_visual = false
@@ -246,14 +246,14 @@ function M.grug_far(options)
     vim.cmd([[normal! vv]])
   end
 
-  return M._grug_far_internal(resolvedOpts, { is_visual = is_visual })
+  return M._open_internal(resolvedOpts, { is_visual = is_visual })
 end
 
 --- launch grug-far with the given options and params
 ---@param options GrugFarOptions
 ---@param params { is_visual: boolean }
 ---@return string instanceName
-function M._grug_far_internal(options, params)
+function M._open_internal(options, params)
   if options.instanceName and namedInstances[options.instanceName] then
     error('A grug-far instance with instanceName="' .. options.instanceName .. '" already exists!')
   end
@@ -274,22 +274,6 @@ function M._grug_far_internal(options, params)
   return options.instanceName
 end
 
---- launch grug-far with the given overrides, pre-filling
---- search with current visual selection.
----@param options? GrugFarOptionsOverride
-function M.with_visual_selection(options)
-  ensure_configured()
-
-  local isVisualMode = vim.fn.mode():lower():find('v') ~= nil
-  if isVisualMode then
-    -- needed to make visual selection work
-    vim.cmd([[normal! vv]])
-  end
-
-  local resolvedOpts = opts.with_defaults(options or {}, globalOptions)
-  return M._grug_far_internal(resolvedOpts, { is_visual = true })
-end
-
 --- toggles given list of flags in the current grug-far buffer
 ---@param flags string[]
 function M.toggle_flags(flags)
@@ -328,7 +312,7 @@ function M.toggle_instance(options)
 
   local inst = namedInstances[options.instanceName]
   if not inst then
-    M.grug_far(options)
+    M.open(options)
     return
   end
 
@@ -418,4 +402,28 @@ function M.update_instance_prefills(instanceName, prefills, clearOld)
   end)
 end
 
+--- launch grug-far with the given overrides, pre-filling
+--- search with current visual selection.
+---@param options? GrugFarOptionsOverride
+function M.with_visual_selection(options)
+  ensure_configured()
+
+  local isVisualMode = vim.fn.mode():lower():find('v') ~= nil
+  if isVisualMode then
+    -- needed to make visual selection work
+    vim.cmd([[normal! vv]])
+  end
+
+  local resolvedOpts = opts.with_defaults(options or {}, globalOptions)
+  return M._open_internal(resolvedOpts, { is_visual = true })
+end
+
+---@deprecated use open(same options) instead
+--- launch grug-far with the given overrides
+---@param options? GrugFarOptionsOverride
+---@return string instanceName
+function M.grug_far(options)
+  return M.open(options)
+end
+
 return M

lua/grug-far/opts.lua

@@ -208,7 +208,7 @@ M.defaultOptions = {
   -- when launching through the lua API. For example, this is how you would launch grug-far.nvim
   -- with the current word under the cursor as the search string
   --
-  -- require('grug-far').grug_far({ prefills = { search = vim.fn.expand("<cword>") } })
+  -- require('grug-far').open({ prefills = { search = vim.fn.expand("<cword>") } })
   --
   prefills = {
     search = '',

lua/grug-far/test/helpers.lua

@@ -215,7 +215,7 @@ function M.childWaitForFinishedStatus(child)
   end)
 end
 
---- run grug_far(options) in child
+--- run open(options) in child
 ---@param child NeovimChild
 ---@param options GrugFarOptionsOverride
 ---@return string instanceName
@@ -224,7 +224,7 @@ function M.childRunGrugFar(child, options)
   vim.fn.mkdir('./temp_history_dir')
 
   M.cdTempTestDir(child)
-  return child.lua_get('GrugFar.grug_far(...)', {
+  return child.lua_get('GrugFar.open(...)', {
     options,
   })
 end

tests/base/test_ui.lua

@@ -42,6 +42,14 @@ T['can launch with :GrugFar ripgrep'] = function()
   helpers.childWaitForScreenshotText(child, 'ripgrep')
 end
 
+T['can launch with deprecated grug_far api'] = function()
+  child.lua_get('GrugFar.grug_far(...)', {
+    {},
+  })
+  helpers.childWaitForScreenshotText(child, 'ripgrep')
+  helpers.childExpectScreenshot(child)
+end
+
 T['can search manually on insert leave or normal mode change'] = function()
   helpers.writeTestFiles({
     { filename = 'file1', content = [[ grug walks ]] },

tests/screenshots/tests-base-test_ui.lua---can-launch-with-deprecated-grug_far-api

@@ -0,0 +1,51 @@
+--|---------|---------|---------|---------|---------|---------|---------|---------|
+01|  Actions / Help <g?>    Replace <,r>    Sync All <,s> ...                   
+02|                                                                                
+03|  Search:                                                                      
+04|                                                                                
+05|  Replace:                                                                     
+06|                                                                                
+07|  Files Filter:                                                                
+08|                                                                                
+09| 󰮚 Flags:                                                                       
+10|                                                                                
+11|  Paths:                                                                       
+12|                                                                                
+13|                                                                                
+14| STATUS_READY ⟪ ripgrep ⟫
+15|                                                                                
+16|~                                                                               
+17|~                                                                               
+18|~                                                                               
+19|~                                                                               
+20|~                                                                               
+21|~                                                                               
+22|~                                                                               
+23|Grug FAR - 1                                                  3,1            All
+24|-- INSERT --                                                                    
+
+--|---------|---------|---------|---------|---------|---------|---------|---------|
+01|01111111111111111111112221111111111111122211111111111111122222222222222222222222
+02|02222222222222222222222222222222222222222222222222222222222222222222222222222222
+03|33333333332222222222222222222222222222222222222222222222222222222222222222222222
+04|02222222222222222222222222222222222222222222222222222222222222222222222222222222
+05|33333333333222222222222222222222222222222222222222222222222222222222222222222222
+06|02222222222222222222222222222222222222222222222222222222222222222222222222222222
+07|33333333333333332222222222222222222222222222222222222222222222222222222222222222
+08|02222222222222222222222222222222222222222222222222222222222222222222222222222222
+09|33333333322222222222222222222222222222222222222222222222222222222222222222222222
+10|02222222222222222222222222222222222222222222222222222222222222222222222222222222
+11|33333333322222222222222222222222222222222222222222222222222222222222222222222222
+12|02222222222222222222222222222222222222222222222222222222222222222222222222222222
+13|22222222222222222222222222222222222222222222222222222222222222222222222222222222
+14|44444444444444444444444444444444444444444444444444444444444444444444444444444444
+15|02222222222222222222222222222222222222222222222222222222222222222222222222222222
+16|00000000000000000000000000000000000000000000000000000000000000000000000000000000
+17|00000000000000000000000000000000000000000000000000000000000000000000000000000000
+18|00000000000000000000000000000000000000000000000000000000000000000000000000000000
+19|00000000000000000000000000000000000000000000000000000000000000000000000000000000
+20|00000000000000000000000000000000000000000000000000000000000000000000000000000000
+21|00000000000000000000000000000000000000000000000000000000000000000000000000000000
+22|00000000000000000000000000000000000000000000000000000000000000000000000000000000
+23|55555555555555555555555555555555555555555555555555555555555555555555555555555555
+24|11111111111166666666666666666666666666666666666666666666666666666666666666666666