Update docs, README, add example gif

README.md

@@ -1,13 +1,14 @@
 Linenoise in OCaml
-======================
+--------------------
 
 # Benefits
-1. BSD licensed
-2. No system dependencies, no need for `readline` on your machine
+1. BSD licensed.
+2. No system dependencies, no need for `readline` on your machine.
 3. Related to 2, these bindings are self-contained, the source for
    `linenoise` is in this repo and compiled all together with the
-   `OCaml`
-4. Written in OCaml
+   `OCaml`.
+4. Written in OCaml.
+5. Pretty cool hints feature, see the gif.
 
 # Installation
 
@@ -17,10 +18,18 @@ It is easy with `opam`
 $ opam install linenoise
 ```
 
+See the pretty
+documentation [here](http://hyegar.com/ocaml-linenoise/LNoise.html)
+
 # Example code
 This example is also included in the repo under examples:
 
-```OCaml
+<p align="center" style='width:100%'> 
+  <img style='width:100%' src='example.gif'/> 
+</p>
+
+
+```ocaml
 let rec user_input prompt cb =
   match LNoise.linenoise prompt with
   | None -> ()
@@ -29,6 +38,13 @@ let rec user_input prompt cb =
     user_input prompt cb
 
 let () =
+  (* LNoise.set_multiline true; *)
+  LNoise.set_hints_callback (fun line ->
+      if line <> "git remote add " then None
+      else Some (" <this is the remote name> <this is the remote URL>",
+                 LNoise.Yellow,
+                 true)
+    );
   LNoise.history_load ~filename:"history.txt" |> ignore;
   LNoise.history_set ~max_length:100 |> ignore;
   LNoise.set_completion_callback begin fun line_so_far ln_completions ->
@@ -49,7 +65,3 @@ let () =
   )
   |> user_input "test_program> "
 ```
-
-# Possible Improvements
-1. Wrap up the int return value of some functions with an Ok | Error
-   variant.

docs/LNoise.html

@@ -16,7 +16,8 @@
 <h1>Module <a href="type_LNoise.html">LNoise</a></h1>
 
 <pre><span class="keyword">module</span> LNoise: <code class="code"><span class="keyword">sig</span></code> <a href="LNoise.html">..</a> <code class="code"><span class="keyword">end</span></code></pre><div class="info module top">
-OCaml bindings to linenoise.<br>
+OCaml bindings to linenoise, functions that can fail use result
+    type<br>
 </div>
 <hr width="100%">
 
@@ -29,7 +30,7 @@ <h1>Module <a href="type_LNoise.html">LNoise</a></h1>
 <pre><span id="VALadd_completion"><span class="keyword">val</span> add_completion</span> : <code class="type"><a href="LNoise.html#TYPEcompletions">completions</a> -> string -> unit</code></pre><div class="info ">
 This function is used by the callback function registered by the
     user in order to add completion options given the input string
-    when the user typed &lt;tab&gt;.<br>
+    when the user typed &lt;TAB&gt;.<br>
 </div>
 
 <pre><span id="VALset_completion_callback"><span class="keyword">val</span> set_completion_callback</span> : <code class="type">(string -> <a href="LNoise.html#TYPEcompletions">completions</a> -> unit) -> unit</code></pre><div class="info ">
@@ -46,40 +47,102 @@ <h1>Module <a href="type_LNoise.html">LNoise</a></h1>
     most desperate of the conditions.<br>
 </div>
 
-<pre><span id="VALhistory_add"><span class="keyword">val</span> history_add</span> : <code class="type">string -> int</code></pre><div class="info ">
+<pre><span id="VALhistory_add"><span class="keyword">val</span> history_add</span> : <code class="type">string -> (unit, string) result</code></pre><div class="info ">
 Add a string to the history<br>
 </div>
 
-<pre><span id="VALhistory_set"><span class="keyword">val</span> history_set</span> : <code class="type">max_length:int -> int</code></pre><div class="info ">
+<pre><span id="VALhistory_set"><span class="keyword">val</span> history_set</span> : <code class="type">max_length:int -> (unit, string) result</code></pre><div class="info ">
 Set the maximum length for the history. This function can be
     called even if there is already some history, the function will
     make sure to retain just the latest 'len' elements if the new
     history length value is smaller than the amount of items already
     inside the history.<br>
 </div>
 
-<pre><span id="VALhistory_save"><span class="keyword">val</span> history_save</span> : <code class="type">filename:string -> int</code></pre><div class="info ">
-Save the history in the specified file. On success 0 is returned
-    otherwise -1 is returned.<br>
+<pre><span id="VALhistory_save"><span class="keyword">val</span> history_save</span> : <code class="type">filename:string -> (unit, string) result</code></pre><div class="info ">
+Save the history in the specified file<br>
 </div>
 
