Better error checking, docs

Signed-off-by: Dan S. Camper <[email protected]>

Author: dancamper

LICENSE.txt

@@ -0,0 +1,11 @@
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

README.md

@@ -1,9 +1,89 @@
-# json2ecl
-### _Dan S. Camper_
+## Description
 
-This is a project to do ... something.
+json2ecl examines JSON data and deduces the ECL RECORD definitions necessary to parse it.
+The resulting ECL definitions are returned via standard out, suitable for piping or copying
+and pasting into your favorite IDE.
 
-## License
+JSON data can be supplied as one or more files or via standard input.
+
+Multiple files, if provided, are parsed as if they should have the same record structure.
+This is useful for cases where you suspect that not all JSON key/value objects are fully
+defined in one file, but other files may contain the missing data.
+
+## Requirements
+
+This project was written using SBCL and it has not been tested with other flavors
+of Lisp.  There are very few dependencies, however, so it should work out of the box
+with all of the common Lisp distributions.
+
+The following dependencies are required:
+
+- ASDF (version 3.3.6 or later)
+- Quicklisp
+- Buildapp
+  - Used to build the binary
+  - [https://www.xach.com/lisp/buildapp/](https://www.xach.com/lisp/buildapp/)
+
+## How to Build (for *nix-compatible systems)
+
+1. Clone this repo:  `git clone https://github.com/dancamper/json2ecl.git`
+1. Change directory: `cd json2ecl`
+1. Run build script: ./build_binary.sh
+1. Final binary is now bin/json2ecl.  You can move or copy that binary to a location on your path.
+
+## How to Use
+
+Usage: `json2ecl [OPTIONS] [FILE...]`
+
+json2ecl examines JSON data and deduces the ECL RECORD definitions necessary to
+parse it. The resulting ECL definitions are returned via standard out, suitable
+for piping or copying and pasting into your favorite IDE.
 
-MIT
+JSON data can be supplied as one or more files or via standard input.
+
+Multiple files, if provided, are parsed as if they should have the same record
+structure. This is useful for cases where you suspect that not all JSON
+key/value objects are fully defined in one file, but other files may contain the
+missing data.
+
+```
+Options:
+  -v, --version         Display version and exit.
+  -h, --help            Display help and exit.
+```
+
+## Examples
+
+Assuming file foo.json contains the following contents:
+
+```json
+{
+  "foo": "bar",
+  "start": 12,
+  "end": 98.76
+}
+```
+
+Simple parsing of those contents:
+
+````
+$ json2ecl foo.json
+FOO_001_LAYOUT := RECORD
+    UTF8 foo {XPATH('foo')};
+    INTEGER start {XPATH('start')};
+    REAL f_end {XPATH('end')};
+END;
+````
+
+````
+$ cat foo.json | json2ecl 
+TOPLEVEL_231_001_LAYOUT := RECORD
+    UTF8 foo {XPATH('foo')};
+    INTEGER start {XPATH('start')};
+    REAL f_end {XPATH('end')};
+END;
+````
+
+## License
 
+Apache 2.0

json2ecl.asd

@@ -10,7 +10,7 @@
   :description "Examines JSON data and deduces the ECL RECORD definitions necessary to parse it."
   :author "Dan S. Camper"
   :license  "MIT"
-  :version "0.0.4"
+  :version "0.0.5"
   :serial t
   :depends-on (#:adopt #:com.inuoe.jzon #:with-user-abort)
   :components ((:file "package")

json2ecl.lisp

@@ -76,7 +76,8 @@
     (null "STRING")
     (string "STRING")
     (utf8 "UTF8")
-    (number "INTEGER")))
+    (number "INTEGER")
+    (float "REAL")))
 
 (defun dataset-datatype-name (name)
   (format nil "DATASET(~A)" (layout-name name)))
@@ -148,12 +149,13 @@
     ((eql nil) 'boolean)
     ((eql null) 'null)
     (integer 'number)
-    (double-float 'number)
+    (double-float 'float)
     (string 'utf8)))
 
 (defun common-type (new-type old-type)
   (cond ((not old-type) new-type)
         ((or (eql old-type 'utf8) (eql new-type 'utf8)) 'utf8)
+        ((or (eql old-type 'float) (eql new-type 'float)) 'float)
         ((not (eql old-type new-type)) 'string)
         (t new-type)))
 

userio.lisp

@@ -20,20 +20,37 @@
                      :short #\h
                      :reduce (constantly t)))
 
+(adopt:define-string *help-text*
+  "json2ecl examines JSON data and deduces the ECL RECORD definitions necessary to parse it. ~
+The resulting ECL definitions are returned via standard out, suitable for piping or copying ~
+and pasting into your favorite IDE.~@
+~@
+JSON data can be supplied as one or more files or via standard input.~@
+~@
+Multiple files, if provided, are parsed as if they should have the same record structure. ~
+This is useful for cases where you suspect that not all JSON key/value objects are fully ~
+defined in one file, but other files may contain the missing data.")
+
 (defparameter *ui*
   (adopt:make-interface :name "json2ecl"
-                        :usage "[OPTIONS] FILE ..."
+                        :usage "[OPTIONS] [FILE...]"
                         :summary (format nil "analyze JSON data and emit ECL record ~
                                               definitions that can parse that data")
-                        :help (format nil "json2ecl examines JSON data and deduces ~
-                                           the ECL RECORD definitions necessary to parse it.")
+                        :help *help-text*
                         :contents (list
                                    *option-version*
                                    *option-help*)))
 
 ;;;
 
-(define-condition user-error (error) ())
+(define-condition user-error (error)
+  ())
+
+(define-condition missing-file (user-error)
+  ((path :initarg :path))
+  (:report
+   (lambda (c s)
+     (format s "missing file '~A'" (slot-value c 'path)))))
 
 ;;;
 
@@ -44,13 +61,20 @@
 (defun run (args)
   (let* ((argc (length args))
          (args (if (plusp argc) args (list *standard-input*))))
+    ;; Verify that files exist
+    (when (plusp argc)
+      (loop for input in args
+            do (unless (uiop:probe-file* input)
+                 (error 'missing-file :path input))))
     (let ((toplevel-name (if (= argc 1)
                              (pathname-name (uiop:probe-file* (car args)))
                              (format nil "~A" (gensym "toplevel_"))))
           (result-obj nil))
+      ;; Parse files or standard input
       (loop for input in args
             do (let ((one-item (or (uiop:probe-file* input) input)))
                  (setf result-obj (process-file-or-stream one-item result-obj))))
+      ;; Emit ECL record definitions
       (setf *layout-names* nil)
       (format t "~A" (as-ecl-recdef result-obj toplevel-name)))))