feat: add <Plug> mappings (#10)

## Problem

Users who want keybindings must call Lua functions directly or wrap
commands in closures. There is no stable public API for key binding.

## Solution

Define <Plug> mappings in the plugin file and document them in a new
MAPPINGS section in the vimdoc.

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -7,8 +7,7 @@ body:
     attributes:
       label: Prerequisites
       options:
-        - label:
-            I have searched [existing
+        - label: I have searched [existing
             issues](https://github.com/barrettruth/http-codes.nvim/issues)
           required: true
         - label: I have updated to the latest version

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -7,8 +7,7 @@ body:
     attributes:
       label: Prerequisites
       options:
-        - label:
-            I have searched [existing
+        - label: I have searched [existing
             issues](https://github.com/barrettruth/http-codes.nvim/issues)
           required: true
 

.luarc.json

@@ -1,7 +1,7 @@
 {
   "runtime.version": "Lua 5.1",
   "runtime.path": ["lua/?.lua", "lua/?/init.lua"],
-  "diagnostics.globals": ["vim"],
+  "diagnostics.globals": ["vim", "jit"],
   "workspace.library": ["$VIMRUNTIME/lua", "${3rd}/luv/library"],
   "workspace.checkThirdParty": false,
   "completion.callSnippet": "Replace"

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Raphael
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,26 @@
+# http-codes.nvim
+
+Quickly investigate HTTP status codes with [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP), with telescope, fzf-lua, and snacks.nvim integrations.
+
+## Installation
+
+Install with your package manager or via
+[luarocks](https://luarocks.org/modules/barrettruth/http-codes.nvim):
+
+```
+luarocks install http-codes.nvim
+```
+
+## Dependencies
+
+One of:
+
+- [fzf-lua](https://github.com/ibhagwan/fzf-lua)
+- [snacks.nvim](https://github.com/folke/snacks.nvim)
+- [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim)
+
+## Documentation
+
+```vim
+:help http-codes.nvim
+```

doc/http-codes.txt

@@ -1,39 +1,53 @@
-http-codes                                                      *http-codes.txt*
+*http-codes* *http-codes.txt*
 
 Author: Barrett Ruth <https://barrettruth.com>
-Homepage: <https://github.com/barrettruth/http-codes.nvim>
+Homepage: <https://github.com/barrett-ruth/http-codes.nvim>
 
 ===============================================================================
 INTRODUCTION                                                 *http-codes.nvim*
 
-http-codes.nvim lets you quickly investigate HTTP status codes with Mozilla,
-supporting fzf-lua, snacks.nvim, and telescope.nvim.
+http-codes.nvim lets you quickly investigate HTTP status codes using Mozilla
+documentation, with telescope, fzf-lua, and snacks.nvim integrations.
 
 ===============================================================================
-CONFIGURATION                                              *http-codes.config*
+USAGE                                                            *:HTTPCodes*
+
+>vim
+    :HTTPCodes
+<
+
+===============================================================================
+MAPPINGS                                                *http-codes-mappings*
+
+                                                      *<Plug>(http-codes-pick)*
+<Plug>(http-codes-pick)     Open the HTTP status code picker.
+                            Equivalent to |:HTTPCodes|.
+
+Example configuration: >lua
+    vim.keymap.set('n', '<leader>hc', '<Plug>(http-codes-pick)')
+<
+
+===============================================================================
+CONFIGURATION                                             *vim.g.http_codes*
+
+Configure via `vim.g.http_codes`:
 
-Configure via `vim.g.http_codes` before the plugin loads:
 >lua
     vim.g.http_codes = {
+        -- Picker: 'fzf-lua', 'snacks', or 'telescope' (auto-detected)
         use = 'fzf-lua',
+        -- Command to open URLs (OS-specific by default)
         open_url = 'xdg-open %s',
     }
 <
-Options: ~
 
-    {use}       `(string|nil)`: Picker to use: 'fzf-lua', 'snacks', or
-                              'telescope'. Auto-detected if not specified.
+Default `open_url` by operating system:
 
-    {open_url}  `(string|nil)`: Command to open URLs. Uses `%s` as placeholder.
-                              Defaults based on OS:
-                              - Linux: 'xdg-open %s'
-                              - macOS: 'open %s'
-                              - Windows: 'start %s'
-
-===============================================================================
-COMMANDS                                                 *http-codes.commands*
-
-:HTTPCodes            Browse HTTP codes using the configured picker.
+    OS          Default
+    --------    ---------------
+    Windows     start %s
+    macOS       open %s
+    Linux       xdg-open %s
 
 -------------------------------------------------------------------------------
-vim:tw=80:ft=help:
+vim:tw=80:ts=8:ft=help:

lua/http-codes.lua

@@ -32,7 +32,10 @@ local function init()
   end
 
   if not config.use then
-    vim.notify_once('http-codes.nvim: install fzf-lua, snacks.nvim, or telescope.nvim', vim.log.levels.ERROR)
+    vim.notify_once(
+      'http-codes.nvim: install fzf-lua, snacks.nvim, or telescope.nvim',
+      vim.log.levels.ERROR
+    )
     return false
   end
 
@@ -70,7 +73,13 @@ M.http_codes = M.pick
 
 ---@deprecated Use `vim.g.http_codes` instead
 function M.setup(user_config)
-  vim.deprecate('require("http-codes").setup()', 'vim.g.http_codes', 'v0.1.0', 'http-codes.nvim', false)
+  vim.deprecate(
+    'require("http-codes").setup()',
+    'vim.g.http_codes',
+    'v0.1.0',
+    'http-codes.nvim',
+    false
+  )
 
   if user_config then
     vim.g.http_codes = vim.tbl_deep_extend('force', vim.g.http_codes or {}, user_config)

lua/http-codes/fzf-lua.lua

@@ -1,4 +1,4 @@
-local codes = require 'http-codes.codes'
+local codes = require('http-codes.codes')
 
 return {
   pick = function(open_url)

lua/http-codes/os.lua

@@ -4,14 +4,20 @@ local OS_TO_OPEN_URL = {
 }
 
 local function get_os()
-    if jit then return jit.os end
+  if jit then
+    return jit.os
+  end
 
   local fh, _ = assert(io.popen('uname -o 2>/dev/null', 'r'))
-    if fh then return fh:read() end
+  if fh then
+    return fh:read()
+  end
 
   return fh and fh:read() or 'Windows'
 end
 
 return {
-    get_open_url = function() return OS_TO_OPEN_URL[get_os()] or 'xdg-open %s' end,
+  get_open_url = function()
+    return OS_TO_OPEN_URL[get_os()] or 'xdg-open %s'
+  end,
 }

lua/http-codes/snacks.lua

@@ -1,13 +1,15 @@
-local codes = require 'http-codes.codes'
+local codes = require('http-codes.codes')
 local cached_items = nil
 
-local function codes_to_snack_items(codes)
-    if cached_items then return cached_items end
+local function codes_to_snack_items(codes_map)
+  if cached_items then
+    return cached_items
+  end
 
   local items = {}
 
   local idx = 1
-    for status, _ in pairs(codes) do
+  for status, _ in pairs(codes_map) do
     table.insert(items, { idx = idx, text = status })
     idx = idx + 1
   end

lua/http-codes/telescope.lua

@@ -1,3 +1,5 @@
 return {
-    setup = function() require('telescope').load_extension 'http' end,
+  setup = function()
+    require('telescope').load_extension('http')
+  end,
 }

lua/telescope/_extensions/http.lua

@@ -1,5 +1,5 @@
-local list = require 'telescope._extensions.http.list'
+local list = require('telescope._extensions.http.list')
 
-return require('telescope').register_extension {
+return require('telescope').register_extension({
   exports = { list = list },
-}
+})

lua/telescope/_extensions/http/list.lua

@@ -1,18 +1,18 @@
-local actions = require 'telescope.actions'
-local finders = require 'telescope.finders'
-local pickers = require 'telescope.pickers'
-local sorters = require 'telescope.sorters'
-local state = require 'telescope.actions.state'
+local actions = require('telescope.actions')
+local finders = require('telescope.finders')
+local pickers = require('telescope.pickers')
+local sorters = require('telescope.sorters')
+local state = require('telescope.actions.state')
 
-local codes = require 'http-codes.codes'
+local codes = require('http-codes.codes')
 
 return function(open_url)
   pickers
     .new(nil, {
       prompt_title = 'HTTP Codes',
-            finder = finders.new_table {
+      finder = finders.new_table({
         results = vim.tbl_keys(codes),
-            },
+      }),
       sorter = sorters.get_generic_fuzzy_sorter(),
       attach_mappings = function(prompt_bufnr, _)
         actions.select_default:replace(function()

plugin/http-codes.lua

@@ -6,3 +6,7 @@ vim.g.loaded_http_codes = 1
 vim.api.nvim_create_user_command('HTTPCodes', function()
   require('http-codes').pick()
 end, {})
+
+vim.keymap.set('n', '<Plug>(http-codes-pick)', function()
+  require('http-codes').pick()
+end, { desc = 'Pick HTTP status code' })

readme.md

@@ -1,47 +0,0 @@
-# http-codes.nvim
-
-Quickly investigate HTTP status codes with the help of [Mozilla](https://developer.mozilla.org/en-US/docs/Web/HTTP), with telescope, fzf-lua, and snacks.nvim integrations.
-
-## Installation
-
-Install using your package manager of choice or via [luarocks](https://luarocks.org/modules/barrettruth/http-codes.nvim):
-
-```
-luarocks install http-codes.nvim
-```
-
-## Dependencies
-
-One of:
-- [fzf-lua](https://github.com/ibhagwan/fzf-lua)
-- [snacks.nvim](https://github.com/folke/snacks.nvim)
-- [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim)
-
-## Configuration
-
-Configure via `vim.g.http_codes` before the plugin loads:
-
-```lua
-vim.g.http_codes = {
-  use = 'fzf-lua', -- or 'snacks' or 'telescope', auto-detected by default
-  open_url = 'xdg-open %s', -- OS-specific by default
-}
-```
-
-| OS      | Default open_url |
-| ------- | ---------------- |
-| Windows | `start %s`       |
-| macOS   | `open %s`        |
-| Linux   | `xdg-open %s`    |
-
-## Usage
-
-```vim
-:HTTPCodes
-```
-
-## Documentation
-
-```vim
-:help http-codes.nvim
-```