-<pre><span id="VALhistory_load"><span class="keyword">val</span> history_load</span> : <code class="type">filename:string -> int</code></pre><div class="info ">
-Load the history from the specified file. If the file does not
-    exist zero is returned and no operation is performed.  If the file
-    exists and the operation succeeded 0 is returned, otherwise on
-    error -1 is returned.<br>
+<pre><span id="VALhistory_load"><span class="keyword">val</span> history_load</span> : <code class="type">filename:string -> (unit, string) result</code></pre><div class="info ">
+Load the history from the specified file.<br>
 </div>
 
 <pre><span id="VALclear_screen"><span class="keyword">val</span> clear_screen</span> : <code class="type">unit -> unit</code></pre><div class="info ">
-Clear the screen. Used to handle ctrl+l<br>
+Clear the screen; used to handle CTRL+L<br>
 </div>
 
 <pre><span id="VALset_multiline"><span class="keyword">val</span> set_multiline</span> : <code class="type">bool -> unit</code></pre><div class="info ">
-Set if to use or not the multi line mode.<br>
+Set if to use or not use the multi line mode.<br>
 </div>
 
 <pre><span id="VALprint_keycodes"><span class="keyword">val</span> print_keycodes</span> : <code class="type">unit -> unit</code></pre><div class="info ">
 This special mode is used by linenoise in order to print scan
     codes on screen for debugging / development purposes.<br>
 </div>
+
+<pre><code><span id="TYPEhint_color"><span class="keyword">type</span> <code class="type"></code>hint_color</span> = </code></pre><table class="typetable">
+<tr>
+<td align="left" valign="top" >
+<code><span class="keyword">|</span></code></td>
+<td align="left" valign="top" >
+<code><span id="TYPEELThint_color.Red"><span class="constructor">Red</span></span></code></td>
+
+</tr>
+<tr>
+<td align="left" valign="top" >
+<code><span class="keyword">|</span></code></td>
+<td align="left" valign="top" >
+<code><span id="TYPEELThint_color.Green"><span class="constructor">Green</span></span></code></td>
+
+</tr>
+<tr>
+<td align="left" valign="top" >
+<code><span class="keyword">|</span></code></td>
+<td align="left" valign="top" >
+<code><span id="TYPEELThint_color.Yellow"><span class="constructor">Yellow</span></span></code></td>
+
+</tr>
+<tr>
+<td align="left" valign="top" >
+<code><span class="keyword">|</span></code></td>
+<td align="left" valign="top" >
+<code><span id="TYPEELThint_color.Blue"><span class="constructor">Blue</span></span></code></td>
+
+</tr>
+<tr>
+<td align="left" valign="top" >
+<code><span class="keyword">|</span></code></td>
+<td align="left" valign="top" >
+<code><span id="TYPEELThint_color.Magenta"><span class="constructor">Magenta</span></span></code></td>
+
+</tr>
+<tr>
+<td align="left" valign="top" >
+<code><span class="keyword">|</span></code></td>
+<td align="left" valign="top" >
+<code><span id="TYPEELThint_color.Cyan"><span class="constructor">Cyan</span></span></code></td>
+
+</tr>
+<tr>
+<td align="left" valign="top" >
+<code><span class="keyword">|</span></code></td>
+<td align="left" valign="top" >
+<code><span id="TYPEELThint_color.White"><span class="constructor">White</span></span></code></td>
+
+</tr></table>
+
+<div class="info ">
+What color you want the hints to be.<br>
+</div>
+
+
+<pre><span id="VALset_hints_callback"><span class="keyword">val</span> set_hints_callback</span> : <code class="type">(string -> (string * <a href="LNoise.html#TYPEhint_color">hint_color</a> * bool) option) -> unit</code></pre><div class="info ">
+Set a hints callback, callback gets a string, aka the line input,
+    and you get a chance to give a hint to the user. Example, imagine
+    if user types git remote add, then you can give a hint of &lt;this is
+    where you add a remote name&gt; &lt;this is where you add the remote's
+    URL&gt;, see animated gif in source repo for clear example. Returned
+    tuple represents the hint message, color, and whether it ought to
+    be bold.<br>
+</div>
 </body></html>

docs/html.stamp

@@ -1 +1 @@
-6633f1fc7d6817fbd1143521f8438dbf
+0ea85cbc34781552c15220ad454a5baf

docs/index.html

@@ -19,7 +19,8 @@ <h1></h1>
 <br/><br>
 <table class="indextable">
 <tr><td class="module"><a href="LNoise.html">LNoise</a></td><td><div class="info">
-OCaml bindings to linenoise.
+OCaml bindings to linenoise, functions that can fail use result
+    type
 </div>
 </td></tr>
 </table>

