[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[nongnu] elpa/parseclj 815ba87a77 137/185: Merge pull request #19 from c
From: |
ELPA Syncer |
Subject: |
[nongnu] elpa/parseclj 815ba87a77 137/185: Merge pull request #19 from clojure-emacs/update-readme |
Date: |
Tue, 28 Dec 2021 14:05:29 -0500 (EST) |
branch: elpa/parseclj
commit 815ba87a77f07f840d050a76b7b359ff5cf5ddab
Merge: f87278a70e 61577603f2
Author: Arne Brasseur <arne.brasseur@gmail.com>
Commit: GitHub <noreply@github.com>
Merge pull request #19 from clojure-emacs/update-readme
Update README.md with installation and usage information
---
README.md | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
parseclj.el | 4 +-
2 files changed, 120 insertions(+), 9 deletions(-)
diff --git a/README.md b/README.md
index 7d095555a9..1b930c937e 100644
--- a/README.md
+++ b/README.md
@@ -2,24 +2,135 @@
# EDN reader and Clojure parser for Emacs Lisp
-`parseclj` is an Emacs Lisp library for parsing Clojure code and EDN data. It
-supports several input and output formats, all powered by the same shift-reduce
-parser function.
+`parseclj` is an Emacs Lisp library for parsing Clojure code and [EDN
+data](https://github.com/edn-format/edn). It supports several input and output
+formats, all powered by the same shift-reduce parser function.
Take a look at the [design document](DESIGN.md) for more details.
-`parseclj` is in **alpha** state right now.
+`parseclj` is in **alpha** state right now, its API might be subject to change.
## Installation
-TODO
+Currently `parseclj` is not part of [MELPA](http://melpa.milkbox.net/), so
+the best way to install it is by getting your own copy of the `parseclj` repo
+and putting it somewhere in your Emacs
+[`load-path`](https://www.emacswiki.org/emacs/LoadPath).
+
+You can just copy-paste this code into your Emacs init file:
+
+```emacs-lisp
+(add-to-list 'load-path "/path/to/your/copy/of/parseclj/")
+```
## Usage
-TODO
+`parseclj` is actually a compound of two libraries:
+
+- `parseedn`: An EDN reader that transforms EDN to Emacs Lisp data structures.
+- `parseclj`: A Clojure parser that returns an
+ [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) that, for example,
+ given as input `(1 2 [:a :b :c])`, it looks like this:
+
+``` emacs-lisp
+((:node-type . :root)
+ (:position . 1)
+ (:children ((:node-type . :list)
+ (:position . 1)
+ (:children ((:node-type . :number)
+ (:position . 2)
+ (:form . "1")
+ (:value . 1))
+ ((:node-type . :number)
+ (:position . 4)
+ (:form . "2")
+ (:value . 2))
+ ((:node-type . :vector)
+ (:position . 6)
+ (:children ((:node-type . :keyword)
+ (:position . 7)
+ (:form . ":a")
+ (:value . :a))
+ ((:node-type . :keyword)
+ (:position . 10)
+ (:form . ":b")
+ (:value . :b))
+ ((:node-type . :keyword)
+ (:position . 13)
+ (:form . ":c")
+ (:value . :c))))))))
+```
+
+In order to use any of them, you first need to require it:
+
+```emacs-lisp
+(require 'parseclj)
+;; or...
+(require 'parseedn)
+```
+
+And then you will have the following functions at your disposal:
+
+### parseclj
+
+- `parseclj-parse-clojure` &rest string-and-options
+
+ When no arguments, parses Clojure source code into an AST and returns it.
+ When given a string as a first argument, parses it and returns the
+ corresponding AST.
+
+ A list of options can be passed down to the parsing process, particularly:
+ * `:lexical-preservation`: a boolean value to retain whitespace, comments,
+ and discards. Defaults to nil.
+ * `:fail-fast`: a boolean value to raise an error when encountering invalid
+ syntax. Defaults to t.
+
+ Examples:
+
+ ```emacs-lisp
+ (parseclj-parse-clojure) ;; will parse clojure code in the current buffer
and return an AST
+ (parseclj-parse-clojure "(1 2 3)") ;; => ((:node-type . :root) ... )
+ (parseclj-parse-clojure :lexical-preservation t) ;; will parse clojure code
in current buffer preserving whitespaces, comments and discards
+ ```
+
+ > Note: there's an open issue to extend this API to [parse clojure code
within
+ > some boundaries of a
+ > buffer](https://github.com/clojure-emacs/parseclj/issues/13). Pull
requests
+ > are welcome.
+
+- `parseclj-unparse-clojure` ast
+
+ Transform the given AST into Clojure source code and inserts it into the
+ current buffer.
+
+- `parseclj-unparse-clojure-to-string` ast
+
+ Transfrom the given AST into Clojure source code and returns it as a
string.
+
+### parseedn
+
+- `parseedn-read`
+
+ Read content from the current buffer as EDN and transforms it into an Emacs
+ Lisp value.
+
+- `parseedn-read-str` str
+
+ Read STR as EDN and transfroms it into an Emacs Lisp value.
+
+- `parseedn-print` datum
+
+ Inserts DATUM as EDN Into the current buffer. DATUM can be any Emacs Lisp
+ value.
+
+- `parseedn-print-str` datum
+
+ Returns a string containing DATUM as EDN. DATUM can be any Emacs Lisp
+ value.
## License
© 2017-2018 Arne Brasseur
-Distributed under the terms of the GNU General Public License 3.0 or later.
See LICENSE.
+Distributed under the terms of the GNU General Public License 3.0 or later. See
+[LICENSE](LICENSE).
diff --git a/parseclj.el b/parseclj.el
index b12695af26..b56b629240 100644
--- a/parseclj.el
+++ b/parseclj.el
@@ -44,8 +44,8 @@ key-value pairs to specify parsing options.
- `:lexical-preservation' Retain whitespace, comments, and
discards. Defaults to nil.
-- `:fail-fast' Raise an error
- when encountering invalid syntax. Defaults to t."
+- `:fail-fast' Raise an error when encountering invalid syntax.
+ Defaults to t."
(if (stringp (car string-and-options))
(with-temp-buffer
(insert (car string-and-options))
- [nongnu] elpa/parseclj 5fbe901cba 071/185: Parse/unparse :tag, rountrip AST, (continued)
- [nongnu] elpa/parseclj 5fbe901cba 071/185: Parse/unparse :tag, rountrip AST, ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj 6e0dc9516c 093/185: Add missing require, ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj b79b3a5438 098/185: Add documentation to `parseclj-ast.el`, ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj 1b071d7775 104/185: Add documentation to `parseedn` module, ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj e1cb9e5514 113/185: Add a few more node accessors., ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj 80e92cdf9f 001/185: Move into its own repo, ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj 2588470302 116/185: Merge pull request #9 from lambdaisland/docstrings-and-conventions, ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj 92396d11cf 127/185: Merge pull request #17 from lambdaisland/travis-evm, ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj f87278a70e 135/185: Merge pull request #18 from clojure-emacs/doc-&-style-fixes-part-2, ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj eedc0d812e 168/185: Update docstring and metion Emacs 27 alternative, ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj 815ba87a77 137/185: Merge pull request #19 from clojure-emacs/update-readme,
ELPA Syncer <=
- [nongnu] elpa/parseclj 9e0b51e39c 160/185: revert tabs to spaces, address minor review comments, ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj bdd6489128 003/185: add travis badge, ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj f6b8ad665c 004/185: Fix .travis.yml, ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj 3ec632ed66 008/185: Travis show Emacs version, ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj 7cf7dc99cd 011/185: Travis: only install the necessary ppa/package for each matrix line, ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj 710511ff79 013/185: Seems these packages dont actually package the versioned executable names, ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj b2e97ecb57 017/185: Lets try that again #travis, ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj d7adaa5177 018/185: Lets try that again #travis, ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj abe7edb04b 019/185: Bunch of refactoring, but we're green now, supposedly, ELPA Syncer, 2021/12/28
- [nongnu] elpa/parseclj 56bb020a9e 020/185: Fix the travis yaml?, ELPA Syncer, 2021/12/28