git.fiddlerwoaroof.com
Browse code

Add more documentation

Ed Langley authored on 29/08/2019 18:30:14
Showing 2 changed files
README.org
History View file @ 6613ae6
... ... 
@@ -9,7 +9,9 @@
9 9
10 10 
 ** List-level APIs
11 11
12 
-   These are functions for getting the todo list and clearing it.
12 
+   These are functions for getting the todo list and clearing
13 
+   it. These are activated by the root route: =todos= for GET requests
14 
+   and =clear-todos= for DELETE requests.
13 15
14 16 
    #+NAME: todolist-manipulation
15 17 
    #+BEGIN_SRC lisp :tangle no
... ... 
@@ -29,7 +31,8 @@
29 31
30 32 
    This uses lisp's [[http://www.lispworks.com/documentation/HyperSpec/Body/05_a.htm][generalized references]] to abstract away the
31 33 
    storage details of the todos. We also provide a =delete-todo=
32 
-   function for removing a todo from the list.
34 
+   function for removing a todo from the list. =todo= is what backs
35 
+   the GET request for a specific todo by id.
33 36
34 37 
    #+NAME: todo-accessor
35 38 
    #+BEGIN_SRC lisp :tangle no
... ... 
@@ -51,7 +54,7 @@
51 54 
    =new-todo= is fairly trivial. It's main feature is that it has to
52 55 
    make sure the =completed= and =url= keys are set to the appropriate
53 56 
    values. Completed isn't a lisp boolean, so it serializes to JSON
54 
-   properly.
57 
+   properly. =new-todo= backs POST requests to the root endpoint.
55 58
56 59 
    #+NAME: new-todo
57 60 
    #+BEGIN_SRC lisp :tangle no
... ... 
@@ -68,7 +71,8 @@
68 71
69 72 
    =update-todo= just merges the input from the frontend into the
70 73 
    relevant todo and then makes sure that the =completed= key is a
71 
-   yason-compatible boolean.
74 
+   yason-compatible boolean. =update-todo= backs PATCH requests to the
75 
+   todo endpoint for a specific ID.
72 76
73 77 
    #+NAME: update-todo
74 78 
    #+BEGIN_SRC lisp :tangle no
docs/index.html
History View file @ 6613ae6
... ... 
@@ -3,7 +3,7 @@
3 3 
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
4 4 
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
5 5 
 <head>
6 
-<!-- 2019-08-28 Wed 23:44 -->
6 
+<!-- 2019-08-29 Thu 13:30 -->
7 7 
 <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
8 8 
 <meta name="viewport" content="width=device-width, initial-scale=1" />
9 9 
 <title>TODO backend implementation using CL and fukamachi/ningle</title>
... ... 
@@ -285,27 +285,27 @@ for the JavaScript code in this tag.
285 285 
 <h2>Table of Contents</h2>
286 286 
 <div id="text-table-of-contents">
287 287 
 <ul>
288 
-<li><a href="#orga5e2729">1. todo API</a>
288 
+<li><a href="#orge26183a">1. todo API</a>
289 289 
 <ul>
290 
-<li><a href="#org64b76a1">1.1. List-level APIs</a></li>
291 
-<li><a href="#orgb6cdd53">1.2. Getting/Replacing a todo</a></li>
292 
-<li><a href="#org856e4b8">1.3. Adding and modifying todos</a></li>
293 
-<li><a href="#org2a06a4c">1.4. Examples</a></li>
290 
+<li><a href="#org7c9af4c">1.1. List-level APIs</a></li>
291 
+<li><a href="#org7cd504f">1.2. Getting/Replacing a todo</a></li>
292 
+<li><a href="#org0c4ab78">1.3. Adding and modifying todos</a></li>
293 
+<li><a href="#org460c7ef">1.4. Examples</a></li>
294 294 
 </ul>
295 295 
 </li>
296 
-<li><a href="#orgb0c97f5">2. Source</a>
296 
+<li><a href="#org54a5346">2. Source</a>
297 297 
 <ul>
298 
-<li><a href="#org39bc7c6">2.1. model.lisp source code</a></li>
299 
-<li><a href="#orgc896c62">2.2. routing.lisp source</a></li>
300 
-<li><a href="#org136cc2b">2.3. main.lisp source</a></li>
298 
+<li><a href="#org7df7206">2.1. model.lisp source code</a></li>
299 
+<li><a href="#orgaddea1e">2.2. routing.lisp source</a></li>
300 
+<li><a href="#orgf3388f3">2.3. main.lisp source</a></li>
301 301 
 </ul>
302 302 
 </li>
303 303 
 </ul>
304 304 
 </div>
