netcaptain/README.md

# 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.

Similarly to Quests, a Ship can easily be edited in whatever editor you have defined in EDITOR by issuing: ncpt -E <ship>

### 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
```