feat(parser): shared block

Author: YaroSpace

NEWS.md

@@ -2,6 +2,7 @@
 
 ## Version 5.3.4
 
+### Feature: `Shared blocks` [Shared blocks](usage/shared-blocks.md)
 ### Enhancement: add `winbar_labels` and `winbar_labels_keymaps` config options to customize winbar labels [Configuration](getting-started/configuration-options.mdx)
 ### Feature: support for `custom_dynamic_variables`
 ### Feature: support `run` command with metadata and without URL [Import and Run](usage/import-and-run-http.md)

docs/docs/getting-started/configuration-options.mdx

@@ -147,6 +147,13 @@ Example:
 }
 ```
 
+### variables_scope
+
+Set variable scope: "document" - variables shared across all requests in the document, no matter where they are defined, later declarations shadow earlier ones.
+"request" - variables scoped to the request they are defined in, variables in Shared block are immutable.
+
+Default: `document`
+
 ### custom_dynamic_variables
 
 Define your own dynamic variables here, e.g. $randomEmail

docs/docs/usage/shared-blocks.md

@@ -0,0 +1,76 @@
+# Shared Blocks
+
+Shared blocks can be used to share variables, metadata, scripts and requests between multiple requests. 
+
+To declare a shared block, use the `### Shared` or `### Shared each` request name. 
+
+Shared variables and metadata will apply to all requests that follow the shared block.  
+Variables and metadata declared in a request will shadow shared variables and metadata.
+
+Scripts and requests declared in the shared block and called with `run` command will be executed before the request you run.
+
+## `### Shared` block
+
+-  When executing `run request`, the shared scripts and requests will be executed before the request you run.
+-  When executing `run all requests`, the shared scripts and requests will be executed `once` before all requests.
+
+## `### Shared each` block
+
+-  When executing `run request`, the shared scripts and requests will be executed before the request you run.
+-  When executing `run all requests`, the shared scripts and requests will be executed before `each` request.
+
+## Variable Scope
+
+By default variables are scoped to `document`, which means they are shared across all requests in the document 
+and later declarations will override previous ones, including the ones in shared blocks.
+
+You can change the scope to `variables_scope = "request"` in the options, which will make variables scoped to the current request only 
+and shared variables will not be overridden by request variables.
+
+```http
+### Shared
+
+@shared_var_1 = shared_value_1
+@shared_var_2 = shared_value_2
+
+# @curl-connect-timeout 20
+# @curl-location
+
+run ./login.http
+
+< {%
+  console.log("pre request 0");
+%}
+
+< ./pre_request.js
+
+POST https://httpbin.org/post HTTP/1.1
+Content-Type: application/json
+
+{
+  "shared_var_1": 1,
+  "shared_var_2": 2
+}
+
+> ./post_request.js
+
+> {%
+  console.log("post request 0");
+%}
+
+
+### request 1
+
+@local_var_1 = local_value_1
+@shared_var_2 = local_value_2
+
+# @curl-connect-timeout 10
+
+POST https://httpbin.org/post HTTP/1.1
+Content-Type: application/json
+
+{
+  "shared_var_1": 3,
+  "shared_var_2": 4
+}
+```

docs/docs/usage/using-variables.md

@@ -38,3 +38,10 @@ you will be prompted to enter a value for `pokemon`.
 
 These variables are available for the current request and
 all subsequent requests in the file.
+
+## Variables scope
+
+By default, variables are scoped to the entire document, i.e. they are available in all requests in the file, 
+no matter where they are declared and later declarations will override earlier ones.
+
+You can change the scope to `variables_scope = "request"` in the options, which will make variables scoped to the current request only.

docs/sidebars.ts

