docs: document the code

Author: boltlessengineer

Makefile

@@ -12,8 +12,9 @@ test:
 	luarocks test --local
 
 docgen:
-	lemmy-help lua/rest-nvim/client/curl.lua > doc/rest-nvim-curl.txt
 	lemmy-help lua/rest-nvim/commands.lua > doc/rest-nvim-commands.txt
 	lemmy-help lua/rest-nvim/config/init.lua > doc/rest-nvim-config.txt
-	lemmy-help lua/rest-nvim/parser/dynamic_vars.lua lua/rest-nvim/parser/env_vars.lua lua/rest-nvim/parser/script_vars.lua lua/rest-nvim/parser/init.lua > doc/rest-nvim-parser.txt
-	lemmy-help lua/rest-nvim/api.lua lua/rest-nvim/utils.lua lua/rest-nvim/functions.lua lua/rest-nvim/logger.lua lua/rest-nvim/result/init.lua lua/rest-nvim/result/winbar.lua lua/rest-nvim/result/help.lua > doc/rest-nvim-api.txt
+	lemmy-help lua/rest-nvim/cookie_jar.lua > doc/rest-nvim-cookies.txt
+	lemmy-help lua/rest-nvim/script.lua > doc/rest-nvim-script.txt
+	lemmy-help lua/rest-nvim/api.lua lua/rest-nvim/utils.lua > doc/rest-nvim-api.txt
+	lemmy-help lua/rest-nvim/client/curl/cli.lua lua/rest-nvim/client/curl/utils.lua > doc/rest-nvim-client-curl.txt

README.md

