Merge pull request #42 from basho/feature/csv_formatter

Add CSV formatter and support for other custom formats in general

Reviewed-by: macintux

Author: borshop

README.md

@@ -30,7 +30,7 @@ Clique provides the application developer with the following capabilities:
    configuration across one or all nodes: i.e.  `riak-admin set anti-entropy=on --all`
  * Return a standard status format that allows output of a variety of content
    types: human-readable, csv, html, etc... (Note that currently only
-   human-readable output is implemented)
+   human-readable and CSV output formats are implemented)
 
 ### Why Not Clique ?
  * You aren't writing a CLI
@@ -309,6 +309,19 @@ clique:register_usage(["riak-admin", "handoff"], handoff_usage()),
 clique:register_usage(["riak-admin", "handoff", "limit"], fun handoff_limit_usage/0).
 ```
 
+### register_writer/2
+This is not something most applications will likely need to use, but the
+capability exists to create custom output writer modules. Currently you can
+specify the `--format=[human|csv]` flag on many commands to determine how the
+output will be written; registering a new writer "foo" allows you to use
+`--format=foo` to write the output using whatever corresponding writer module
+you've registered.
+
+Writing custom output writers is relatively undocumented right now, and the
+values passed to the `write/1` callback may be subject to future changes. But,
+the `clique_*_writer` modules in the clique source tree provide good examples
+that can be used for reference.
+
 ### run/1
 `run/1` takes a given command as a list of strings and attempts to run the
 command using the registered information. If called with `set`, `show`, or

include/clique_status_types.hrl

@@ -5,7 +5,7 @@
 %% csv and a subset of html, as well as other possible output.
 -type text() :: {text, iolist()}.
 -type status_list() :: {list, iolist(), [iolist()]} | {list, [iolist()]}.
--type table() :: {table, [{iolist(), iolist()}]}.
+-type table() :: {table, [[{atom() | string(), term()}]]}.
 -type alert() :: {alert, [status_list() | table() | text()]}.
 -type usage() :: usage.
 -type elem() :: text() | status_list() | table() | alert() | usage().

rebar.config

@@ -6,6 +6,11 @@
 {xref_checks, []}.
 {xref_queries, [{"(XC - UC) || (XU - X - B - \"(cluster_info|dtrace)\" : Mod)", []}]}.
 
+{erl_first_files, [
+  "src/clique_writer.erl",
+  "src/clique_handler.erl"
+]}.
+
 {deps, [
   {cuttlefish, ".*", {git, "git://github.com/basho/cuttlefish.git", {branch, "2.0"}}}
 ]}.

src/clique.erl

@@ -25,6 +25,7 @@
          register_command/4,
          register_config/2,
          register_formatter/2,
+         register_writer/2,
          register_config_whitelist/1,
          register_usage/2,
          run/1,
@@ -56,6 +57,11 @@ register_config(Key, Callback) ->
 register_formatter(Key, Callback) ->
     clique_config:register_formatter(Key, Callback).
 
+%% @doc Register a module for writing output in a specific format
+-spec register_writer(string(), module()) -> true.
+register_writer(Name, Module) ->
+    clique_writer:register(Name, Module).
+
 %% @doc Register a list of configuration variables that are settable.
 %% Clique disallows setting of all config variables by default. They must be in
 %% whitelist to be settable.
@@ -75,43 +81,29 @@ register_usage(Cmd, Usage) ->
     clique_usage:register(Cmd, Usage).
 
 %% @doc Take a list of status types and generate console output
--spec print(err() | clique_status:status(), [string()]) -> ok.
-print(usage, Cmd) ->
+-spec print(err() | clique_status:status() | {clique_status:status(), string()}, [string()]) -> ok.
+print({error, _} = E, Cmd) ->
+    print(E, Cmd, "human");
+print({Status, Format}, Cmd) ->
+    print(Status, Cmd, Format);
+print(Status, Cmd) ->
+    print(Status, Cmd, "human").
+
+-spec print(usage | err() | clique_status:status(), [string()], string()) -> ok.
+print(usage, Cmd, _Format) ->
     clique_usage:print(Cmd);
-print({error, _}=E, Cmd) ->
+print({error, _}=E, Cmd, Format) ->
     Alert = clique_error:format(hd(Cmd), E),
-    print(Alert, Cmd);
-print(Status, _Cmd) ->
-    Output = clique_human_writer:write(Status),
-    io:format("~ts", [Output]),
-    ok.
+    print(Alert, Cmd, Format);
+print(Status, _Cmd, Format) ->
+    Output = clique_writer:write(Status, Format),
+    io:format("~ts", [Output]).
 
 %% @doc Run a config operation or command
 -spec run([string()]) -> ok | {error, term()}.
-run([_Script, "set" | Args] = Cmd) ->
-    print(clique_config:set(Args), Cmd);
-run([_Script, "show" | Args] = Cmd) ->
-    print(clique_config:show(Args), Cmd);
-run([_Script, "describe" | Args] = Cmd) ->
-    print(clique_config:describe(Args), Cmd);
-run(Cmd0) ->
-    case is_help(Cmd0) of
-        {ok, Cmd} ->
-            clique_usage:print(Cmd);
-        _ ->
-            M0 = clique_command:match(Cmd0),
-            M1 = clique_parser:parse(M0),
-            M2 = clique_parser:validate(M1),
-            print(clique_command:run(M2), Cmd0)
-    end.
-
-%% @doc Help flags always comes at the end of the command
--spec is_help(iolist()) -> {ok, iolist()} | false.
-is_help(Str) ->
-    [H | T] = lists:reverse(Str),
-    case H =:= "--help" orelse H =:= "-h" of
-        true ->
-            {ok, lists:reverse(T)};
-        false ->
-            false
-    end.
+run(Cmd) ->
+    M0 = clique_command:match(Cmd),
+    M1 = clique_parser:parse(M0),
+    M2 = clique_parser:extract_global_flags(M1),
+    M3 = clique_parser:validate(M2),
+    print(clique_command:run(M3), Cmd).

src/clique_command.erl

@@ -32,6 +32,8 @@
 -type proplist() :: [{atom(), term()}].
 -type status() :: clique_status:status().
 
+-define(SET_CMD_SPEC, {["_", "set"], '_', clique_config:config_flags(), fun clique_config:set/2}).
+
 init() ->
     _ = ets:new(?cmd_table, [public, named_table]),
     ok.
@@ -45,17 +47,36 @@ register(Cmd, Keys, Flags, Fun) ->
          ({fun(), proplist(), proplist()})-> status().
 run({error, _}=E) ->
     E;
-run({Fun, Args, Flags}) ->
-    Fun(Args, Flags).
+run({Fun, Args, Flags, GlobalFlags}) ->
+    Format = proplists:get_value(format, GlobalFlags, "human"),
+    case proplists:is_defined(help, GlobalFlags) of
+        true ->
+            {usage, Format};
+        false ->
+            Result = Fun(Args, Flags),
+            {Result, Format}
+    end.
 
 -spec match([list()])-> {tuple(), list()} | {error, no_matching_spec}.
 match(Cmd0) ->
     {Cmd, Args} = split_command(Cmd0),
-    case ets:lookup(?cmd_table, Cmd) of
-        [Spec] ->
+    %% Check for builtin commands first. If that fails, check our command table.
+    case Cmd of
+        [_Script, "set" | _] ->
+            {?SET_CMD_SPEC, Args};
+        [_Script, "show" | _] ->
+            Spec = cmd_spec(Cmd, fun clique_config:show/2, clique_config:config_flags()),
+            {Spec, Args};
+        [_Script, "describe" | _] ->
+            Spec = cmd_spec(Cmd, fun clique_config:describe/2, []),
             {Spec, Args};
-        [] ->
-            {error, {no_matching_spec, Cmd0}}
+        _ ->
+            case ets:lookup(?cmd_table, Cmd) of
+                [Spec] ->
+                    {Spec, Args};
+                [] ->
+                    {error, {no_matching_spec, Cmd0}}
+            end
     end.
 
 -spec split_command([list()]) -> {list(), list()}.
@@ -65,3 +86,13 @@ split_command(Cmd0) ->
                         clique_parser:is_not_flag(Str)
                     end, Cmd0).
 
+%% NB This is a bit sneaky. We normally only accept key/value args like
+%% "handoff.inbound=off" and flag-style arguments like "--node [email protected]" or "--all",
+%% but the builtin "show" and "describe" commands work a bit differently.
+%% To handle these special cases, we dynamically build a command spec to smuggle the
+%% arguments through the rest of the (otherwise cleanly designed and implemented) code.
+cmd_spec(Cmd, CmdFun, AllowedFlags) ->
+    [_Script, _CmdName | CfgKeys] = Cmd,
+    %% Discard key/val args passed in since we don't need them, and inject the freeform args:
+    SpecFun = fun([], Flags) -> CmdFun(CfgKeys, Flags) end,
+    {Cmd, [], AllowedFlags, SpecFun}.