Beta Release

2020-10-16 15:39:07 -05:00
parent c1f7e8ae91
commit 5f07ea41d2
5 changed files with 162 additions and 8 deletions
@@ -0,0 +1,110 @@
+# netcaptain
+Sail the treacherous seas of the internet.
+
+Netcaptain assists you in building and making HTTP requests.
+
+## Vernacular:
+### Quest - An internet adventure
+Held in the `quests` directory under the given config directory, a quest will look something like this (we'll call this `quest` `auth`):
+```
+POST {{ .Crew.BaseURL }}/api/v1.0/auth
+{"email":"{{.Args.Arg0}}","password":"{{.Args.Arg1}}"}
+```
+Or something like this (and this `quest` will be `lookup`):
+```
+Authorization: Bearer {{ .Hold.Token }}
+GET http://192.168.86.197:8080/api/v1.0/lookup/book/{{ .Args.Arg0 }}
+```
+As you can see, support for `go` templates is built in. While executing the template, the captain will load as much information as can be loaded. 
+
+In the examples above we can see these variables:
+* `.Crew.*`
+* `.Hold.*`
+* `.Args.Arg*`
+
+The `Crew` and the `Hold` are loaded if the captain is given a ship to sail. (A ship need not be specified if one named `default` exists in the given configuration.)
+
+`Args` values are loaded at runtime by arguments passed on the command line in addition to the quest and ship.
+
+That is:
+`ncpt <quest> <ship> <Args.Arg0> <Args.Arg1> ...`
+
+And for example:
+`ncpt lookup enterprise Search+Term`
+Will take the ship `enterprise` and go on the `lookup` quest providing:
+* `Args.Arg0` = `Search+Term`
+
+On the other hand, if `enterprise` is not the name of a defined ship, then you will go on the `lookup` quest providing:
+* `Args.Arg0` = `enterprise`
+* `Args.Arg1` = `Search+Term`
+
+In this second case, if a `default` ship exists, it will be sailed, whether it contains anything to be used or not.
+
+Quests can be easily edited in whatever editor you have defined in `EDITOR` by issuing:
+`ncpt -e <quest>`
+
+And quests can be validated (just run through the the parser without executing it) by issuing:
+`ncpt -c <quest>`
+
+And all available quests can be listed by issuing:
+`ncpt -l`
+
+### Ship - A Crew, and rules for Plunder and Delivery
+Held in the `ships` directory under the given config directory, a ship will look something like this:
+```
+{
+  "crew": {
+    "BaseURL": "http://192.168.86.197:8080"
+  },
+  "plunder": {
+    "auth": {
+      "token": "token"
+    },
+    "ddg-search": {
+      "image": "Image",
+      "result": "Abstract"
+    }
+  }
+}
+``` 
+Here we have a `Crew` some rules for `Plunder`, and a rule for `Deliver`. 
+
+The `Crew` is simple, we have a single Crew Member: `BaseURL`. Looking at the first Quest up above (`auth`):
+```
+POST {{ .Crew.BaseURL }}/api/v1.0/auth
+{"email":"{{.Args.Arg0}}","password":"{{.Args.Arg1}}"}
+```
+So, when we pursue the `auth` quest using this `ship`, the `BaseURL` variable will be replaced with the given Crew member: `http://192.168.86.197:8080`)
+
+The `Plunder` takes a little more explanation. Here we have defined a rule for plundering the `auth` `Quest`. It's basically saying "Upon completing the `auth` quest, I expect to receive `json` that contains, at the first level of the response, a `token` value. Store that value in the `Hold` under the name `token`."
+
+The second `Plunder` rule will trigger on a Quest named `ddg-search`. It's going to pull a couple of values out of the top level of the response:
+* `Image` stored in the ship `Hold` as `image` and
+* `Abstract` stored in the ship `Hold` as `result`
+
+Currently, only top-level values in JSON responses can be plundered.
+
+### Hold - Where Plunder is Stored
+These are simple JSON files that act as key-value stores for anything plundered.
+
+## Usage of ncpt:
+```
+Usage of ncpt:
+  -l    List available Quests
+  -L    List available Ships
+  -c <quest>
+        Validate that the given quest is _c_orrect
+  -C <ship>
+        Validate that the given ship is _C_orrect
+  -e <quest>
+        Edit the given quest
+  -E <ship>
+        Edit the given ship
+  -H <ship>
+        Edit the hold for the given ship
+  -h <ship> <key>
+        Output the value of <key> in the given ship's hold
+  -d string
+        The configuration directory to use (default ".ncpt")
+  -v    Run in Verbose mode
+```