@@ -32,12 +32,13 @@ CLI. For more information on this, please see this [blog post](https://amartin.c
 ## Features
 
 - Easy to use
-- Friendly and organized request results window
+- Friendly, organized and featureful request results window
 - Fast runtime with statistics about your request
 - Set custom pre-request and post-request hooks to dynamically interact with the data
 - Easily set environment variables based on the response to re-use the data later
 - Tree-sitter based parsing and syntax highlighting for speed and perfect accuracy
 - Possibility of using dynamic/environment variables and Lua scripting in HTTP files
+- Save received cookies and load them automatically
 
 ## Install
 
@@ -208,12 +209,12 @@ request and run the <kbd>:Rest run</kbd> command.
 >    request in the current cursor line, no matters the position as long as
 >    the cursor is on a request tree-sitter node.
 
-## Keybindings
+### Keybindings
 
 By default `rest.nvim` does not have any key mappings except the result buffers so you will not have
 conflicts with any of your existing ones.
 
-## Commands
+### Commands
 
 | User Command           | Behavior                                             |
 |------------------------|------------------------------------------------------|
@@ -227,6 +228,8 @@ conflicts with any of your existing ones.
 | `:Rest env select`     | Select & register `.env` file with `vim.ui.select()` |
 | `:Rest env set {path}` | Register `.env` file to current `.http` file         |
 
+See `:h rest-nvim.commands` for more info
+
 ## Extensions
 
 ### Telescope Extension

doc/rest-nvim-api.txt

@@ -45,35 +45,30 @@ api.register_rest_subcommand({name}, {cmd})
         {cmd}   (RestCmd)
 
 
-                                                     *api.register_rest_keybind*
-api.register_rest_keybind({mode}, {lhs}, {cmd}, {opts})
-
-
-    Parameters: ~
-        {mode}  (string)  Keybind mode
-        {lhs}   (string)  Keybind trigger
-        {cmd}   (string)  Command to be run
-        {opts}  (table)   Keybind options
-
-
 ==============================================================================
 rest.nvim utilities                                            *rest-nvim.utils*
 
 
  rest.nvim utility functions
 
 
-utils.escape({str})                                               *utils.escape*
+utils.escape({str}, {only_necessary?})                            *utils.escape*
     Encodes a string into its escaped hexadecimal representation
-    taken from Lua Socket and added underscore to ignore
 
     Parameters: ~
-        {str}  (string)  Binary string to be encoded
+        {str}              (string)   Binary string to be encoded
+        {only_necessary?}  (boolean)  Encode only necessary characters
 
     Returns: ~
         (string)
 
 
+utils.url_decode({str})                                       *utils.url_decode*
+
+    Parameters: ~
+        {str}  (string)
+
+
 utils.file_exists({path})                                    *utils.file_exists*
     Check if a file exists in the given `path`
 
@@ -94,250 +89,66 @@ utils.read_file({path})                                        *utils.read_file*
         (string)
 
 
-                                                               *utils.highlight*
-utils.highlight({bufnr}, {start}, {end_}, {ns})
-    Highlight a request
-
-    Parameters: ~
-        {bufnr}  (number)  Buffer handler ID
-        {start}  (number)  Request tree-sitter node start
-        {end_}   (number)  Request tree-sitter node end
-        {ns}     (number)  rest.nvim Neovim namespace
-
-
-==============================================================================
-rest.nvim functions                                        *rest-nvim.functions*
-
+utils.parse_http_time()                                  *utils.parse_http_time*
 
- rest.nvim functions
 
-
-functions.exec({scope})                                         *functions.exec*
-    Execute one or several HTTP requests depending on given `scope`
-    and return request(s) results in a table that will be used to render results
-    in a buffer.
-
-    Parameters: ~
-        {scope}  (string)  Defines the request execution scope. Can be: `last`, `cursor` (default) or `document`
-
-
-functions.find_env_files()                            *functions.find_env_files*
-    Find a list of environment files starting from the current directory
-
-    Returns: ~
-        (string[])  variable files path
-
-
-functions.env({action}, {path})                                  *functions.env*
-    Manage the environment file that is currently in use while running requests
-
-    If you choose to `set` the environment, you must provide a `path` to the environment file.
+                                                       *utils.ts_highlight_node*
+utils.ts_highlight_node({bufnr}, {node}, {ns})
 
     Parameters: ~
-        {action}  (string|nil)  Determines the action to be taken. Can be: `set` or `show` (default)
-        {path}    (string|nil)  Path to the environment variables file
+        {bufnr}  (number)
+        {node}   (TSNode)
+        {ns}     (number)
 
 
-functions.cycle_result_pane({cycle})               *functions.cycle_result_pane*
-    Cycle through the results buffer winbar panes
+utils.ts_parse_source({source})                          *utils.ts_parse_source*
 
     Parameters: ~
-        {cycle}  (string)  Cycle direction, can be: `"next"` or `"prev"`
-
-
-==============================================================================
-rest.nvim logger                                              *rest-nvim.logger*
-
-
-Logging library for rest.nvim, slightly inspired by rmagatti/logger.nvim
-Intended for use by internal and third-party modules.
-
-Default logger instance is made during the `setup` and can be accessed
-by anyone through the `_G._rest_nvim.logger` configuration field
-that is set automatically.
-
-------------------------------------------------------------------------------
-
-Usage:
-
-```lua
-local logger = require("rest-nvim.logger"):new({ level = "debug" })
-
-logger:set_log_level("info")
-
-logger:info("This is an info log")
- -- [rest.nvim] INFO: This is an info log
-```
-
-
-Logger                                                                  *Logger*
-
-
-LoggerLevels                                                      *LoggerLevels*
-
-
-LoggerConfig                                                      *LoggerConfig*
-
-    Fields: ~
-        {level_name}  (string)   Logging level name. Default is `"info"`
-        {save_logs}   (boolean)  Whether to save log messages into a `.log` file. Default is `true`
-
-
-logger:new({opts})                                                  *logger:new*
-    Create a new logger instance
-
-    Parameters: ~
-        {opts}  (LoggerConfig)  Logger configuration
+        {source}  (string|integer)
 
     Returns: ~
-        (Logger)
-
-
-logger:set_log_level({level})                             *logger:set_log_level*
-    Set the log level for the logger
-
-    Parameters: ~
-        {level}  (string)  New logging level
-
-    See: ~
-        |vim.log.levels|
-
-
-logger:trace({msg})                                               *logger:trace*
-    Log a trace message
-
-    Parameters: ~
-        {msg}  (string)  Log message
+        (vim.treesitter.LanguageTree)
+        (TSTree)
 
 
-logger:debug({msg})                                               *logger:debug*
-    Log a debug message
+utils.ts_find({node}, {type})                                    *utils.ts_find*
 
     Parameters: ~
-        {msg}  (string)  Log message
+        {node}  (TSNode)
+        {type}  (string)  @return TSNode?
 
 
-logger:info({msg})                                                 *logger:info*
-    Log an info message
+                                                            *utils.ts_node_spec*
+utils.ts_node_spec({node}, {expected_type})
 
     Parameters: ~
-        {msg}  (string)  Log message
-
-
-logger:warn({msg})                                                 *logger:warn*
-    Log a warning message
-
-    Parameters: ~
-        {msg}  (string)  Log message
-
-
-logger:error({msg})                                               *logger:error*
-    Log an error message
-
-    Parameters: ~
-        {msg}  (string)  Log message
-
-
-==============================================================================
-rest.nvim result buffer                                       *rest-nvim.result*
-
-
- rest.nvim result buffer handling
-
-
-result.bufnr                                                      *result.bufnr*
-    Results buffer handler number
-
-    Type: ~
-        (number|nil)
-
-
-result.get_or_create_buf()                            *result.get_or_create_buf*
+        {node}           (TSNode)
+        {expected_type}  (string)
 
     Returns: ~
-        (number)  handler number
-
-
-result.write_block()                                        *result.write_block*
-
-    See: ~
-        |vim.api.nvim_buf_set_lines|
-
-
-result.display_buf({bufnr}, {stats})                        *result.display_buf*
-    Display results buffer window
-
-    Parameters: ~
-        {bufnr}  (number)  The target buffer
-        {stats}  (table)   Request statistics
-
+        (table)
 
-result.write_res({bufnr}, {res})                              *result.write_res*
-    Write request results in the given buffer and display it
-
-    Parameters: ~
-        {bufnr}  (number)  The target buffer
-        {res}    (table)   Request results
-
-
-==============================================================================
-rest.nvim result buffer winbar add-on                  *rest-nvim.result.winbar*
-
-
- rest.nvim result buffer winbar
 
-
-winbar.current_pane_index                            *winbar.current_pane_index*
-    Current pane index in the results window winbar
-
-    Type: ~
-        (number)
-
-
-winbar.get_content({stats})                                 *winbar.get_content*
-    Create the winbar contents and return them
+utils.ts_node_error_log({node})                        *utils.ts_node_error_log*
+    Create error log for TSNode that has a syntax error
 
     Parameters: ~
-        {stats}  (table)  Request statistics
+        {node}  (TSNode)  Tree-sitter node
 
     Returns: ~
         (string)
 
 
-ResultPane                                                          *ResultPane*
-
-    Fields: ~
-        {name}      (string)    Pane name
-        {contents}  (string[])  Pane contents
-
-
-winbar.set_hl()                                                  *winbar.set_hl*
-    Set the results window winbar highlighting groups
-
-
-winbar.set_pane({selected})                                    *winbar.set_pane*
-    Select the winbar panel based on the pane index and set the pane contents
-
-    If the pane index is higher than 4 or lower than 1, it will cycle through
-    the panes, e.g. >= 5 gets converted to 1 and <= 0 gets converted to 4
+                                                        *utils.nvim_lazy_set_wo*
+utils.nvim_lazy_set_wo({bufnr}, {name}, {value})
+    Set window-option to specific buffer
+    Some options leaves in `vim.wo` while they are actually tied to buffers
+    see: <https://github.com/neovim/neovim/issues/11525> and `:h local-options`
 
     Parameters: ~
-        {selected}  (number)  winbar pane index
-
-
-==============================================================================
-rest.nvim result buffer help                             *rest-nvim.result.help*
-
-
- rest.nvim result buffer help window handling
-
-
-help.open()                                                          *help.open*
-    Open the request results help window
-
-
-help.close()                                                        *help.close*
-    Close the request results help window
+        {bufnr}  (number)
+        {name}   (string)
+        {value}  (any)
 
 
 vim:tw=78:ts=8:noet:ft=help:norl: