Merge pull request #104 from paulo-ferraz-oliveira/feature/improved-doc-and-example

Improved doc. and example

Author: elbrujohalcon

.github/workflows/ci.yml

@@ -21,4 +21,40 @@ jobs:
         with:
           otp-version: ${{matrix.otp_vsn}}
           rebar3-version: '3.14'
-      - run: rebar3 test
+      - run: |
+          rm -rf example/_checkouts  # Prevent long running analysis
+          rebar3 test
+  example:
+    name: Makes sure our example run over ${{matrix.otp_vsn}} and ${{matrix.os}}
+    runs-on: ${{matrix.os}}
+    strategy:
+      matrix:
+        otp_vsn: [21, 22, 23, 24]
+        os: [ubuntu-latest]
+    steps:
+      - uses: actions/checkout@v2
+      - uses: erlef/setup-beam@v1
+        with:
+          otp-version: ${{matrix.otp_vsn}}
+          rebar3-version: '3.14'
+      - name: test our example
+        run: |
+          cd example
+          rebar3 release
+          _build/default/rel/example/bin/example daemon
+          R=$(curl -s -w "%{http_code}" -XPUT "localhost:8080/poor-kv/some-key/some-value" -H "content-type: text/plain")
+          [[ $R == "some-value201" ]] || exit 1  # This becomes some-value200 after the first PUT
+          R=$(curl -s -w "%{http_code}" "localhost:8080/poor-kv/some-key" -H "content-type: text/plain")
+          [[ $R == "some-value200" ]] || exit 1
+          R=$(curl -s -w "%{http_code}" "localhost:8080/poor-kv/non-existing-key" -H "content-type: text/plain")
+          [[ $R == "404" ]] || exit 1
+          R=$(curl -s -w "%{http_code}" -XDELETE "localhost:8080/poor-kv/some-key" -H "content-type: text/plain")
+          [[ $R == "204" ]] || exit 1
+          R=$(curl -s -w "%{http_code}" -XDELETE "localhost:8080/poor-kv/some-key" -H "content-type: text/plain")
+          [[ $R == "404" ]] || exit 1
+          _build/default/rel/example/bin/example stop
+      - name: check our example
+        run: |
+          cd example
+          rm -rf _checkouts  # Prevent long running analysis
+          rebar3 test

README.md

