README.md (4344B)
1 [](https://travis-ci.org/clojure-emacs/parseclj) 2 3 # Clojure parser for Emacs Lisp 4 5 `parseclj` is an Emacs Lisp library for parsing Clojure code and [EDN 6 data](https://github.com/edn-format/edn). It supports several input and output 7 formats, all powered by the same shift-reduce parser function. 8 9 Take a look at the [design document](DESIGN.md) for more details. 10 11 `parseclj` is in **alpha** state right now, its API might be subject to change. 12 13 ## Installation 14 15 Available on the major `package.el` community maintained repos - 16 [MELPA Stable][] and [MELPA][] repos. 17 18 MELPA Stable is the recommended repo as it has the latest stable 19 version. MELPA has a development snapshot for users who don't mind 20 (infrequent) breakage but don't want to run from a git checkout. 21 22 You can install `parseclj` using the following command: 23 24 <kbd>M-x package-install [RET] parseclj [RET]</kbd> 25 26 or if you'd rather keep it in your dotfiles: 27 28 ```el 29 (unless (package-installed-p 'parseclj) 30 (package-install 'parseclj)) 31 ``` 32 33 If the installation doesn't work try refreshing the package list: 34 35 <kbd>M-x package-refresh-contents</kbd> 36 37 [melpa]: http://melpa.org 38 [melpa stable]: http://stable.melpa.org 39 40 ## Usage 41 42 `parseclj` contains function that return an 43 [AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree) that, for example, 44 given as input `(1 2 [:a :b :c])`, it looks like this: 45 46 ``` emacs-lisp 47 ((:node-type . :root) 48 (:position . 1) 49 (:children ((:node-type . :list) 50 (:position . 1) 51 (:children ((:node-type . :number) 52 (:position . 2) 53 (:form . "1") 54 (:value . 1)) 55 ((:node-type . :number) 56 (:position . 4) 57 (:form . "2") 58 (:value . 2)) 59 ((:node-type . :vector) 60 (:position . 6) 61 (:children ((:node-type . :keyword) 62 (:position . 7) 63 (:form . ":a") 64 (:value . :a)) 65 ((:node-type . :keyword) 66 (:position . 10) 67 (:form . ":b") 68 (:value . :b)) 69 ((:node-type . :keyword) 70 (:position . 13) 71 (:form . ":c") 72 (:value . :c)))))))) 73 ``` 74 75 In order to use any of these functions, you first need to require it: 76 77 ```emacs-lisp 78 (require 'parseclj) 79 ``` 80 81 And then you will have the following functions at your disposal: 82 83 - `parseclj-parse-clojure` &rest string-and-options 84 85 When no arguments, parses Clojure source code into an AST and returns it. 86 When given a string as a first argument, parses it and returns the 87 corresponding AST. 88 89 A list of options can be passed down to the parsing process, particularly: 90 * `:lexical-preservation`: a boolean value to retain whitespace, comments, 91 and discards. Defaults to nil. 92 * `:fail-fast`: a boolean value to raise an error when encountering invalid 93 syntax. Defaults to t. 94 95 Examples: 96 97 ```emacs-lisp 98 (parseclj-parse-clojure) ;; will parse clojure code in the current buffer and return an AST 99 (parseclj-parse-clojure "(1 2 3)") ;; => ((:node-type . :root) ... ) 100 (parseclj-parse-clojure :lexical-preservation t) ;; will parse clojure code in current buffer preserving whitespaces, comments and discards 101 ``` 102 103 > Note: there's an open issue to extend this API to [parse clojure code within 104 > some boundaries of a 105 > buffer](https://github.com/clojure-emacs/parseclj/issues/13). Pull requests 106 > are welcome. 107 108 - `parseclj-unparse-clojure` ast 109 110 Transform the given AST into Clojure source code and inserts it into the 111 current buffer. 112 113 - `parseclj-unparse-clojure-to-string` ast 114 115 Transfrom the given AST into Clojure source code and returns it as a string. 116 117 118 ## License 119 120 © 2017-2021 Arne Brasseur and contributors. 121 122 Distributed under the terms of the GNU General Public License 3.0 or later. See 123 [LICENSE](LICENSE).