305 305 
 </div>
306 306
307 
-<div id="outline-container-orga5e2729" class="outline-2">
308 
-<h2 id="orga5e2729"><span class="section-number-2">1</span> todo API</h2>
307 
+<div id="outline-container-orge26183a" class="outline-2">
308 
+<h2 id="orge26183a"><span class="section-number-2">1</span> todo API</h2>
309 309 
 <div class="outline-text-2" id="text-1">
310 310 
 <p>
311 311 
 We use a fairly simple structure for our "database": a fset map (a
... ... 
@@ -315,15 +315,17 @@ referenced as <code>*todo*</code>, but this is a detail hidden behind the API.
315 315 
 </p>
316 316 
 </div>
317 317
318 
-<div id="outline-container-org64b76a1" class="outline-3">
319 
-<h3 id="org64b76a1"><span class="section-number-3">1.1</span> List-level APIs</h3>
318 
+<div id="outline-container-org7c9af4c" class="outline-3">
319 
+<h3 id="org7c9af4c"><span class="section-number-3">1.1</span> List-level APIs</h3>
320 320 
 <div class="outline-text-3" id="text-1-1">
321 321 
 <p>
322 
-These are functions for getting the todo list and clearing it.
322 
+These are functions for getting the todo list and clearing
323 
+it. These are activated by the root route: <code>todos</code> for GET requests
324 
+and <code>clear-todos</code> for DELETE requests.
323 325 
 </p>
324 326
325 327 
 <div class="org-src-container">
326 
-<pre class="src src-lisp" id="orgcf25214"><span style="color: #8c8c8c;">(</span><span style="color: #F0DFAF;">defun</span> <span style="color: #8CD0D3;">todos</span> <span style="color: #93a8c6;">()</span>
328 
+<pre class="src src-lisp" id="orgc5c9786"><span style="color: #8c8c8c;">(</span><span style="color: #F0DFAF;">defun</span> <span style="color: #8CD0D3;">todos</span> <span style="color: #93a8c6;">()</span>
327 329 
   <span style="color: #93a8c6;">(</span>gmap:gmap <span style="font-weight: bold;">:seq</span>
328 330 
              <span style="color: #b0b1a3;">(</span><span style="color: #F0DFAF;">lambda</span> <span style="color: #97b098;">(</span>_ b<span style="color: #97b098;">)</span>
329 331 
                <span style="color: #97b098;">(</span><span style="color: #F0DFAF;">declare</span> <span style="color: #aebed8;">(</span>ignore _<span style="color: #aebed8;">)</span><span style="color: #97b098;">)</span>
... ... 
@@ -338,17 +340,18 @@ These are functions for getting the todo list and clearing it.
338 340 
 </div>
339 341 
 </div>
340 342
341 
-<div id="outline-container-orgb6cdd53" class="outline-3">
342 
-<h3 id="orgb6cdd53"><span class="section-number-3">1.2</span> Getting/Replacing a todo</h3>
343 
+<div id="outline-container-org7cd504f" class="outline-3">
344 
+<h3 id="org7cd504f"><span class="section-number-3">1.2</span> Getting/Replacing a todo</h3>
343 345 
 <div class="outline-text-3" id="text-1-2">
344 346 
 <p>
345 347 
 This uses lisp's <a href="http://www.lispworks.com/documentation/HyperSpec/Body/05_a.htm">generalized references</a> to abstract away the
346 348 
 storage details of the todos. We also provide a <code>delete-todo</code>
347 
-function for removing a todo from the list.
349 
+function for removing a todo from the list. <code>todo</code> is what backs
350 
+the GET request for a specific todo by id.
348 351 
 </p>
349 352
350 353 
 <div class="org-src-container">
351 
-<pre class="src src-lisp" id="org1588f8a"><span style="color: #8c8c8c;">(</span><span style="color: #F0DFAF;">defun</span> <span style="color: #8CD0D3;">todo</span> <span style="color: #93a8c6;">(</span>id<span style="color: #93a8c6;">)</span>
354 
+<pre class="src src-lisp" id="orgd2f1b68"><span style="color: #8c8c8c;">(</span><span style="color: #F0DFAF;">defun</span> <span style="color: #8CD0D3;">todo</span> <span style="color: #93a8c6;">(</span>id<span style="color: #93a8c6;">)</span>
352 355 
   <span style="color: #93a8c6;">(</span><span style="color: #F0DFAF;">let</span> <span style="color: #b0b1a3;">(</span><span style="color: #97b098;">(</span>todo <span style="color: #aebed8;">(</span>fset:@ *todos* id<span style="color: #aebed8;">)</span><span style="color: #97b098;">)</span><span style="color: #b0b1a3;">)</span>
353 356 
     todo<span style="color: #93a8c6;">)</span><span style="color: #8c8c8c;">)</span>
354 357
... ... 
@@ -364,18 +367,18 @@ function for removing a todo from the list.
364 367 
 </div>
365 368 
 </div>
366 369
367 
-<div id="outline-container-org856e4b8" class="outline-3">
368 
-<h3 id="org856e4b8"><span class="section-number-3">1.3</span> Adding and modifying todos</h3>
370 
+<div id="outline-container-org0c4ab78" class="outline-3">
371 
+<h3 id="org0c4ab78"><span class="section-number-3">1.3</span> Adding and modifying todos</h3>
369 372 
 <div class="outline-text-3" id="text-1-3">
370 373 
 <p>
371 374 
 <code>new-todo</code> is fairly trivial. It's main feature is that it has to
372 375 
 make sure the <code>completed</code> and <code>url</code> keys are set to the appropriate
373 376 
 values. Completed isn't a lisp boolean, so it serializes to JSON
374 
-properly.
377 
+properly. <code>new-todo</code> backs POST requests to the root endpoint.
375 378 
 </p>
376 379
377 380 
 <div class="org-src-container">
378 
-<pre class="src src-lisp" id="org9afb9a3"><span style="color: #8c8c8c;">(</span><span style="color: #F0DFAF;">defun</span> <span style="color: #8CD0D3;">new-todo</span> <span style="color: #93a8c6;">(</span>value<span style="color: #93a8c6;">)</span>
381 
+<pre class="src src-lisp" id="org7d447ff"><span style="color: #8c8c8c;">(</span><span style="color: #F0DFAF;">defun</span> <span style="color: #8CD0D3;">new-todo</span> <span style="color: #93a8c6;">(</span>value<span style="color: #93a8c6;">)</span>
379 382 
   <span style="color: #93a8c6;">(</span><span style="color: #F0DFAF;">let</span> <span style="color: #b0b1a3;">(</span><span style="color: #97b098;">(</span>id <span style="color: #aebed8;">(</span>next-id<span style="color: #aebed8;">)</span><span style="color: #97b098;">)</span><span style="color: #b0b1a3;">)</span>
380 383 
     <span style="color: #b0b1a3;">(</span>setf <span style="color: #97b098;">(</span>todo id<span style="color: #97b098;">)</span>
381 384 
           <span style="color: #97b098;">(</span>alexandria:alist-hash-table
... ... 
@@ -390,11 +393,12 @@ properly.
390 393 
 <p>
391 394 
 <code>update-todo</code> just merges the input from the frontend into the
392 395 
 relevant todo and then makes sure that the <code>completed</code> key is a
393 
-yason-compatible boolean.
396 
+yason-compatible boolean. <code>update-todo</code> backs PATCH requests to the
397 
+todo endpoint for a specific ID.
394 398 
 </p>
395 399
396 400 
 <div class="org-src-container">
397 
-<pre class="src src-lisp" id="orgb07c731"><span style="color: #8c8c8c;">(</span><span style="color: #F0DFAF;">defun</span> <span style="color: #8CD0D3;">update-todo</span> <span style="color: #93a8c6;">(</span>id v<span style="color: #93a8c6;">)</span>
401 
+<pre class="src src-lisp" id="org1f3ff77"><span style="color: #8c8c8c;">(</span><span style="color: #F0DFAF;">defun</span> <span style="color: #8CD0D3;">update-todo</span> <span style="color: #93a8c6;">(</span>id v<span style="color: #93a8c6;">)</span>
398 402 
   <span style="color: #93a8c6;">(</span>setf <span style="color: #b0b1a3;">(</span>todo id<span style="color: #b0b1a3;">)</span>
399 403 
         <span style="color: #b0b1a3;">(</span>serapeum:merge-tables <span style="color: #97b098;">(</span>or <span style="color: #aebed8;">(</span>todo id<span style="color: #aebed8;">)</span>
400 404 
                                    <span style="color: #aebed8;">(</span>make-hash-table <span style="font-weight: bold;">:test</span> 'equal<span style="color: #aebed8;">)</span><span style="color: #97b098;">)</span>
... ... 
@@ -408,8 +412,8 @@ yason-compatible boolean.
408 412 
 </div>
409 413 
 </div>
410 414
411 
-<div id="outline-container-org2a06a4c" class="outline-3">
412 
-<h3 id="org2a06a4c"><span class="section-number-3">1.4</span> Examples</h3>
415 
+<div id="outline-container-org460c7ef" class="outline-3">
416 
+<h3 id="org460c7ef"><span class="section-number-3">1.4</span> Examples</h3>
413 417 
 <div class="outline-text-3" id="text-1-4">
414 418 
 <div class="org-src-container">
415 419 
 <pre class="src src-lisp"><span style="color: #8c8c8c;">(</span><span style="color: #F0DFAF;">in-package</span> <span style="font-weight: bold;">:fwoar.todo</span><span style="color: #8c8c8c;">)</span>
... ... 
@@ -424,10 +428,10 @@ yason-compatible boolean.
424 428 
 </div>
425 429
426 430 
 <pre class="example">
427 
-(#&lt;hash-table "url": "http://localhost:5000/todo/57",
431 
+(#&lt;hash-table "url": "http://localhost:5000/todo/67",
428 432 
               "title": "get groceries",
429 433 
               "completed": YASON:FALSE&gt;
430 
- #&lt;hash-table "url": "http://localhost:5000/todo/58",
434 
+ #&lt;hash-table "url": "http://localhost:5000/todo/68",
431 435 
               "title": "write-better-documentation",
432 436 
               "completed": YASON:FALSE&gt;)
433 437 
 </pre>
... ... 
@@ -435,12 +439,12 @@ yason-compatible boolean.
435 439 
 </div>
436 440 
 </div>
437 441
438 
-<div id="outline-container-orgb0c97f5" class="outline-2">
439 
-<h2 id="orgb0c97f5"><span class="section-number-2">2</span> Source</h2>
442 
+<div id="outline-container-org54a5346" class="outline-2">
443 
+<h2 id="org54a5346"><span class="section-number-2">2</span> Source</h2>
440 444 
 <div class="outline-text-2" id="text-2">
441 445 
 </div>
442 
-<div id="outline-container-org39bc7c6" class="outline-3">
443 
-<h3 id="org39bc7c6"><span class="section-number-3">2.1</span> model.lisp source code</h3>
446 
+<div id="outline-container-org7df7206" class="outline-3">
447 
+<h3 id="org7df7206"><span class="section-number-3">2.1</span> model.lisp source code</h3>
444 448 
 <div class="outline-text-3" id="text-2-1">
445 449 
 <div class="org-src-container">
446 450 
 <pre class="src src-lisp"><span style="color: #A6A689; background-color: #2B2B2B;">;; </span><span style="color: #A6A689; background-color: #2B2B2B;">[[file:~/git_repos/lisp-sandbox/todo/README.org::package-include][package-include]]</span>
... ... 
@@ -522,8 +526,8 @@ yason-compatible boolean.
522 526 
 </div>
523 527 
 </div>
524 528
525 
-<div id="outline-container-orgc896c62" class="outline-3">
526 
-<h3 id="orgc896c62"><span class="section-number-3">2.2</span> routing.lisp source</h3>
529 
+<div id="outline-container-orgaddea1e" class="outline-3">
530 
+<h3 id="orgaddea1e"><span class="section-number-3">2.2</span> routing.lisp source</h3>
527 531 
 <div class="outline-text-3" id="text-2-2">
528 532 
 <div class="org-src-container">
529 533 
 <pre class="src src-lisp"><span style="color: #8c8c8c;">(</span><span style="color: #F0DFAF;">in-package</span> <span style="font-weight: bold;">:fwoar.todo</span><span style="color: #8c8c8c;">)</span>
... ... 
@@ -569,8 +573,8 @@ yason-compatible boolean.
569 573 
 </div>
570 574 
 </div>
571 575
572 
-<div id="outline-container-org136cc2b" class="outline-3">
573 
-<h3 id="org136cc2b"><span class="section-number-3">2.3</span> main.lisp source</h3>
576 
+<div id="outline-container-orgf3388f3" class="outline-3">
577 
+<h3 id="orgf3388f3"><span class="section-number-3">2.3</span> main.lisp source</h3>
574 578 
 <div class="outline-text-3" id="text-2-3">
575 579 
 <div class="org-src-container">
576 580 
 <pre class="src src-lisp"><span style="color: #8c8c8c;">(</span><span style="color: #F0DFAF;">in-package</span> <span style="font-weight: bold;">:fwoar.todo</span><span style="color: #8c8c8c;">)</span>
... ... 
@@ -616,7 +620,7 @@ yason-compatible boolean.
616 620 
 </div>
617 621 
 <div id="postamble" class="status">
618 622 
 <p class="author">Author: Langley</p>
619 
-<p class="date">Created: 2019-08-28 Wed 23:44</p>
623 
+<p class="date">Created: 2019-08-29 Thu 13:30</p>
620 624 
 <p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
621 625 
 </div>
622 626 
 </body>