doc: variables

kriogenia · Apr 14, 2024 · e543f48 · e543f48
1 parent 5d6e403
commit e543f48
Show file tree

Hide file tree

Showing 3 changed files with 26 additions and 1 deletion.
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -10,7 +10,7 @@
 - [Request DSL](./reference_guide/request_dsl.md)
   - [Body](./reference_guide/request_dsl/body.md)
   - [Input_parameters]()
-  - [Placeholders and variables]()
+  - [Placeholders](./reference_guide/request_dsl/placeholders.md)
 - [Command Line Interface](./reference_guide/command_line_interface.md)
   - [run](reference_guide/command_line_interface/run.md)
   - [example](reference_guide/command_line_interface/example.md)

diff --git a/book/src/reference_guide/request_dsl.md b/book/src/reference_guide/request_dsl.md
@@ -68,6 +68,7 @@ _warning: some common leaders like `Host` and `Content-Type` will be autogenerat
 option to disable this autogeneration_
 
 ## [query_params]
+
 This table is **free**. There's no predefined keys but the values can't be of type datetime
 or tables. Arrays are supported and will be sent in the request as a comma separated list of
 the values.
@@ -95,6 +96,18 @@ name = "Feldespato"
 location = "unknown"
 ```
 
+## [variables]
+This table is **free**. There's no predefined keys but the values can't be of type datetime
+or tables. Arrays are supported and will be sent in the request as a comma separated list of
+the values.
+
+Variables serve to set a value to replace **placeholders** ([see](./request_dsl/placeholders.md)).
+
+```toml
+host = "192.0.0.1"
+name = "Vin"
+```
+
 ## [metadata]
 
 This table is **free** but the values must be one of the primitive values (_string_, _integer_,

diff --git a/book/src/reference_guide/request_dsl/placeholders.md b/book/src/reference_guide/request_dsl/placeholders.md
@@ -0,0 +1,12 @@
+# Placeholders
+
+Placeholders are strings wrapped in double braces, like `{{this}}`. They can be the whole value
+of a string or can be a substring, for example: `{{host}}/api/{{version}}/hello`.
+
+Placeholders can be given a value through different resolvers. These resolvers have a defined
+order and the first providing a value will be the one that is used. If no resolver has a value
+for the placeholder then the user will be prompted to resolve it.
+
+The order of resolution is:
+1. [Variables](#variables), these are defined in a [standard table](../request_dsl.md#variables)
+similar to query params or headers, but this one is only aimed to provide values for placeholders.