From 08339229db6da6e76726162ba325a625b558cfb6 Mon Sep 17 00:00:00 2001
From: Guillaume Pasquet <dev@etenil.net>
Date: Sat, 26 Mar 2022 06:22:34 +0000
Subject: Feature/16 dependencies

---
 README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 75 insertions(+), 5 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 37d950a..ae6aa40 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,31 @@ BARB
 
 Barb is a file-based API query tool that works nicely with version control and fits into UNIX terminal usage.
 
+
+<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
+**Table of Contents**
+
+- [BARB](#barb)
+    - [Installation](#installation)
+    - [Example usage](#example-usage)
+        - [CLI options](#cli-options)
+    - [Barb format](#barb-format)
+        - [Verb line](#verb-line)
+        - [Headers](#headers)
+        - [Filter](#filter)
+            - [JSONPath](#jsonpath)
+            - [JQ](#jq)
+        - [Dependencies](#dependencies)
+        - [Body](#body)
+        - [Variable substitution](#variable-substitution)
+            - [Placeholder format](#placeholder-format)
+            - [Default value](#default-value)
+    - [Credits](#credits)
+
+<!-- markdown-toc end -->
+
+
+
 ## Installation
 
 Barb is only available through `Cargo` at this time. To install the default version with JSONPath only, [install rust with rustup](https://rustup.rs).do like so:
@@ -120,6 +145,20 @@ Filters can be named to populate execution variables by extracting values. Consi
 #FOOBAR|<JQ FILTER>
 ```
 
+### Dependencies
+
+A barb file can declare only _one_ dependency which will be executed before the main file is executed. If multiple dependencies are declared, only the last one will be executed.
+
+Syntax:
+
+```
+#>relative/path/to/file.barb
+```
+
+The path to the dependency can either be relative to the current file or absolute. When running multiple barb files which have the same dependency, that dependency will only be executed _once_.
+
+A barb dependency _cannot have dependencies of its own_. Any dependency declared within a dependency will simply be ignored.
+
 ### Body
 
 Anything after the preamble is considered as a body and will be send in the request for the following methods:
@@ -134,9 +173,10 @@ Body does not support variable substitution.
 
 Barb can include environment variable values and variables defined in `.env` into the requests with the following placeholder format:
 
+#### Placeholder format
+
 ```
 {VARIABLE NAME}
-{VARIABLE NAME:-DEFAULT}
 ```
 
 This allows to do the following:
@@ -147,10 +187,40 @@ $ cat api-status.barb
 #GET^{BASE_URL}/api/v1/status
 
 $ barb api-status.barb
-200 OK GET http://127.0.0.1:8000/api/v1/status
-{
-    "status": "OK"
-}
+GET http://127.0.0.1:8000/api/v1/status
+
+200 OK
+
+{"status": "OK"}
+```
+
+#### Default value
+
+A placholder can be given a default value that will be used if the environment variable is not available. The format is as follows:
+
+```
+{VARIABLE NAME:-DEFAULT}
+```
+
+Example:
+
+```
+$ cat api-ping.barb
+#GET^http://{HOST:-foobar.com}/api/ping
+
+$ barb api-ping.barb
+GET http://foobar.com/api/ping
+
+200 OK
+
+{"response": "pong"}
+
+$ HOST=bar.com barb api-ping.barb
+GET http://bar.com/api/ping
+
+200 OK
+
+{"response": "pong"}
 ```
 
 ## Credits
-- 
cgit v1.2.3