feat: support command range (#60)

* fix: visual mode

* fix: visual mode

* revert: move back line_range method

README.md

@@ -1,3 +1,5 @@
+<!-- markdownlint-disable MD013 MD034 -->
+
 # gitlinker.nvim
 
 > A fork of [ruifm's gitlinker](https://github.com/ruifm/gitlinker.nvim), refactored
@@ -13,22 +15,26 @@ An example of git permalink:
 Personally, I use this all the time to easily share code locations with my
 co-workers.
 
-- [New Features & Break Changes](#new-features--break-changes)
+- [Break Changes & Features](#break-changes--features)
   - [Lua pattern based rules](#lua-pattern-based-rules)
 - [Installation](#installation)
   - [packer.nvim](#packernvim)
   - [vim-plug](#vim-plug)
   - [lazy.nvim](#lazynvim)
-- [Key Mappings](#key-mappings)
+- [Usage](#usage)
+  - [Action](#action)
+  - [API](#api)
+  - [Key Mappings](#key-mappings)
+  - [Customization](#customization)
 - [Configuration](#configuration)
 
-## New Features & Break Changes
+## Break Changes & Features
 
-1. Bug fix: you can disable/custom the default key mappings.
+1. Bug fix: you can disable/custom default key mappings.
 2. Windows support: you can use it on Windows.
 3. Url mapping engine changed: pattern based rules instead of hard coding.
 4. Refactor: use git error message instead of self-defined error, drop off `plenary` library.
-6. Rewrittens: API re-designed, logger added, code base re-structured.
+5. Rewrittens: API re-designed, logger added, code base re-structured.
 
 ### Lua pattern based rules
 
@@ -88,19 +94,69 @@ EOF
 },
 ```
 
+# Usage
+
+## Action
+
+- `require('gitlinker.actions').clipboard`: copy git link to clipboard.
+- `require('gitlinker.actions').system`: open git link in browser.
+
+## API
+
+- `require('gitlinker').link(option)`: the main API that generate the git permalink, the `option` is a lua table that has below fields:
+
+  ```lua
+  {
+      action = ..., -- gitlinker actions: clipboard/system
+      lstart = ..., -- selected line start, please see in [Customization](#customization).
+      lend = ..., -- selected line end, please see in [Customization](#customization).
+  }
+  ```
+
+There're no pre-defined vim command, you need to use:
+
+- `require('gitlinker').link({ action = require('gitlinker.actions').clipboard })` to copy git link.
+- `require('gitlinker').link({ action = require('gitlinker.actions').system })` to open git link.
+
 ## Key Mappings
 
-There're two key mappings defined by default:
+The above two operations are already defined with two default key mappings:
 
 - `<leader>gl` (normal/visual mode): copy git link to clipboard.
 - `<leader>gL` (normal/visual mode): open git link in browser.
 
+## Customization
+
 To disable the default key mappings, set `mapping = false` in `setup()` function
 (see [Configuration](#configuration)).
 
 To create your own key mappings, please specify the `mapping` option
 in `setup()` function.
 
+To create your own vim command, please use:
+
+For vim:
+
+```vim
+command! -range GitLink lua require('gitlinker').link({ action = require('gitlinker.actions').system, lstart = vim.api.nvim_buf_get_mark(0, '<')[1], lend = vim.api.nvim_buf_get_mark(0, '>')[1] })
+```
+
+For lua:
+
+```lua
+vim.api.nvim_create_user_command("GitLink", function()
+    require("gitlinker").link({
+        action = require("gitlinker.actions").system,
+        lstart = vim.api.nvim_buf_get_mark(0, '<')[1],
+        lend = vim.api.nvim_buf_get_mark(0, '>')[1]
+    })
+end, {
+    range = true,
+})
+```
+
+> Support visual mode is a little bit tricky, please read: https://github.com/linrongbin16/gitlinker.nvim/discussions/38.
+
 ## Configuration
 
 ````lua

lua/gitlinker.lua

@@ -164,7 +164,7 @@ local function new_linker(remote_url, rev, file, lstart, lend, file_changed)
 end
 
 --- @return Linker|nil
-local function make_link_data()
+local function make_link_data(range)
   --- @type JobResult
   local root_result = git.get_root()
   if not git.result_has_out(root_result) then
@@ -246,13 +246,15 @@ local function make_link_data()
     vim.inspect(buf_path_on_cwd)
   )
 
-  --- @type LineRange
-  local range = util.line_range()
-  logger.debug(
-    "[make_link_data] range(%s):%s",
-    vim.inspect(type(range)),
-    vim.inspect(range)
-  )
+  if range == nil or range["lstart"] == nil or range["lend"] == nil then
+    --- @type LineRange
+    range = util.line_range()
+    logger.debug(
+      "[make_link_data] range(%s):%s",
+      vim.inspect(type(range)),
+      vim.inspect(range)
+    )
+  end
 
   local remote_url = remote_url_result.stdout[1]
   logger.debug(
@@ -327,7 +329,11 @@ local function link(option)
   option = vim.tbl_deep_extend("force", Configs, option or {})
   logger.debug("[make_link] after merge, option: %s", vim.inspect(option))
 
-  local linker = make_link_data()
+  local range = nil
+  if option["lstart"] ~= nil and option["lend"] ~= nil then
+    range = { lstart = option["lstart"], lend = option["lend"] }
+  end
+  local linker = make_link_data(range)
   if not linker then
     return nil
   end