docs/index_modules.html

@@ -16,7 +16,8 @@ <h1>Index of modules</h1>
 <tr><td align="left"><br>L</td></tr>
 <tr><td><a href="LNoise.html">LNoise</a> </td>
 <td><div class="info">
-OCaml bindings to linenoise.
+OCaml bindings to linenoise, functions that can fail use result
+    type
 </div>
 </td></tr>
 </table>

docs/index_types.html

@@ -19,6 +19,12 @@ <h1>Index of types</h1>
 Abstract type of completions, given to your completion callback
 </div>
 </td></tr>
+<tr><td align="left"><br>H</td></tr>
+<tr><td><a href="LNoise.html#TYPEhint_color">hint_color</a> [<a href="LNoise.html">LNoise</a>]</td>
+<td><div class="info">
+What color you want the hints to be.
+</div>
+</td></tr>
 </table>
 </body>
 </html>

docs/index_values.html

@@ -18,13 +18,13 @@ <h1>Index of values</h1>
 <td><div class="info">
 This function is used by the callback function registered by the
     user in order to add completion options given the input string
-    when the user typed &lt;tab&gt;.
+    when the user typed &lt;TAB&gt;.
 </div>
 </td></tr>
 <tr><td align="left"><br>C</td></tr>
 <tr><td><a href="LNoise.html#VALclear_screen">clear_screen</a> [<a href="LNoise.html">LNoise</a>]</td>
 <td><div class="info">
-Clear the screen.
+Clear the screen; used to handle CTRL+L
 </div>
 </td></tr>
 <tr><td align="left"><br>H</td></tr>
@@ -40,7 +40,7 @@ <h1>Index of values</h1>
 </td></tr>
 <tr><td><a href="LNoise.html#VALhistory_save">history_save</a> [<a href="LNoise.html">LNoise</a>]</td>
 <td><div class="info">
-Save the history in the specified file.
+Save the history in the specified file
 </div>
 </td></tr>
 <tr><td><a href="LNoise.html#VALhistory_set">history_set</a> [<a href="LNoise.html">LNoise</a>]</td>
@@ -69,9 +69,15 @@ <h1>Index of values</h1>
     tab-completion, aka when &lt;TAB&gt; is hit in the terminal
 </div>
 </td></tr>
+<tr><td><a href="LNoise.html#VALset_hints_callback">set_hints_callback</a> [<a href="LNoise.html">LNoise</a>]</td>
+<td><div class="info">
+Set a hints callback, callback gets a string, aka the line input,
+    and you get a chance to give a hint to the user.
+</div>
+</td></tr>
 <tr><td><a href="LNoise.html#VALset_multiline">set_multiline</a> [<a href="LNoise.html">LNoise</a>]</td>
 <td><div class="info">
-Set if to use or not the multi line mode.
+Set if to use or not use the multi line mode.
 </div>
 </td></tr>
 </table>

docs/type_LNoise.html

@@ -14,11 +14,14 @@
 &nbsp;&nbsp;<span class="keyword">val</span>&nbsp;set_completion_callback&nbsp;:
 &nbsp;&nbsp;&nbsp;&nbsp;(string&nbsp;<span class="keywordsign">-&gt;</span>&nbsp;<span class="constructor">LNoise</span>.completions&nbsp;<span class="keywordsign">-&gt;</span>&nbsp;unit)&nbsp;<span class="keywordsign">-&gt;</span>&nbsp;unit
 &nbsp;&nbsp;<span class="keyword">val</span>&nbsp;linenoise&nbsp;:&nbsp;string&nbsp;<span class="keywordsign">-&gt;</span>&nbsp;string&nbsp;option
