Browse code
Add license and description to .asd
Ed Langley authored on 09/07/2018 06:05:18Showing 3 changed files
| 1 | 1 |
new file mode 100644 |
| ... | ... |
@@ -0,0 +1,22 @@ |
| 1 |
+MIT License |
|
| 2 |
+ |
|
| 3 |
+Copyright (c) 2018 Edward Langley |
|
| 4 |
+ |
|
| 5 |
+Permission is hereby granted, free of charge, to any person obtaining |
|
| 6 |
+a copy of this software and associated documentation files (the |
|
| 7 |
+"Software"), to deal in the Software without restriction, including |
|
| 8 |
+without limitation the rights to use, copy, modify, merge, publish, |
|
| 9 |
+distribute, sublicense, and/or sell copies of the Software, and to |
|
| 10 |
+permit persons to whom the Software is furnished to do so, subject to |
|
| 11 |
+the following conditions: |
|
| 12 |
+ |
|
| 13 |
+The above copyright notice and this permission notice shall be |
|
| 14 |
+included in all copies or substantial portions of the Software. |
|
| 15 |
+ |
|
| 16 |
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, |
|
| 17 |
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF |
|
| 18 |
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND |
|
| 19 |
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE |
|
| 20 |
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION |
|
| 21 |
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION |
|
| 22 |
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| 0 | 23 |
new file mode 100644 |
| ... | ... |
@@ -0,0 +1,68 @@ |
| 1 |
+<?xml version="1.0" encoding="UTF-8" ?> |
|
| 2 |
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" |
|
| 3 |
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
|
| 4 |
+ |
|
| 5 |
+<html xmlns="http://www.w3.org/1999/xhtml"> |
|
| 6 |
+ |
|
| 7 |
+<head> |
|
| 8 |
+<title>README.html</title> |
|
| 9 |
+ |
|
| 10 |
+</head> |
|
| 11 |
+ |
|
| 12 |
+<body> |
|
| 13 |
+ |
|
| 14 |
+<h1>Installation</h1> |
|
| 15 |
+ |
|
| 16 |
+<ul> |
|
| 17 |
+<li>Clone this repository somewhere ASDF can find the system: e.g. <code>git clone https://github.com/fiddlerwoaroof/cl-edn.git ~/quicklisp/local-projects/cl-edn/</code></li> |
|
| 18 |
+<li>At a REPL, <code>(ql:quickload :cl-edn)</code></li> |
|
| 19 |
+</ul> |
|
| 20 |
+ |
|
| 21 |
+<h1>Usage</h1> |
|
| 22 |
+ |
|
| 23 |
+<p>This library divides the task of parsing EDN into two stages. In the |
|
| 24 |
+first stage, implemented by <code>(EDN:READ-EDN string)</code> an EDN file is is |
|
| 25 |
+parsed into an AST where primitives are converted into lisp values and |
|
| 26 |
+compound forms are converted into lists of the form |
|
| 27 |
+<code>(type-specifier . data)</code>. This AST can be passed to |
|
| 28 |
+<code>(EDN:SYNTHESIZE implementation ast)</code> to produce datastructures of a |
|
| 29 |
+specific kind. The system <code>cl-edn/fset</code> provides a synthesizer that |
|
| 30 |
+produces appropriate fset datastructures. The system |
|
| 31 |
+<code>cl-edn/fset-lossy</code> produces fset datastructures, but forces symbols |
|
| 32 |
+and keywords to have uppercase names, for easier interoperation with |
|
| 33 |
+CL's default readtable. As a convenience, there is also |
|
| 34 |
+<code>(EDN:PARSE string &optional (implementation 'fset))</code> that combines |
|
| 35 |
+the two steps into a single call. These implementations can passed to |
|
| 36 |
+<code>PARSE</code> and <code>SYNTHESIZE</code> either as the symbols <code>EDN:FSET</code> and |
|
| 37 |
+<code>EDN:FSET-LOSSY</code> or by instantiating the classes named by those symbols.</p> |
|
| 38 |
+ |
|
| 39 |
+<h1>EXTENSION</h1> |
|
| 40 |
+ |
|
| 41 |
+<p><code>EDN:SYNTHESIZE</code> is a generic function that takes an implementation as |
|
| 42 |
+the first argument. The main system, <code>CL-EDN</code>, provides two |
|
| 43 |
+implementations of this function: one that specializes the first |
|
| 44 |
+argument on <code>SYMBOL</code>, that just makes an instance of the class named |
|
| 45 |
+by <code>IMPLEMENTATION</code> and calls <code>EDN:SYNTHESIZE</code> with the instance as |
|
| 46 |
+its first argument; the other implementation inspects the second |
|
| 47 |
+argument and, if it is a list, it delegates to |
|
| 48 |
+<code>(EDN:SYNTHESIZE-COMPOUND IMPLEMENTATION DISCRIMINATOR ARGS)</code>, the |
|
| 49 |
+head of the list as <code>DISCRIMINATOR</code> and the tail as <code>ARGS</code>. The |
|
| 50 |
+default implementation of this generic also provides methods for |
|
| 51 |
+strings, symbols and keywords that produce the relevant lisp types, as |
|
| 52 |
+well as an implementation for tagged literals that implements <code>#inst</code> |
|
| 53 |
+and <code>#uuid</code> and produces a form <code>(:TAGGED TAG-SYMBOL DATA)</code> where |
|
| 54 |
+<code>DATA</code> is synthesized according to the rules governing |
|
| 55 |
+<code>IMPLEMENTATION</code> (e.g. the <code>FSET</code> implementation makes <code>DATA</code> to be an |
|
| 56 |
+instance of the datastructures provided by the <code>FSET</code> library). Tags |
|
| 57 |
+can also be added to the default implementation by providing an |
|
| 58 |
+EQL-specialized method of <code>(EDN:SYNTHESIZE-TAG IMPLEMENTATION TAG ARG)</code> |
|
| 59 |
+for the symbol you want to define a behavior for. When this method is |
|
| 60 |
+called, the tag-symbol will be uppercased and converted into a common |
|
| 61 |
+lisp keyword and the <code>ARG</code> will have been synthesized according to the |
|
| 62 |
+rules provided by <code>IMPLEMENTATION</code>. To override this behavior, an |
|
| 63 |
+implementation can override <code>EDN:SYNTHESIZE-COMPOUND</code>, but such |
|
| 64 |
+implementations should either call <code>CALL-NEXT-METHOD</code> or implement |
|
| 65 |
+<code>#inst</code> and <code>#uuid</code> processing themselves.</p> |
|
| 66 |
+ |
|
| 67 |
+</body> |
|
| 68 |
+</html> |