Merge pull request #8 from dpi0/feat/add-position-option

!Add position option with 6 configurable positions (replaces mode)
itmecho · Sep 26, 2024 · 7ef5dec · 7ef5dec
2 parents b0a6901 + 6d08cbf
commit 7ef5dec
Show file tree

Hide file tree

Showing 4 changed files with 237 additions and 44 deletions.
diff --git a/README.md b/README.md
@@ -28,17 +28,18 @@ The following functions are available on the neoterm module. They map directly t
 ```lua
 -- Setup global config
 require('neoterm').setup({
-	clear_on_run = true, -- run clear command before user specified commands
-	mode = 'vertical',   -- vertical/horizontal/fullscreen
-	noinsert = false     -- disable entering insert mode when opening the neoterm window
+  clear_on_run = true, -- Run clear command before user specified commands
+  position = 'right',  -- Position of the terminal window: fullscreen (0), top (1), right (2), bottom (3), left (4), center (5) (string or integer value)
+  noinsert = false,    -- Disable entering insert mode when opening the neoterm window
+  width = 0.5,         -- Width of the terminal window (percentage, ratio, or range between 0-1)
+  height = 1,          -- Height of the terminal window (percentage, ratio, or range between 0-1)
 })
 
-
 local neoterm = require('neoterm')
 
 neoterm.open()
 -- Override global config on a specific open call
-neoterm.open({ mode = 'horizontal', noinsert = true})
+neoterm.open({ position = 'bottom', noinsert = true, width = 0.7, height = 0.3 })
 neoterm.close()
 neoterm.toggle()
 neoterm.run('ls')
@@ -62,22 +63,60 @@ tnoremap <leader>tx <cmd>NeotermExit<CR>
 
 # Screenshots
 
-## Vertical (default)
+## Right (default)
 ```lua
 require('neoterm').open()
 -- or
-require('neoterm').open({mode ='vertical'})
+require('neoterm').open({ position = 'right' })
+-- or
+require('neoterm').open({ position = 2 })
+```
+![position-right](https://github.com/user-attachments/assets/f60ded98-8be4-4dd6-a77b-757ece4f5d84)
+
+## Top
+```lua
+require('neoterm').open({ position = 'top', height = 0.6 })
 ```
-![image](https://user-images.githubusercontent.com/8384983/126306361-353a61ad-dfa3-4a16-b9f3-0cc8a6a258f6.png)
+![position-top](https://github.com/user-attachments/assets/3aba21d5-b0b2-4250-a415-cc478916c90a)
 
-## Horizontal
+## Bottom
 ```lua
-require('neoterm').open({mode ='horizontal'})
+require('neoterm').open({ position = 'bottom' })
+--or
+require('neoterm').open({ position = 3 })
 ```
-![image](https://user-images.githubusercontent.com/8384983/126306318-bd1c43e4-154a-4a52-9eff-d77dc683c38c.png)
+![position-bottom](https://github.com/user-attachments/assets/4c3f557c-44ca-4894-a75d-ef45a3943942)
+
+## Left
+```lua
+require('neoterm').open({ position = 'left', width = 0.7 })
+```
+![position-left](https://github.com/user-attachments/assets/812a7d5b-31ed-4061-9bc8-93236b0763f4)
+
+## Center
+```lua
+require('neoterm').open({ position = 'left', width = 0.6, height = 0.6 })
+```
+![position-center](https://github.com/user-attachments/assets/4cbbf668-c7d4-43ee-a9a6-2e5a6ba3b9fb)
 
 ## Fullscreen
 ```lua
-require('neoterm').open({mode ='fullscreen'})
+require('neoterm').open({ position = 'fullscreen' })
+-- or
+require('neoterm').open({ position = 0 })
 ```
-![image](https://user-images.githubusercontent.com/8384983/126306383-192ea5a2-7d5b-4267-a3b7-9cee0751c44a.png)
+![position-fullscreen](https://github.com/user-attachments/assets/9423e593-2c86-48aa-8cba-49024c38e3be)
+
+
+## Deprecation Notice
+
+> [!WARNING]
+> The `mode` option is deprecated. Please use the new `position` option instead.
+
+#### Migration Guide
+
+- `mode = vertical` → `position = right`
+
+- `mode = horizontal` → `position = bottom`
+
+- `mode = fullscreen` → `position = fullscreen`
diff --git a/doc/neoterm.txt b/doc/neoterm.txt
@@ -1,9 +1,10 @@
-*neoterm.txt*                                         Last change: 2022 June 14
+*neoterm.txt*                                         Last change: 2024 September 25
 ==============================================================================
 CONTENTS                                                              *neoterm*
 
   1. Commands ....... |neoterm-commands|
   2. Events ......... |neoterm-events|
+  3. Configuration .. |neoterm-configuration|
 
 ==============================================================================
 Section 1: Commands                                          *neoterm-commands*
@@ -43,14 +44,58 @@ NeotermWinOpen
 
                                                               *NeotermWinClose*
 NeotermWinClose
-    Fired when the neoterm window is opened.
+    Fired when the neoterm window is closed.
 
                                                              *NeotermTermEnter*
 NeotermTermEnter
-    Fired when the entering Terminal Mode in the Neoterm buffer.
+    Fired when entering Terminal Mode in the Neoterm buffer.
 
                                                              *NeotermTermLeave*
 NeotermTermLeave
-    Fired when the leaving Terminal Mode in the Neoterm buffer.
+    Fired when leaving Terminal Mode in the Neoterm buffer.
+
+==============================================================================
+Section 3: Configuration                                  *neoterm-configuration*
+
+The neoterm plugin can be configured using the `setup` function. The following
+options are available:
+
+                                                                 *neoterm-setup*
+:lua require('neoterm').setup({options})
+
+    Configure the neoterm plugin with the given options.
+
+    Options:
+
+    clear_on_run (boolean)
+        Run the clear command before user specified commands. Default: true.
 
-vim:textwidth=78:tabstop=4:expandtab:shiftwidth=4:filetype=help:
+    position (string)
+        Position of the terminal window. Possible values:
+        - 'fullscreen'
+        - 'top'
+        - 'right' (default)
+        - 'bottom'
+        - 'left'
+        - 'center'
+
+    noinsert (boolean)
+        Disable entering insert mode when opening the neoterm window. Default: false.
+
+    width (number or string)
+        Width of the terminal window. Can be a number between 0 and 1 or a percentage string (e.g., '50%'). Default: 0.5.
+
+    height (number or string)
+        Height of the terminal window. Can be a number between 0 and 1 or a percentage string (e.g., '50%'). Default: 1.
+
+    Deprecation Notice:
+    The `mode` option is deprecated. Please use the `position` option instead.
+    The `mode` option will be removed in future versions.
+
+    Migration Guide:
+    - 'vertical' → 'right'
+    - 'horizontal' → 'bottom'
+    - 'fullscreen' → 'fullscreen'
+
+==============================================================================
+vim:textwidth=78:tabstop=4:expandtab:shiftwidth=4:filetype=help:
diff --git a/doc/tags b/doc/tags
@@ -9,5 +9,6 @@ NeotermWinClose	neoterm.txt	/*NeotermWinClose*
 NeotermWinOpen	neoterm.txt	/*NeotermWinOpen*
 neoterm	neoterm.txt	/*neoterm*
 neoterm-commands	neoterm.txt	/*neoterm-commands*
+neoterm-configuration	neoterm.txt	/*neoterm-configuration*
 neoterm-events	neoterm.txt	/*neoterm-events*
-neoterm.txt	neoterm.txt	/*neoterm.txt*
+neoterm.txt	neoterm.txt	/*neoterm.txt*