-&nbsp;&nbsp;<span class="keyword">val</span>&nbsp;history_add&nbsp;:&nbsp;string&nbsp;<span class="keywordsign">-&gt;</span>&nbsp;int
-&nbsp;&nbsp;<span class="keyword">val</span>&nbsp;history_set&nbsp;:&nbsp;max_length:int&nbsp;<span class="keywordsign">-&gt;</span>&nbsp;int
-&nbsp;&nbsp;<span class="keyword">val</span>&nbsp;history_save&nbsp;:&nbsp;filename:string&nbsp;<span class="keywordsign">-&gt;</span>&nbsp;int
-&nbsp;&nbsp;<span class="keyword">val</span>&nbsp;history_load&nbsp;:&nbsp;filename:string&nbsp;<span class="keywordsign">-&gt;</span>&nbsp;int
+&nbsp;&nbsp;<span class="keyword">val</span>&nbsp;history_add&nbsp;:&nbsp;string&nbsp;<span class="keywordsign">-&gt;</span>&nbsp;(unit,&nbsp;string)&nbsp;<span class="constructor">Pervasives</span>.result
+&nbsp;&nbsp;<span class="keyword">val</span>&nbsp;history_set&nbsp;:&nbsp;max_length:int&nbsp;<span class="keywordsign">-&gt;</span>&nbsp;(unit,&nbsp;string)&nbsp;<span class="constructor">Pervasives</span>.result
+&nbsp;&nbsp;<span class="keyword">val</span>&nbsp;history_save&nbsp;:&nbsp;filename:string&nbsp;<span class="keywordsign">-&gt;</span>&nbsp;(unit,&nbsp;string)&nbsp;<span class="constructor">Pervasives</span>.result
+&nbsp;&nbsp;<span class="keyword">val</span>&nbsp;history_load&nbsp;:&nbsp;filename:string&nbsp;<span class="keywordsign">-&gt;</span>&nbsp;(unit,&nbsp;string)&nbsp;<span class="constructor">Pervasives</span>.result
 &nbsp;&nbsp;<span class="keyword">val</span>&nbsp;clear_screen&nbsp;:&nbsp;unit&nbsp;<span class="keywordsign">-&gt;</span>&nbsp;unit
 &nbsp;&nbsp;<span class="keyword">val</span>&nbsp;set_multiline&nbsp;:&nbsp;bool&nbsp;<span class="keywordsign">-&gt;</span>&nbsp;unit
 &nbsp;&nbsp;<span class="keyword">val</span>&nbsp;print_keycodes&nbsp;:&nbsp;unit&nbsp;<span class="keywordsign">-&gt;</span>&nbsp;unit
+&nbsp;&nbsp;<span class="keyword">type</span>&nbsp;hint_color&nbsp;=&nbsp;<span class="constructor">Red</span>&nbsp;<span class="keywordsign">|</span>&nbsp;<span class="constructor">Green</span>&nbsp;<span class="keywordsign">|</span>&nbsp;<span class="constructor">Yellow</span>&nbsp;<span class="keywordsign">|</span>&nbsp;<span class="constructor">Blue</span>&nbsp;<span class="keywordsign">|</span>&nbsp;<span class="constructor">Magenta</span>&nbsp;<span class="keywordsign">|</span>&nbsp;<span class="constructor">Cyan</span>&nbsp;<span class="keywordsign">|</span>&nbsp;<span class="constructor">White</span>
+&nbsp;&nbsp;<span class="keyword">val</span>&nbsp;set_hints_callback&nbsp;:
+&nbsp;&nbsp;&nbsp;&nbsp;(string&nbsp;<span class="keywordsign">-&gt;</span>&nbsp;(string&nbsp;*&nbsp;<span class="constructor">LNoise</span>.hint_color&nbsp;*&nbsp;bool)&nbsp;option)&nbsp;<span class="keywordsign">-&gt;</span>&nbsp;unit
 <span class="keyword">end</span></code></body></html>

opam/descr

@@ -1,18 +1,42 @@
-Simple readline like functionality
+Simple readline like functionality with nice hints feature.
 
 These are self contained OCaml bindings to linenoise,
 no system libraries needed at all.
 
-Here's the simplest program:
+Here's a simple program:
 
 let rec user_input prompt cb =
   match LNoise.linenoise prompt with
   | None -> ()
-  | Some v -> cb v;
+  | Some v ->
+    cb v;
     user_input prompt cb
 
 let () =
-  (fun from_user -> Printf.sprintf "Got: %s" from_user |> print_endline)
+  LNoise.set_hints_callback (fun line ->
+      if line <> "git remote add " then None
+      else Some (" <this is the remote name> <this is the remote URL>",
+                 LNoise.Yellow,
+                 true)
+    );
+  LNoise.history_load ~filename:"history.txt" |> ignore;
+  LNoise.history_set ~max_length:100 |> ignore;
+  LNoise.set_completion_callback begin fun line_so_far ln_completions ->
+    if line_so_far <> "" && line_so_far.[0] = 'h' then
+      ["Hey"; "Howard"; "Hughes";"Hocus"]
+      |> List.iter (LNoise.add_completion ln_completions);
+  end;
+  ["These are OCaml bindings to linenoise";
+   "get tab completion with <TAB>, type h then hit <TAB>";
+   "type quit to exit gracefully";
+   "By Edgar Aroutiounian\n"]
+  |> List.iter print_endline;
+  (fun from_user ->
+     if from_user = "quit" then exit 0;
+     LNoise.history_add from_user |> ignore;
+     LNoise.history_save ~filename:"history.txt" |> ignore;
+     Printf.sprintf "Got: %s" from_user |> print_endline
+  )
   |> user_input "test_program> "
 
 and compile with: