feat: default configurations (#19)

Co-authored-by: benlubas <[email protected]>

README.md

@@ -43,6 +43,7 @@ If you want to quickly understand the concept, you can watch
 - [Installation](#installation)
 - [Creating a New Hydra](#creating-a-new-hydra)
 - [Config](#config)
+  - [Default Configuration](#default-configuration)
 - [Hint](#hint)
   - [Hint Configuration](#hint-configuration)
 - [Heads](#heads)
@@ -149,6 +150,37 @@ config = {
 }
 ```
 
+### Default Configuration
+
+The above discusses per-hydra configuration. But Hydra.nvim also allows you to set default
+values for the `config` table. These defaults are automatically applied to new hydras, but
+can still be overridden on a per-hydra basis.
+
+This is useful for setting config that you want to apply to all of your hydras, like
+common floating window borders, or common hooks.
+
+_Only applies to hydras that are created after you call the setup method_
+
+```lua
+require('hydra').setup({
+    debug = false,
+    exit = false,
+    foreign_keys = nil,
+    color = "red",
+    timeout = false,
+    invoke_on_body = false,
+    hint = {
+        show_name = true,
+        position = { "bottom" },
+        offset = 0,
+        float_opts = { },
+    },
+    on_enter = nil,
+    on_exit = nil,
+    on_key = nil,
+})
+```
+
 ## Hint
 
 The hint for a hydra can let you know that it's active, and remind you of the hydra's

doc/hydra.txt

@@ -1,4 +1,4 @@
-*hydra.txt*            For NVIM v0.9.4           Last change: 2023 December 31
+*hydra.txt*            For NVIM v0.9.4            Last change: 2024 January 06
 
 ==============================================================================
 Table of Contents                                    *hydra-table-of-contents*
@@ -8,6 +8,7 @@ Table of Contents                                    *hydra-table-of-contents*
 3. Installation                                           |hydra-installation|
 4. Creating a New Hydra                           |hydra-creating-a-new-hydra|
 5. Config                                                       |hydra-config|
+  - Default Configuration                 |hydra-config-default-configuration|
 6. Hint                                                           |hydra-hint|
   - Hint Configuration                         |hydra-hint-hint-configuration|
 7. Heads                                                         |hydra-heads|
@@ -156,6 +157,38 @@ With this table, you can set the behavior of the whole hydra.
 <
 
 
+DEFAULT CONFIGURATION                     *hydra-config-default-configuration*
+
+The above discusses per-hydra configuration. But Hydra.nvim also allows you to
+set default values for the `config` table. These defaults are automatically
+applied to new hydras, but can still be overridden on a per-hydra basis.
+
+This is useful for setting config that you want to apply to all of your hydras,
+like common floating window borders, or common hooks.
+
+_Only applies to hydras that are created after you call the setup method_
+
+>lua
+    require('hydra').setup({
+        debug = false,
+        exit = false,
+        foreign_keys = nil,
+        color = "red",
+        timeout = false,
+        invoke_on_body = false,
+        hint = {
+            show_name = true,
+            position = { "bottom" },
+            offset = 0,
+            float_opts = { },
+        },
+        on_enter = nil,
+        on_exit = nil,
+        on_key = nil,
+    })
+<
+
+
 ==============================================================================
 6. Hint                                                           *hydra-hint*
 

lua/hydra/init.lua

@@ -25,18 +25,17 @@ local Hydra = class()
 
 ---@type hydra.Config
 local default_config = {
-   debug = false,
-   exit = false,
-   foreign_keys = nil,
-   color = 'red',
-   timeout = false,
-   invoke_on_body = false,
-   hint = {
-      show_name = true,
-      position = { 'bottom' },
-      offset = 0,
-      border = nil,
-   }
+  debug = false,
+  exit = false,
+  foreign_keys = nil,
+  color = "red",
+  timeout = false,
+  invoke_on_body = false,
+  hint = {
+    show_name = true,
+    position = { "bottom" },
+    offset = 0,
+  },
 }
 
 ---@param input table
@@ -107,6 +106,7 @@ function Hydra:initialize(input)
    self.heads = {}
    self.options = options('hydra.options')
    self.plug_wait = string.format('<Plug>(Hydra%d_wait)', self.id)
+
    self.config = util.merge_config(default_config, input.config or {})
    util.process_deprecations(self.config)
    do
@@ -523,4 +523,10 @@ function Hydra:debug(...)
    end
 end
 
+--- Change the default configuration
+--- @param opts hydra.OptionalConfig
+function Hydra.setup(opts)
+  default_config = vim.tbl_deep_extend("force", default_config, opts)
+end
+
 return Hydra

lua/hydra/lib/types.lua

@@ -16,15 +16,38 @@
 ---@field timeout boolean | number  Number of milliseconds
 ---@field hint hydra.hint.Config | false
 
+---@class hydra.OptionalConfig
+---@field debug? boolean
+---@field desc? string
+---@field buffer? integer
+---@field exit? boolean
+---@field foreign_keys? hydra.foreign_keys
+---@field color? hydra.color
+---@field on_enter? function  Before entering hydra
+---@field on_exit? function   After leaving hydra
+---@field on_key? function    After every hydra head
+---@field invoke_on_body? boolean
+---@field timeout? boolean | number  Number of milliseconds
+---@field hint? hydra.hint.OptionalConfig | false
+
 ---@class hydra.hint.Config
----@field type 'statusline' | 'cmdline' | 'window'
+---@field type 'statusline' | 'cmdline' | 'window' | nil
 ---@field position hydra.hint.Config.position
 ---@field offset integer
 ---@field border? string | table -- deprecated, use `float_opts.border`
 ---@field float_opts? table
 ---@field funcs? table<string, fun():string>
 ---@field show_name boolean
 
+---@class hydra.hint.OptionalConfig
+---@field type 'statusline' | 'cmdline' | 'window' | nil
+---@field position? hydra.hint.Config.position
+---@field offset? integer
+---@field border? string | table -- deprecated, use `float_opts.border`
+---@field float_opts? table
+---@field funcs? table<string, fun():string>
+---@field show_name? boolean
+
 ---@class hydra.hint.Config.position
 ---@field [1] 'top' | 'middle' | 'bottom'
 ---@field [2]? 'left' | 'right'