Version 2.0.0

2020-07-07 15:53:00 +02:00
parent 16ecac7329
commit 30c9acc2bb
4 changed files with 136 additions and 66 deletions
--- a/doc/op.html
+++ b/doc/op.html
@@ -101,34 +101,44 @@ function main() {
 <li>
  <a class="reference reference-toplevel" href="#7" id="57">Types</a>
  <ul class="simple simple-toc-section">
-      <li><a class="reference" href="#OP"
-    title="OP[T] = object
-  case isOk*: bool
+      <li><a class="reference" href="#Either"
+    title="Either[A; B] = object
+  case isA*: bool
  of true:
-      val*: T
+      a*: A

  of false:
-      error*: string"><wbr />OP<span class="attachedType"></span></a></li>
-
-  </ul>
-</li>
-<li>
-  <a class="reference reference-toplevel" href="#12" id="62">Procs</a>
-  <ul class="simple simple-toc-section">
-      <li><a class="reference" href="#ok%2CT"
-    title="ok[T](val: T): OP[T]"><wbr />ok<span class="attachedType">OP</span></a></li>
-  <li><a class="reference" href="#fail%2COP%2Cstring"
-    title="fail(op: OP; msg: string): OP"><wbr />fail<span class="attachedType">OP</span></a></li>
-  <li><a class="reference" href="#fail%2Ctypedesc%2Cstring"
-    title="fail(T: typedesc; msg: string): OP[T]"><wbr />fail<span class="attachedType">OP</span></a></li>
+      b*: B"><wbr />Either<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#OP"
+    title="OP[T] = Either[T, string]"><wbr />OP<span class="attachedType"></span></a></li>

  </ul>
 </li>
 <li>
  <a class="reference reference-toplevel" href="#18" id="68">Templates</a>
  <ul class="simple simple-toc-section">
-      <li><a class="reference" href="#fail.t%2C%2Cstring"
+      <li><a class="reference" href="#checkA.t%2CEither"
+    title="checkA(self: Either): bool"><wbr />check<wbr />A<span class="attachedType">Either</span></a></li>
+  <li><a class="reference" href="#getA.t%2CEither%5BA%2CB%5D"
+    title="getA[A; B](self: Either[A, B]): A"><wbr />get<wbr />A<span class="attachedType">Either</span></a></li>
+  <li><a class="reference" href="#getB.t%2CEither%5BA%2CB%5D"
+    title="getB[A; B](self: Either[A, B]): B"><wbr />get<wbr />B<span class="attachedType">Either</span></a></li>
+  <li><a class="reference" href="#isOK.t%2COP"
+    title="isOK(self: OP): bool"><wbr />is<wbr />OK<span class="attachedType">OP</span></a></li>
+  <li><a class="reference" href="#val.t%2COP"
+    title="val(self: OP): auto"><wbr />val<span class="attachedType">OP</span></a></li>
+  <li><a class="reference" href="#error.t%2COP"
+    title="error(self: OP): auto"><wbr />error<span class="attachedType">OP</span></a></li>
+  <li><a class="reference" href="#ok.t%2CT"
+    title="ok[T](val: T): OP[T]"><wbr />ok<span class="attachedType">OP</span></a></li>
+  <li><a class="reference" href="#ok.t%2COP%5BT%5D%2CT"
+    title="ok[T](self: var OP[T]; val: T)"><wbr />ok<span class="attachedType">OP</span></a></li>
+  <li><a class="reference" href="#fail.t%2C%2Cstring"
    title="fail[T; ](O: type OP[T]; msg: string): O:type"><wbr />fail<span class="attachedType">OP</span></a></li>
+  <li><a class="reference" href="#fail.t%2Ctypedesc%2Cstring"
+    title="fail(T: typedesc; msg: string): OP[T]"><wbr />fail<span class="attachedType">OP</span></a></li>
+  <li><a class="reference" href="#fail.t%2COP%2Cstring"
+    title="fail(op: OP; msg: string): OP"><wbr />fail<span class="attachedType">OP</span></a></li>
  <li><a class="reference" href="#fail.t%2Cstatic%5Bstring%5D"
    title="fail(msg: static[string]): auto"><wbr />fail<span class="attachedType"></span></a></li>

@@ -160,19 +170,26 @@ function main() {
  <div class="section" id="7">
 <h1><a class="toc-backref" href="#7">Types</a></h1>
 <dl class="item">
-<a id="OP"></a>
-<dt><pre><a href="op.html#OP"><span class="Identifier">OP</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span> <span class="Other">=</span> <span class="Keyword">object</span>
-  <span class="Keyword">case</span> <span class="Identifier">isOk</span><span class="Operator">*</span><span class="Other">:</span> <span class="Identifier">bool</span>
+<a id="Either"></a>
+<dt><pre><a href="op.html#Either"><span class="Identifier">Either</span></a><span class="Other">[</span><span class="Identifier">A</span><span class="Other">;</span> <span class="Identifier">B</span><span class="Other">]</span> <span class="Other">=</span> <span class="Keyword">object</span>
+  <span class="Keyword">case</span> <span class="Identifier">isA</span><span class="Operator">*</span><span class="Other">:</span> <span class="Identifier">bool</span>
  <span class="Keyword">of</span> <span class="Identifier">true</span><span class="Other">:</span>
-      <span class="Identifier">val</span><span class="Operator">*</span><span class="Other">:</span> <span class="Identifier">T</span>
+      <span class="Identifier">a</span><span class="Operator">*</span><span class="Other">:</span> <span class="Identifier">A</span>

  <span class="Keyword">of</span> <span class="Identifier">false</span><span class="Other">:</span>
-      <span class="Identifier">error</span><span class="Operator">*</span><span class="Other">:</span> <span class="Identifier">string</span>
+      <span class="Identifier">b</span><span class="Operator">*</span><span class="Other">:</span> <span class="Identifier">B</span>

  </pre></dt>
 <dd>

-<p>Object to wrap the result of an operation.</p>
+An <tt class="docutils literal"><span class="pre">Either</span></tt> object can hold either one value or the other, but never both
+
+</dd>
+<a id="OP"></a>
+<dt><pre><a href="op.html#OP"><span class="Identifier">OP</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span> <span class="Other">=</span> <a href="op.html#Either"><span class="Identifier">Either</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">,</span> <span class="Identifier">string</span><span class="Other">]</span></pre></dt>
+<dd>
+
+<p>Object to wrap the result of an operation. Alias of <tt class="docutils literal"><span class="pre">Either</span></tt> with a string as error message</p>
 <p>The type is discriminated by the <tt class="docutils literal"><span class="pre">isOK</span></tt> bool. So it is an compiler error to try to access the value without checking if the operation was successful.</p>
 <ul class="simple"><li><tt class="docutils literal"><span class="pre">isOk</span></tt>: Indicates if the operation was successful</li>
 <li><tt class="docutils literal"><span class="pre">val</span></tt>: If successful, this will hold the real result value</li>
@@ -183,32 +200,67 @@ function main() {
 </dd>

 </dl></div>
-<div class="section" id="12">
-<h1><a class="toc-backref" href="#12">Procs</a></h1>
+<div class="section" id="18">
+<h1><a class="toc-backref" href="#18">Templates</a></h1>
 <dl class="item">
-<a id="ok,T"></a>
-<dt><pre><span class="Keyword">proc</span> <a href="#ok%2CT"><span class="Identifier">ok</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span><span class="Other">(</span><span class="Identifier">val</span><span class="Other">:</span> <span class="Identifier">T</span><span class="Other">)</span><span class="Other">:</span> <a href="op.html#OP"><span class="Identifier">OP</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">inline</span></span><span class="Other">.}</span></span></pre></dt>
+<a id="checkA.t,Either"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#checkA.t%2CEither"><span class="Identifier">checkA</span></a><span class="Other">(</span><span class="Identifier">self</span><span class="Other">:</span> <a href="op.html#Either"><span class="Identifier">Either</span></a><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">bool</span></pre></dt>
+<dd>
+
+
+
+</dd>
+<a id="getA.t,Either[A,B]"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#getA.t%2CEither%5BA%2CB%5D"><span class="Identifier">getA</span></a><span class="Other">[</span><span class="Identifier">A</span><span class="Other">;</span> <span class="Identifier">B</span><span class="Other">]</span><span class="Other">(</span><span class="Identifier">self</span><span class="Other">:</span> <a href="op.html#Either"><span class="Identifier">Either</span></a><span class="Other">[</span><span class="Identifier">A</span><span class="Other">,</span> <span class="Identifier">B</span><span class="Other">]</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">A</span></pre></dt>
+<dd>
+
+
+
+</dd>
+<a id="getB.t,Either[A,B]"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#getB.t%2CEither%5BA%2CB%5D"><span class="Identifier">getB</span></a><span class="Other">[</span><span class="Identifier">A</span><span class="Other">;</span> <span class="Identifier">B</span><span class="Other">]</span><span class="Other">(</span><span class="Identifier">self</span><span class="Other">:</span> <a href="op.html#Either"><span class="Identifier">Either</span></a><span class="Other">[</span><span class="Identifier">A</span><span class="Other">,</span> <span class="Identifier">B</span><span class="Other">]</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">B</span></pre></dt>
+<dd>
+
+
+
+</dd>
+<a id="isOK.t,OP"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#isOK.t%2COP"><span class="Identifier">isOK</span></a><span class="Other">(</span><span class="Identifier">self</span><span class="Other">:</span> <a href="op.html#OP"><span class="Identifier">OP</span></a><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">bool</span></pre></dt>
+<dd>
+
+
+
+</dd>
+<a id="val.t,OP"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#val.t%2COP"><span class="Identifier">val</span></a><span class="Other">(</span><span class="Identifier">self</span><span class="Other">:</span> <a href="op.html#OP"><span class="Identifier">OP</span></a><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">auto</span></pre></dt>
+<dd>
+
+
+
+</dd>
+<a id="error.t,OP"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#error.t%2COP"><span class="Identifier">error</span></a><span class="Other">(</span><span class="Identifier">self</span><span class="Other">:</span> <a href="op.html#OP"><span class="Identifier">OP</span></a><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">auto</span></pre></dt>
+<dd>
+
+
+
+</dd>
+<a id="ok.t,T"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#ok.t%2CT"><span class="Identifier">ok</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span><span class="Other">(</span><span class="Identifier">val</span><span class="Other">:</span> <span class="Identifier">T</span><span class="Other">)</span><span class="Other">:</span> <a href="op.html#OP"><span class="Identifier">OP</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span></pre></dt>
 <dd>

 Wraps the given value in a successful operation result.

 </dd>
-<a id="fail,OP,string"></a>
-<dt><pre><span class="Keyword">proc</span> <a href="#fail%2COP%2Cstring"><span class="Identifier">fail</span></a><span class="Other">(</span><span class="Identifier">op</span><span class="Other">:</span> <a href="op.html#OP"><span class="Identifier">OP</span></a><span class="Other">;</span> <span class="Identifier">msg</span><span class="Other">:</span> <span class="Identifier">string</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">OP</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">inline</span></span><span class="Other">.}</span></span></pre></dt>
+<a id="ok.t,OP[T],T"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#ok.t%2COP%5BT%5D%2CT"><span class="Identifier">ok</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span><span class="Other">(</span><span class="Identifier">self</span><span class="Other">:</span> <span class="Keyword">var</span> <a href="op.html#OP"><span class="Identifier">OP</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span><span class="Other">;</span> <span class="Identifier">val</span><span class="Other">:</span> <span class="Identifier">T</span><span class="Other">)</span></pre></dt>
 <dd>

-Will create a new operation result with the given error message. The type for the operation result is taken from the <tt class="docutils literal"><span class="pre">op</span></tt> argument.
-<p><strong class="examples_text">Examples:</strong></p>
-<pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">someProc</span><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">OP</span><span class="Other">[</span><span class="Identifier">int</span><span class="Other">]</span> <span class="Other">=</span>
-  <span class="Identifier">result</span><span class="Other">.</span><span class="Identifier">fail</span> <span class="StringLit">&quot;Not implemented!&quot;</span>
-
-<span class="Keyword">let</span> <span class="Identifier">data</span> <span class="Other">=</span> <span class="Identifier">someProc</span><span class="Other">(</span><span class="Other">)</span>
-<span class="Identifier">assert</span> <span class="Identifier">data</span><span class="Other">.</span><span class="Identifier">isOk</span> <span class="Operator">==</span> <span class="Identifier">false</span>
-<span class="Identifier">assert</span> <span class="Identifier">data</span><span class="Other">.</span><span class="Identifier">error</span> <span class="Operator">==</span> <span class="StringLit">&quot;Not implemented!&quot;</span></pre>
+Set the result to the given value

 </dd>
-<a id="fail,typedesc,string"></a>
-<dt><pre><span class="Keyword">proc</span> <a href="#fail%2Ctypedesc%2Cstring"><span class="Identifier">fail</span></a><span class="Other">(</span><span class="Identifier">T</span><span class="Other">:</span> <span class="Identifier">typedesc</span><span class="Other">;</span> <span class="Identifier">msg</span><span class="Other">:</span> <span class="Identifier">string</span><span class="Other">)</span><span class="Other">:</span> <a href="op.html#OP"><span class="Identifier">OP</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><span class="Identifier">inline</span></span><span class="Other">.}</span></span></pre></dt>
+<a id="fail.t,,string"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#fail.t%2C%2Cstring"><span class="Identifier">fail</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">;</span> <span class="Other">]</span><span class="Other">(</span><span class="Identifier">O</span><span class="Other">:</span> <span class="Keyword">type</span> <a href="op.html#OP"><span class="Identifier">OP</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span><span class="Other">;</span> <span class="Identifier">msg</span><span class="Other">:</span> <span class="Identifier">string</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">O:type</span></pre></dt>
 <dd>

 <p>Will create a new operation result with the given error message. The type for the operation result is given explicitly.</p>
@@ -219,17 +271,31 @@ Will create a new operation result with the given error message. The type for th


 </dd>
-
-</dl></div>
-<div class="section" id="18">
-<h1><a class="toc-backref" href="#18">Templates</a></h1>
-<dl class="item">
-<a id="fail.t,,string"></a>
-<dt><pre><span class="Keyword">template</span> <a href="#fail.t%2C%2Cstring"><span class="Identifier">fail</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">;</span> <span class="Other">]</span><span class="Other">(</span><span class="Identifier">O</span><span class="Other">:</span> <span class="Keyword">type</span> <a href="op.html#OP"><span class="Identifier">OP</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span><span class="Other">;</span> <span class="Identifier">msg</span><span class="Other">:</span> <span class="Identifier">string</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">O:type</span></pre></dt>
+<a id="fail.t,typedesc,string"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#fail.t%2Ctypedesc%2Cstring"><span class="Identifier">fail</span></a><span class="Other">(</span><span class="Identifier">T</span><span class="Other">:</span> <span class="Identifier">typedesc</span><span class="Other">;</span> <span class="Identifier">msg</span><span class="Other">:</span> <span class="Identifier">string</span><span class="Other">)</span><span class="Other">:</span> <a href="op.html#OP"><span class="Identifier">OP</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span></pre></dt>
 <dd>

+<p>Will create a new operation result with the given error message. The type for the operation result is given explicitly.</p>
+<p><strong>See Also:</strong></p>
+<ul class="simple"><li><a class="reference external" href="#fail,OP,string">fail proc</a></li>
+<li><a class="reference external" href="#fail.t,static[string]">fail template</a></li>
+</ul>


+</dd>
+<a id="fail.t,OP,string"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#fail.t%2COP%2Cstring"><span class="Identifier">fail</span></a><span class="Other">(</span><span class="Identifier">op</span><span class="Other">:</span> <a href="op.html#OP"><span class="Identifier">OP</span></a><span class="Other">;</span> <span class="Identifier">msg</span><span class="Other">:</span> <span class="Identifier">string</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">OP</span></pre></dt>
+<dd>
+
+Will create a new operation result with the given error message. The type for the operation result is taken from the <tt class="docutils literal"><span class="pre">op</span></tt> argument.
+<p><strong class="examples_text">Examples:</strong></p>
+<pre class="listing"><span class="Keyword">proc</span> <span class="Identifier">someProc</span><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">OP</span><span class="Other">[</span><span class="Identifier">int</span><span class="Other">]</span> <span class="Other">=</span>
+  <span class="Identifier">result</span><span class="Other">.</span><span class="Identifier">fail</span> <span class="StringLit">&quot;Not implemented!&quot;</span>
+
+<span class="Keyword">let</span> <span class="Identifier">data</span> <span class="Other">=</span> <span class="Identifier">someProc</span><span class="Other">(</span><span class="Other">)</span>
+<span class="Identifier">assert</span> <span class="Identifier">data</span><span class="Other">.</span><span class="Identifier">isOk</span> <span class="Operator">==</span> <span class="Identifier">false</span>
+<span class="Identifier">assert</span> <span class="Identifier">data</span><span class="Other">.</span><span class="Identifier">error</span> <span class="Operator">==</span> <span class="StringLit">&quot;Not implemented!&quot;</span></pre>
+
 </dd>
 <a id="fail.t,static[string]"></a>
 <dt><pre><span class="Keyword">template</span> <a href="#fail.t%2Cstatic%5Bstring%5D"><span class="Identifier">fail</span></a><span class="Other">(</span><span class="Identifier">msg</span><span class="Other">:</span> <span class="Identifier">static</span><span class="Other">[</span><span class="Identifier">string</span><span class="Other">]</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">auto</span></pre></dt>
@@ -248,7 +314,7 @@ Will create a new operation result with the given error message. The type for th
      <div class="twelve-columns footer">
        <span class="nim-sprite"></span>
        <br/>
-        <small style="color: var(--hint);">Made with Nim. Generated: 2020-07-02 17:57:25 UTC</small>
+        <small style="color: var(--hint);">Made with Nim. Generated: 2020-07-07 13:52:22 UTC</small>
      </div>
    </div>
  </div>
--- a/op.nimble
+++ b/op.nimble
@@ -10,5 +10,9 @@ srcDir        = "src"

 requires "nim >= 1.2.4"

-task genDocs, "Generate Docs":
+task docs, "Generate Docs":
  exec "nim doc --project -o:doc src/op.nim"
+
+task bench, "Runs the benchmark code":
+  exec "nim c -r benchmarks/bench.nim"
+
--- a/src/op.nim
+++ b/src/op.nim
@@ -25,37 +25,38 @@
 ##  assert r.isOk == false
 ##  assert r.error == "Cannot divide by zero!"

-import macros
-
 type
  Either*[A, B] = object
-    case isA: bool
+    ## An `Either` object can hold either one value or the other, but never both
+    case isA*: bool
    of true:
-      a: A
+      a*: A
    of false:
-      b: B
+      b*: B

  OP*[T] = Either[T, string]
+    ## Object to wrap the result of an operation.
    ## Alias of `Either` with a string as error message
-
+    ##
+    ## The type is discriminated by the `isOK` bool.
+    ## So it is an compiler error to try to access the value without checking
+    ## if the operation was successful.
+    ##
+    ## - `isOk`: Indicates if the operation was successful
+    ## - `val`: If successful, this will hold the real result value
+    ## - `error`: Otherwise this will hold an error message

 template checkA*(self: Either): bool = self.isA
 template getA*[A, B](self: Either[A, B]): A = self.a
 template getB*[A, B](self: Either[A, B]): B = self.b

-proc newEitherA*[A, B](a: A): Either[A, B] {.inline.} =
-  Either[A, B](isA: true, a: a)
-
-proc newEitherB*[A, B](b: B): Either[A, B] {.inline.} =
-  Either[A, B](isA: false, b: b)
-
 template isOK*(self: OP): bool = checkA(self)
 template val*(self: OP): auto = getA(self)
 template error*(self: OP): auto = getB(self)

 template ok*[T](val: T): OP[T] =
  ## Wraps the given value in a successful operation result.
-  newEitherA[T, string](val)
+  OP[T](isA: true, a: val)

 template ok*[T](self: var OP[T], val: T) =
  ## Set the result to the given value
@@ -68,7 +69,7 @@ template fail*[T](O: type OP[T], msg: string): O =
  ## **See Also:**
  ## - `fail proc<#fail,OP,string>`_
  ## - `fail template<#fail.t,static[string]>`_
-  newEitherB[T, string](msg)
+  OP[T](isA: false, b: msg)

 template fail*(T: typedesc, msg: string): OP[T] =
  ## Will create a new operation result with the given error message.
@@ -77,7 +78,7 @@ template fail*(T: typedesc, msg: string): OP[T] =
  ## **See Also:**
  ## - `fail proc<#fail,OP,string>`_
  ## - `fail template<#fail.t,static[string]>`_
-  newEitherB[T, string](msg)
+  OP[typeof(T)](isA: false, b: msg)

 template fail*(op: OP, msg: string): OP =
  ## Will create a new operation result with the given error message.
@@ -91,5 +92,4 @@ template fail*(op: OP, msg: string): OP =
    assert data.error == "Not implemented!"
  fail(typeof(op), msg)

-
 template fail*(msg: static[string]): auto = fail(typeof(result), msg)
--- a/tests/tests.nim
+++ b/tests/tests.nim
@@ -15,7 +15,7 @@ suite "Basic tests":
    check test.isOk == true

  test "Check fail":
-    let test = fail(void, "no data here")
+    let test = int.fail "no data here"
    check test.isOk == false

  test "Check proc results":