@@ -1,5 +1,3 @@
-[![Stories in Ready](https://badge.waffle.io/inaka/cowboy-trails.png?label=ready&title=Ready)](https://waffle.io/inaka/cowboy-trails)
-
 <img src="https://lh5.googleusercontent.com/-Y1n1Vh4FjLE/TXDZiQ_zSVI/AAAAAAAAAJY/h47az_0MxO0/s1600/Western+backdrop+04.png" height="200" width="100%" />
 
 # cowboy-trails
@@ -9,22 +7,24 @@
 Cowboy routes on steroids!
 
 ## Contact Us
+
 If you find any **bugs** or have a **problem** while using this library, please
-[open an issue](https://github.com/inaka/elvis/issues/new) in this repo
-(or a pull request :)).
+[open an issue](https://github.com/inaka/cowboy-trails/issues/new) in this repo
+(or a pull request 😄).
 
-And you can check all of our open-source projects at [inaka.github.io](http://inaka.github.io).
+And you can check out all of our open-source projects at [inaka.github.io](http://inaka.github.io).
 
 ## Why Cowboy Trails?
-**Cowboy-Trails** enables you to:
 
-* Add information to `cowboy` routes, which can be used later to interact with
-  the server in a higher abstraction level.
+**Cowboy-Trails** enables you to:
 
-* Define the server routes directly within the module that implements them.
+* add information to `cowboy` routes, which can later be used to interact with
+  the server in a higher abstraction level,
+* define the server routes directly within the module that implements them.
 
 ## How to Use it?
-The first use case for `cowboy_trails` is to compile `cowboy` routes.
+
+The most common use case for `cowboy_trails` is to compile `cowboy` routes.
 
 Normally with `cowboy` you compile routes in the following way:
 
@@ -38,18 +38,18 @@ Routes = [{'_',
 cowboy_router:compile(Routes),
 ```
 
-Trails is also fully compatible with `cowboy` routes, so you can pass the same
-routes in order to be processed by trails:
+Trails is fully compatible with `cowboy` routes, so you can pass the same
+routes in order to be processed by Trails:
 
 ```erlang
 trails:compile(Routes),
 ```
 
-So far it seems like there is not any difference, right? But the most common case
-with `cowboy` is that you usually work with a single host, even though you're
+So far it seems like there's no difference, right? But most of the time,
+with `cowboy`, you usually work with only a single host, but you're
 required to keep defining the host parameter within the routes (`[{'_', [...]}]`).
 
-Well, with trails you have another useful function to compile single host routes:
+Well, with Trails you have another useful function to compile single host routes:
 
 ```erlang
 %% You only define the routes/paths
@@ -59,13 +59,15 @@ Routes = [ {"/resource1", resource1_handler, []}
 trails:single_host_compile(Routes),
 ```
 
-Now, let's suppose that you want to add additional information (metadata) to
-cowboy routes related with the semantics of each HTTP method.
+Now, let's suppose you want to add metadata to
+`cowboy` routes related with the semantics of each HTTP method.
+
+You'd do something like:
 
 ```erlang
 Metadata = #{put => #{description => "PUT method"},
-             post => #{ description => "POST method"},
-             get => #{ description => "GET method"}},
+             post => #{description => "POST method"},
+             get => #{description => "GET method"}},
 Trail = trails:trail("/",
                      cowboy_static,
                      {private_file, "index2.html"},
@@ -75,9 +77,9 @@ Trail = trails:trail("/",
 Metadata = trails:metadata(Trail),
 ```
 
-This can be used later to generate documentation related to each endpoint.
+This can then be used to generate documentation related to each endpoint.
 
-Normally, when you work with `cowboy` you have to define all routes in one place:
+Also, when you work with `cowboy`, you have to define all routes in one place:
 
 ```erlang
 Routes =
@@ -100,9 +102,10 @@ Routes =
 Dispatch = cowboy_router:compile(Routes),
 ```
 
-But now with `trails` you're able to define the routes on each resource handler.
-The handler must implement the callback `trails/0` or `trails/1` and return the specific
-routes for that handler. For a better understanding, you can check out the
+But now, with `trails`, you're able to define the routes on each of your resource handlers,
+separately.
+These handlers must implement callback `trails/0` or `trails/1` and return the specific
+routes that define them. For a better understanding, you can check out the
 examples in the `test` folder ([trails_test_handler](./test/trails_test_handler.erl)).
 
 Once you have implemented the `trails/0` or `trails/1` callback on your handlers, you can do
@@ -128,26 +131,10 @@ Trails =
 trails:single_host_compile(Trails),
 ```
 
-This way each handler keeps their own routes, as it should be, and you can
+This way each handler maintains their own routes, as it should be, and you can
 merge them easily.
 
 ## Example
 
 For more information about `cowboy_trails`, how to use it and the different
-functions that it exposes, please check this [Example](./example).
-
-## Testing
-
-This project's test suites include [meta testing](http://inaka.net/blog/2015/11/13/erlang-meta-test-revisited/).
-Therefore, in order to run the tests, it requires a proper plt.
-Otherwise, when you try `rebar3 ct`, you'll get an error similar to:
-
-```erlang
-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-ktn_meta_SUITE:dialyzer failed on line 60
-Reason: {test_case_failed,No plts at ../../*.plt - you need to at least have one}
-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-```
-
-To generate the required plt, just run `rebar3 dialyzer` once and then you can
-run `rebar3 ct` as many times as you like.
+functions that it exposes, please check this [example](./example).

example/.gitignore

@@ -1,13 +1,5 @@
-*.beam
-*.log
-*.plt
-*pem
-.DS_Store
-all.coverdata
-bin
-/deps/mixer
-ebin
+.rebar3
+_build
 erl_crash.dump
 log
-logs
-.erlang.mk.packages.v2
+rebar3.crashdump

example/README.md

@@ -1,72 +1,64 @@
-# Cowboy Trails Example
+# Cowboy Trails Basic Example
 
 To try this example, you need `git` and `Erlang` in your PATH.
 
-```erlang
-
-  rebar3 compile
+```shell
+$ rebar3 compile
 ```
 
 To start the example server in a interactive way do this:
-```erlang
-
-  rebar3 shell
-```
-
-## Handlers Description
-
-if you run this `curl` command, you will see all trails description of this server.
 
+```shell
+$ rebar3 shell
 ```
-curl -i http://localhost:8080/description
 
-[#{constraints => [],
-   handler => cowboy_static,
-   metadata => #{get => #{desc => "Static Data"}},
-   options => {priv_dir,example,[],[{mimetypes,cow_mimetypes,all}]},
-   path_match => <<"/[...]">>},
- #{constraints => [],
-   handler => example_echo_handler,
-   metadata => #{get => #{desc => "Gets echo var in the server"},
-     put => #{desc => "Sets echo var in the server"}},
-   options => [],
-   path_match => <<"/message/[:echo]">>},
- #{constraints => [],
-   handler => example_description_handler,
+## Handlers' Description
+
+If you run this `curl` command, you will see all trails' description of this server.
+
+```shell
+$ curl -i http://localhost:8080/description
+[#{constraints => [],handler => example_poor_kv_handler,
+   metadata =>
+       #{delete =>
+             #{'content-type' => "text/plain",
+               desc => "Unsets an env var in the server"},
+         get =>
+             #{'content-type' => "text/plain",
+               desc => "Gets en env var from the server"},
+         put =>
+             #{'content-type' => "text/plain",
+               desc => "Sets an env var in the server"}},
+   options => [],path_match => "/poor-kv/:key/[:value]"},
+ #{constraints => [],handler => example_description_handler,
    metadata => #{get => #{desc => "Retrives trails's server description"}},
-   options => [],
-   path_match => <<"/description">>}]
+   options => [],path_match => <<"/description">>}]
 ```
 
-## Poor-Man's Key-Value Store
+## Poor Man's Key-Value Store
 
-There is an  additional endpoint that implement a really simple key-value store
-that uses the application's env variable as its backend. It is possible to `PUT`,
+There is an additional endpoint that implements a really simple key-value store
+that uses the application's env. variable as its backend. It is possible to `PUT`,
 `GET` and `DELETE` values in the following way:
 
-```
+```shell
 $ curl -XPUT "localhost:8080/poor-kv/some-key/some-value" -H "content-type: text/plain"
-
 some-value
 
-$ curl -XGET "localhost:8080/poor-kv/some-key" -H "content-type: text/plain"
-
+$ curl "localhost:8080/poor-kv/some-key" -H "content-type: text/plain"
 some-value
 
-$ curl -v -XGET "localhost:8080/poor-kv/non-existing-key" -H "content-type: text/plain"
-
+$ curl -v "localhost:8080/poor-kv/non-existing-key" -H "content-type: text/plain"
 ...
 < HTTP/1.1 404 Not Found
 ...
 
 $ curl -v -XDELETE "localhost:8080/poor-kv/some-key" -H "content-type: text/plain"
-
 ...
 < HTTP/1.1 204 No Content
 ...
 
 $ curl -v -XDELETE "localhost:8080/poor-kv/some-key" -H "content-type: text/plain"
-
 ...
 < HTTP/1.1 404 Not Found
 ...

example/_checkouts/trails

@@ -0,0 +1 @@
+../../.