@@ -1,4 +1,4 @@
-import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
 
 const sidebars: SidebarsConfig = {
   defaultSidebar: [
@@ -38,6 +38,7 @@ const sidebars: SidebarsConfig = {
         "usage/magic-variables",
         "usage/authentication",
         "usage/import-and-run-http",
+        "usage/shared-blocks",
         "usage/reading-file-data",
         "usage/filter-response",
         "usage/redirect-the-response",

lua/kulala/cmd/init.lua

@@ -330,12 +330,12 @@ local function process_pre_request_commands(request)
   local processor
   for _, metadata in ipairs(request.metadata) do
     processor = int_meta_processors[metadata.name]
-    _ = processor and INT_PROCESSING[processor](metadata.value, response)
+    _ = processor and INT_PROCESSING[processor](metadata.value)
   end
 
   for _, metadata in ipairs(request.metadata) do
     processor = ext_meta_processors[metadata.name]
-    _ = processor and EXT_PROCESSING[processor](metadata.value, response)
+    _ = processor and EXT_PROCESSING[processor](metadata.value)
   end
 
   return true
@@ -345,9 +345,14 @@ local function parse_request(requests, request, variables)
   if not process_pre_request_commands(request) then return end
 
   local parsed_request, status = REQUEST_PARSER.parse(requests, variables, request)
+
   if not parsed_request then
-    status = status == "skipped" and "is skipped" or "could not be parsed"
-    return Logger.warn(("Request at line: %s " .. status):format(request.start_line or request.show_icon_line_number))
+    if status == "empty" then return status end
+
+    local msg = status == "skipped" and "is skipped" or "could not be parsed"
+    Logger.warn(("Request at line: %s " .. msg):format(request.start_line or request.show_icon_line_number))
+
+    return status
   end
 
   return parsed_request
@@ -383,6 +388,8 @@ function process_request(requests, request, variables, callback)
   handle_response = vim.schedule_wrap(handle_response)
 
   local parsed_request = parse_request(requests, request, variables)
+
+  if parsed_request == "empty" or parsed_request == "skipped" then return M.queue:run_next() end
   if not parsed_request then
     callback(false, 0, request.start_line)
     return config.halt_on_error and M.queue:reset() or M.queue:run_next()
@@ -438,7 +445,7 @@ end
 
 ---Parses and executes DocumentRequest/s:
 ---if requests is nil then it parses the current document
----if line_nr is nil then runs the first request in the list
+---if line_nr is nil then runs the first request in the list (used for replaying last request)
 ---if line_nr > 0 then runs the request from current buffer around the line number
 ---if line_nr is 0 then runs all or visually selected requests
 ---@param requests? DocumentRequest[]|nil

lua/kulala/config/defaults.lua

@@ -22,6 +22,8 @@ local M = {
   -- enable reading vscode rest client environment variables
   vscode_rest_client_environmentvars = false,
 
+  -- set variable scope:  document or request
+  variables_scope = "document", ---@type "document"|"request"
   -- define your own dynamic variables here, e.g. $randomEmail
   custom_dynamic_variables = {}, ---@type { [string]: fun():string }
 

lua/kulala/formatter/formatter.lua

@@ -258,6 +258,8 @@ format_rules = {
     insert_formatted(#section.variables > 0, table.concat(section.variables, "\n"), "variable_declaration")
     insert_formatted(#section.commands > 0, table.concat(section.commands, "\n"), "command")
     insert_formatted(#section.metadata > 0, table.concat(section.metadata, "\n"), "metadata")
+    -- force parsing request child node, when there is no request node, like in Shared section
+    if #section.request.formatted == 0 then format_rules["request"](node) end
     insert_formatted(#section.request.formatted > 0, section.request.formatted, "request")
 
     section.formatted = section.formatted:gsub("\n*$", "")
@@ -344,9 +346,11 @@ format_rules = {
       or (method ~= "GRPC" and method ~= "WEBSOCKET" and method ~= "WS" and "HTTP/1.1" or "")
 
     local request = current_section().request
-    request.url = ("%s %s %s"):format(method, target_url, http_version)
 
-    format_children(node)
+    if #target_url > 0 then -- format url and children only if url is present
+      request.url = ("%s %s %s"):format(method, target_url, http_version)
+      format_children(node)
+    end
 
     _ = #request.pre_request_script > 0
       and table.insert(formatted, table.concat(request.pre_request_script, "\n\n") .. "\n")

lua/kulala/parser/document.lua

@@ -1,3 +1,4 @@
+local Config = require("kulala.config")
 local DB = require("kulala.db")
 local Diagnostics = require("kulala.cmd.diagnostics")
 local FS = require("kulala.utils.fs")
@@ -9,7 +10,9 @@ local Table = require("kulala.utils.table")
 local M = {}
 
 ---@class DocumentRequest
+---@field shared DocumentRequest
 ---@field metadata table<{name: string, value: string}>
+---@field variables table<{name: string, value: string|number|boolean}>
 ---@field comments string[]
 ---
 ---@field method string
@@ -53,7 +56,10 @@ local M = {}
 
 ---@type DocumentRequest
 local default_document_request = {
+  ---@diagnostic disable-next-line: missing-fields
+  shared = {},
   metadata = {},
+  variables = {},
   comments = {},
   method = "",
   url = "",
@@ -179,15 +185,17 @@ local function parse_redirect_response(request, line)
   })
 end
 
--- Variable
 -- Variables are defined as `@variable_name=value`
 -- The value can be a string, a number or boolean
-local function parse_variables(variables, line)
+local function parse_variables(request, variables, line)
   local variable_name, variable_value = line:match("^@([%w_]+)%s*=%s*(.*)$")
   if variable_name and variable_value then
     -- remove the @ symbol from the variable name
     variable_name = variable_name:sub(1)
     variables[variable_name] = variable_value
+
+    request.variables[variable_name] = variable_value
+    if Config.options.variables_scope == "document" then request.shared.variables[variable_name] = variable_value end
   end
 end
 
@@ -361,7 +369,7 @@ local function parse_run_command(requests, imported_requests, variables, request
   end)
 
   vim.iter(vim.split(variables_to_replace or "", ",%s*")):each(function(variable)
-    parse_variables(variables, variable)
+    parse_variables(request, variables, variable)
   end)
 end
 
@@ -409,7 +417,10 @@ function parse_document(lines, path)
 
   if not content_lines then return end
 
-  local variables = {}
+  local shared = vim.deepcopy(default_document_request)
+  shared.url = nil
+
+  local variables = {} -- TODO: remove
   local requests = {}
   local imported_requests = {}
   local blocks = split_content_by_blocks(content_lines, line_offset)
@@ -426,6 +437,7 @@ function parse_document(lines, path)
     request.end_line = block.end_lnum
     request.name = block.name
     request.file = path or vim.fn.fnamemodify(vim.fn.bufname(DB.get_current_buffer()), ":p")
+    request.shared = shared
 
     for relative_linenr, line in ipairs(block.lines) do
       local lnum = request.start_line + relative_linenr
@@ -454,7 +466,7 @@ function parse_document(lines, path)
       elseif is_prerequest_handler_script_inline then
         request.scripts.pre_request.priority = request.scripts.pre_request.priority or "inline"
         table.insert(request.scripts.pre_request.inline, line)
-      -- we're still in(/before) the request line and we have a pre-request inline handler script
+        -- we're still in(/before) the request line and we have a pre-request inline handler script
       elseif is_request_line and line:match("^< %{%%$") then
         is_prerequest_handler_script_inline = true
         -- we're still in(/before) the request line and we have a pre-request file handler script
@@ -476,7 +488,7 @@ function parse_document(lines, path)
         local scriptfile = line:match("^> (.*)$")
         table.insert(request.scripts.post_request.files, scriptfile)
       elseif line:match("^@([%w_]+)") then
-        parse_variables(variables, line)
+        parse_variables(request, variables, line)
       elseif is_body_section then
         parse_body(request, line, lnum)
       elseif not is_request_line and line:match("^%s*/.+") then
@@ -502,13 +514,15 @@ function parse_document(lines, path)
       infer_headers_from_body(request)
     end
 
-    if request.url and #request.url > 0 then
+    if request.name == "Shared" or request.name == "Shared each" then
+      shared = request
+      shared.url = #shared.url > 0 and shared.url or nil
+    elseif request.url and #request.url > 0 then
       table.insert(requests, request)
     elseif #request.nested_requests > 0 then
       vim.iter(request.nested_requests or {}):each(function(r)
         r.metadata = vim.tbl_extend("force", r.metadata, request.metadata)
-        r.start_line = request.start_line
-        r.end_line = request.end_line
+        r.start_line, r.end_line = request.start_line, request.end_line
       end)
       vim.list_extend(requests, request.nested_requests)
     end
@@ -533,16 +547,58 @@ M.get_document = function(lines, path)
   return unpack(result)
 end
 
+local function apply_shared_data(shared, request)
+  local request_metadata = vim
+    .iter(request.metadata)
+    :map(function(metadata)
+      return metadata.name
+    end)
+    :totable()
+
+  vim.iter(shared.metadata):each(function(metadata)
+    if not vim.tbl_contains(request_metadata, metadata.name) then table.insert(request.metadata, metadata) end
+  end)
+
+  vim.iter(shared.variables):each(function(k, v)
+    if not request.variables[k] then request.variables[k] = v end
+  end)
+
+  return request
+end
+
+local function is_runnable(request)
+  local pre_scripts = request.scripts.pre_request
+  return request.url or #pre_scripts.inline + #pre_scripts.files > 0 or #request.nested_requests > 0
+end
+
 local function expand_nested_requests(requests, lnum)
   requests = vim.islist(requests) and requests or { requests }
 
   local expanded = {}
+  local shared = requests[1].shared
+
+  if not requests[1].name:match("Shared") and is_runnable(shared) then
+    if shared.name == "Shared each" then
+      local requests_ = vim.deepcopy(requests)
+      requests = {}
+
+      vim.iter(requests_):each(function(request)
+        table.insert(requests, shared)
+        table.insert(requests, request)
+      end)
+    else
+      table.insert(requests, 1, shared)
+    end
+  end
 
   vim.iter(requests):each(function(request)
+    request = apply_shared_data(shared, request)
+
     vim.iter(request.nested_requests):each(function(nested_request)
       nested_request.show_icon_line_number = lnum or nested_request.show_icon_line_number
       vim.list_extend(expanded, expand_nested_requests(nested_request, nested_request.show_icon_line_number))
     end)
+
     table.insert(expanded, request)
   end)