rest-nvim.txt

*rest-nvim.txt* A fast Neovim http client written in Lua based on curl

             ______                                _        ~
            (_____ \              _               (_)       ~
             _____) )_____  ___ _| |_   ____ _   _ _ ____   ~
            |  __  /| ___ |/___|_   _) |  _ \ | | | |    \  ~
            | |  \ \| ____|___ | | |_ _| | | \ V /| | | | | ~
            |_|   |_|_____|___/   \__|_)_| |_|\_/ |_|_|_|_| ~


 NTBBloodbath                                                      *rest-nvim*

===============================================================================
CONTENTS                                                   *rest-nvim-contents*
    1. Introduction...........................................|rest-nvim-intro|
    2. Features............................................|rest-nvim-features|
    3. Quick start......................................|rest-nvim-quick-start|
    4. Usage..................................................|rest-nvim-usage|
        1. Commands..................................|rest-nvim-usage-commands|
        2. Requests..................................|rest-nvim-usage-requests|
        3. Import body from external file......|rest-nvim-usage-external-files|
        4. Environment Variables........|rest-nvim-usage-environment-variables|
        5. Dynamic Variables................|rest-nvim-usage-dynamic-variables|
    5. Known issues..........................................|rest-nvim-issues|
    6. License..............................................|rest-nvim-license|
    7. Contributing....................................|rest-nvim-contributing|


===============================================================================
INTRODUCTION                                                  *rest-nvim-intro*

`rest.nvim` is a fast Neovim http client written in Lua which makes use of a
curl wrapper made in pure Lua by github.com/tami5 and implemented in the
plugin `plenary.nvim` so, in other words, `rest.nvim` is a curl wrapper so you
don't have to leave Neovim!


===============================================================================
FEATURES                                                   *rest-nvim-features*

- Easy to use
- Fast execution time
- Run request under cursor
- Syntax highlight for http files and output
- Possibility of using environment variables in http files


===============================================================================
QUICK START                                             *rest-nvim-quick-start*

After installing `rest.nvim` you will need to configure it using a `setup`
function, it looks like this by default:

`require("rest-nvim").setup({`
`  -- Open request results in a horizontal split`
`  result_split_horizontal = false,`
`  -- Skip SSL verification, useful for unknown certificates`
`  skip_ssl_verification = false,`
`  -- Highlight request on run`
`  highlight = {`
`      enabled = true,`
`      timeout = 150,`
`  },`
`  -- Jump to request line on run`
`  jump_to_request = false,`
`  env_file = '.env'`
`})`

In this section we will be using `https://reqres.in/` for requests.

Let's say we want to create a new user and send our body as a JSON, so we
will do the following:

    1. We declare the HTTP method to use followed by the URL.
       `POST https://reqres.in/api/users`

    2. Since we want to send our body as a JSON object, we set the
       Content-Type header.
       `Content-Type: application/json`

    3. Now, we set the body of our request.
       `{`
       `    "name": "morpheus",`
       `    "job": "leader"`
       `}`

    4. Finally, we place the cursor over or below the method of our request 
       and call `rest.nvim` with `:lua require('rest-nvim').run()`.

Since the way to call rest.nvim with Lua is not comfortable, rest.nvim
exposes a command to be mapped. See |rest-nvim-usage-commands|


===============================================================================
USAGE                                                         *rest-nvim-usage*

Create a new http file or open an existing one and place the cursor over the
request line (e.g. `GET http://localhost:3000/foo`) or below and run `rest.nvim`
(see |rest-nvim-usage-commands|).

Notes:
    - `rest.nvim` follows the RFC 2616 request format so any other http file
      should work without problems.
    - `rest.nvim` supports multiple http requests in one file. It selects the
      nearest request in or above the current cursor line.


===============================================================================
COMMANDS                                             *rest-nvim-usage-commands*

- `<Plug>RestNvim`
  Run `rest.nvim` in the current cursor position.

- `<Plug>RestNvimPreview`
  Same as `RestNvim` but it returns the cURL command without executing the
  request. Intended for debugging purposes.


===============================================================================
REQUESTS                                             *rest-nvim-usage-requests*

Currently `rest.nvim` supports the following request methods:

    - GET
    - POST
    - DELETE
    - PATCH
    - PUT


===============================================================================
IMPORT BODY FROM EXTERNAL FILE                 *rest-nvim-usage-external-files*

`rest.nvim` allows the http file to import the body from an external file.

The syntax is `< path/to/file.json`. `rest.nvim` supports absolute and relative
paths to the external file.


===============================================================================
ENVIRONMENT VARIABLES                   *rest-nvim-usage-environment-variables*

`rest.nvim` allows the use of environment variables in requests.

To use environment variables, the following syntax is used: `{{VARIABLE_NAME}}`

These environment variables can be obtained from:
    - File in the current working directory (env_file in config or '.env')
    - System


===============================================================================
DYNAMIC VARIABLES                           *rest-nvim-usage-dynamic-variables*

`rest.nvim` allows the use of dynamic variables in requests.

The following dynamic variables are currenty supported:
    - $uuid: generates a universally unique identifier (UUID-v4)
    - $timestamp: generates the current UNIX timestamp (seconds since epoch)
    - $randomInt: generates a random integer between 0 and 1000

To use dynamic variables, the following syntax is used: `{{DYNAMIC_VARIABLE}}`, 
e.g. `{{$uuid}}`


===============================================================================
KNOWN ISSUES                                                 *rest-nvim-issues*

    - Nothing here at the moment :)


===============================================================================
LICENSE                                                     *rest-nvim-license*

rest.nvim is distributed under MIT License.

Copyright (c) 2021 NTBBloodbath

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.


===============================================================================
CONTRIBUTING                                           *rest-nvim-contributing*

    1. Fork it (`github.com/NTBBloodbath/rest.nvim/fork`)
    2. Create your feature branch (`git checkout -b my-new-feature`)
    3. Commit your changes (`git commit -am 'Add some feature'`)
    4. Push to the branch (`git push origin my-new-feature`)
    5. Create a new Pull Request