feat: allow function is config.cmd

and some docs update

Resolve #63

README.md

@@ -43,44 +43,54 @@ Following options can be provided when calling [`setup()`](#setup). Below is the
 
 ```lua
 {
-    -- Filetype of the terminal buffer
+    ---Filetype of the terminal buffer
+    ---@type string
     ft = 'FTerm',
 
-    -- Command to run inside the terminal. It could be a `string` or `table`
+    ---Command to run inside the terminal
+    ---NOTE: if given string[], it will skip the shell and directly executes the command
+    ---@type fun():(string|string[])|string|string[]
     cmd = os.getenv('SHELL'),
 
-    -- Neovim's native window border. See `:h nvim_open_win` for more configuration options.
+    ---Neovim's native window border. See `:h nvim_open_win` for more configuration options.
     border = 'single',
 
-    -- Close the terminal as soon as shell/command exits.
-    -- Disabling this will mimic the native terminal behaviour.
+    ---Close the terminal as soon as shell/command exits.
+    ---Disabling this will mimic the native terminal behaviour.
+    ---@type boolean
     auto_close = true,
 
-    -- Highlight group for the terminal. See `:h winhl`
+    ---Highlight group for the terminal. See `:h winhl`
+    ---@type string
     hl = 'Normal',
 
-    -- Transparency of the floating window. See `:h winblend`
+    ---Transparency of the floating window. See `:h winblend`
+    ---@type integer
     blend = 0,
 
-    -- Object containing the terminal window dimensions.
-    -- The value for each field should be between `0` and `1`
+    ---Object containing the terminal window dimensions.
+    ---The value for each field should be between `0` and `1`
+    ---@type table<string,number>
     dimensions = {
         height = 0.8, -- Height of the terminal window
         width = 0.8, -- Width of the terminal window
         x = 0.5, -- X axis of the terminal window
         y = 0.5, -- Y axis of the terminal window
     },
 
-    -- Callback invoked when the terminal exits.
-    -- See `:h jobstart-options`
+    ---Callback invoked when the terminal exits.
+    ---See `:h jobstart-options`
+    ---@type fun()|nil
     on_exit = nil,
 
-    -- Callback invoked when the terminal emits stdout data.
-    -- See `:h jobstart-options`
+    ---Callback invoked when the terminal emits stdout data.
+    ---See `:h jobstart-options`
+    ---@type fun()|nil
     on_stdout = nil,
 
-    -- Callback invoked when the terminal emits stderr data.
-    -- See `:h jobstart-options`
+    ---Callback invoked when the terminal emits stderr data.
+    ---See `:h jobstart-options`
+    ---@type fun()|nil
     on_stderr = nil,
 }
 ```
@@ -189,10 +199,10 @@ local gitui = fterm:new({
     }
 })
 
- -- Use this to toggle gitui in a floating terminal
-function _G.__fterm_gitui()
+-- Use this to toggle gitui in a floating terminal
+vim.keymap.set('n', '<A-g>', function()
     gitui:toggle()
-end
+end)
 ```
 
 Screenshot
@@ -210,9 +220,9 @@ local btop = fterm:new({
 })
 
  -- Use this to toggle btop in a floating terminal
-function _G.__fterm_btop()
+vim.keymap.set('n', '<A-b>', function()
     btop:toggle()
-end
+end)
 ```
 
 Screenshot

lua/FTerm/init.lua

@@ -48,7 +48,7 @@ function M.run(cmd)
 end
 
 ---To create a scratch (use and throw) terminal. Like those good ol' C++ build terminal.
----@param cfg Command
+---@param cfg Config
 function M.scratch(cfg)
     if not cfg then
         return vim.notify('FTerm: Please provide configuration for scratch terminal', vim.log.levels.ERROR)

lua/FTerm/terminal.lua

@@ -10,7 +10,7 @@ local cmd = A.nvim_command
 ---@class Term
 ---@field win WinId
 ---@field buf BufId
----@field terminal number Terminal's job id
+---@field terminal? number Terminal's job id
 ---@field config Config
 local Term = {}
 
@@ -33,7 +33,7 @@ function Term:setup(cfg)
     end
 
     self.config = vim.tbl_deep_extend('force', self.config, cfg)
-    self.config.cmd = U.build_cmd(self.config.cmd)
+    self.config.cmd = U.is_cmd(self.config.cmd)
 
     return self
 end
@@ -180,7 +180,7 @@ function Term:open()
 end
 
 ---Term:close does all the magic of closing terminal and clearing the buffers/windows
----@param force boolean If true, kill the terminal otherwise hide it
+---@param force? boolean If true, kill the terminal otherwise hide it
 ---@return Term
 function Term:close(force)
     if not U.is_win_valid(self.win) then
@@ -228,7 +228,7 @@ function Term:run(command)
 
     A.nvim_chan_send(
         self.terminal,
-        string.format('%s%s', U.build_cmd(command), A.nvim_replace_termcodes('<CR>', true, true, true))
+        string.format('%s%s', U.is_cmd(command), A.nvim_replace_termcodes('<CR>', true, true, true))
     )
 
     return self

lua/FTerm/utils.lua

@@ -76,9 +76,9 @@ end
 
 ---Creates a valid command from user's input
 ---@param cmd Command
----@return string
-function U.build_cmd(cmd)
-    return type(cmd) == 'table' and table.concat(cmd, ' ') or cmd
+---@return Command
+function U.is_cmd(cmd)
+    return type(cmd) == 'function' and cmd() or cmd --[[ @as string|string[] ]]
 end
 
 return U