# HG changeset patch
# User Evan Hanson <evhan@foldling.org>
# Date 1608539288 -46800
#      Mon Dec 21 21:28:08 2020 +1300
# Node ID 97ff74dd7b54e0d23c6c764fcc2de34fe4f618cb
# Parent  eb994cedcf6a2af79d4ca6626e349af7cfc5c189
Add README and LICENSE

diff --git a/LICENSE b/LICENSE
new file mode 100644
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,25 @@
+Copyright (c) 2020, Evan Hanson <evhan@foldling.org>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+  * Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+  * Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+  * The name of the author may not be used to endorse or promote products
+    derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/README.md b/README.md
new file mode 100644
--- /dev/null
+++ b/README.md
@@ -0,0 +1,96 @@
+# sq
+
+sq is a [jq][] wrapper for S-expressions.
+
+Specifically, it round-trips [SRFI-180][]-formatted inputs through jq, allowing
+you to use that program's filters and flags to manipulate Scheme data.
+
+Think of it like [yq][], but for S-expressions instead of YAML.
+
+[jq]: https://github.com/stedolan/jq
+[yq]: https://github.com/kislyuk/yq
+
+## Resources
+
+ * Sources: <https://hg.sr.ht/~evhan/sq>
+ * Issues: <https://todo.sr.ht/~evhan/sq>
+
+## Installation
+
+Use your distribution's package manager to install CHICKEN 5.2 or newer, then
+run:
+
+``` sh
+chicken-install -s sq
+```
+
+Because sq calls jq internally, you will also need to install jq according to
+the [download instructions][jq/download] for your platform.
+
+[jq/download]: https://stedolan.github.io/jq/download/
+
+## Usage
+
+Invoke sq just like you would jq. It accepts either S-expressions or JSON as
+input. When S-expressions are used, they must follow the format described by
+[SRFI-180][], for which the mapping between JSON types and Scheme objects is
+the following:
+
+ - `null` → the symbol `null`
+ - `true` → `#t`
+ - `false` → `#f`
+ - number → number
+ - string → string
+ - array → vector
+ - object → association list with keys that are symbols
+
+By default, sq generates S-expressions:
+
+``` sh
+$ echo '{"greeting": "hello"}'  | sq
+((greeting . "hello"))
+$ echo '((greeting . "hello"))' | sq
+((greeting . "hello"))
+```
+
+To generate JSON instead, pass the `-j` or `--json` flag:
+
+``` sh
+$ echo '{"greeting": "hello"}'  | sq --json
+{
+  "greeting": "hello"
+}
+$ echo '((greeting . "hello"))' | sq --json
+{
+  "greeting": "hello"
+}
+```
+
+Any other flags (apart from `--help` and `--version`) are passed directly
+through to jq. For example, use the `-r` or `--raw-output` flag to output
+string values:
+
+``` sh
+$ echo '{"greeting": "hello"}'  | sq --raw-output .greeting
+hello
+$ echo '((greeting . "hello"))' | sq --raw-output .greeting
+hello
+```
+
+Note that not all flags will work with sq. For example, the `--color-output`
+flag will only work when combined with `--json`, and the `--null-input` flag is
+obviously useless since sq works by sending input to jq.
+
+[SRFI-180]: https://srfi.schemers.org/srfi-180/srfi-180.html
+
+## Known Problems
+
+- Parsing is slow for large JSON outputs generated by jq.
+- The program should probably just execute jq when `--json` is used with JSON inputs.
+- There is no validation of command line flags for compatibility.
+- Error messages for invalid S-expression inputs are not very helpful.
+- There are no tests.
+
+## License
+
+Three-clause BSD. See LICENSE for details.