Skip to content
Newer
Older
100644 205 lines (156 sloc) 6.63 KB
ddc9005 @roman Fixing wrong URL on travis LOGO
roman authored Feb 7, 2012
1 # zetta-parser [![Build Status](https://secure.travis-ci.org/van-clj/zetta-parser.png)](http://travis-ci.org/van-clj/zetta-parser)
d70dd5b @roman First commit of the zetta-parse
roman authored Jan 2, 2012
2
3c04fa6 @roman Adding a README and examples to the project
roman authored Feb 6, 2012
3 zetta-parser provides an easy to use Parser combinator library that allows
4 you to parse strings easily by composing simple parsers together to create
5 more powerful ones.
d70dd5b @roman First commit of the zetta-parse
roman authored Jan 2, 2012
6
93f2c00 @roman Updating the formatting of the README
roman authored Feb 6, 2012
7 Basic parsers can be found in `zetta.parser.seq`, this parsers will work
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
8 with mostly any type of items you find on a stream, some others such
9 as `string` and `number` expect to process a stream of characters.
10
19347db @roman Adding the installation instructions to README
roman authored Feb 15, 2012
11 ## Install
12
0280f97 @roman Updating the README
roman authored Feb 28, 2012
13 ```clojure
2bd3d10 @roman Update README with bwo/monads notation
roman authored Mar 27, 2015
14 [org.van-clj/zetta-parser "0.1.0"]
0280f97 @roman Updating the README
roman authored Feb 29, 2012
15 ```
19347db @roman Adding the installation instructions to README
roman authored Feb 15, 2012
16
d70dd5b @roman First commit of the zetta-parse
roman authored Jan 2, 2012
17 ## Usage
18
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
19 zetta-parser provides several namespaces, each with an specific functionality:
20
93f2c00 @roman Updating the formatting of the README
roman authored Feb 6, 2012
21 * `zetta.core`
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
22 Holds the basic functions to start using a zetta-parser, such
23 as the parser runners, a monadic implementation for parsers, etc.
24
93f2c00 @roman Updating the formatting of the README
roman authored Feb 6, 2012
25 * `zetta.parser.seq`
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
26 Holds the most basic parsers you may find, you can use this parsers
27 out of the box to create more complex ones using the `zetta.combinators`
28 namespace.
29
93f2c00 @roman Updating the formatting of the README
roman authored Feb 6, 2012
30 * `zetta.parse.string`
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
31 Implements some of the `zetta.parser.seq` namespace parsers so that they
32 always return a string result rather than a seq
33
93f2c00 @roman Updating the formatting of the README
roman authored Feb 6, 2012
34 * `zetta.combinators`
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
35 Contains useful parsers transformers like many, sep-by, among others, this
36 functions will allow you to enhance the behavior of simple parsers to allow
37 them parse more complex inputs.
38
ccec20f @roman Formatting changes to the README
roman authored Feb 6, 2012
39 ### do-parse Notation
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
40
41 do-parse is a macro that will allow you to implement parsers using a monadic
303cee3 @roman :memo: Update small details in the README
roman authored Mar 27, 2015
42 notation like the one provided by [bwo monads
43 library](https://github.com/bwo/monads). This kinds of parsers are really handy
44 when the behavior of the parser changes as you parse through the input.
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
45
46 ```clojure
c756ec3 @roman Updating the README.md file with a better example
roman authored Feb 11, 2012
47 (ns example
2bd3d10 @roman Update README with bwo/monads notation
roman authored Mar 27, 2015
48 (:require
49 [zetta.core :refer :all]
50 [zetta.parser.seq :as pseq]
51 [zetta.parser.string :as pstr]
52 [zetta.combinators :as pc]))
c756ec3 @roman Updating the README.md file with a better example
roman authored Feb 12, 2012
53
2bd3d10 @roman Update README with bwo/monads notation
roman authored Mar 27, 2015
54 ;; sub parsers that are going to be used
55 (def parse-movie ...)
56 (def parse-patient ...)
57 (def parse-program ...)
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
58
59 (def parse-professional
60 (do-parser
2bd3d10 @roman Update README with bwo/monads notation
roman authored Mar 27, 2015
61 pseq/skip-spaces
62
63 name <- (pstr/take-till #(Character/isSpace %))
64 ;; ^ assigns name to a string up until a space
65
66 pseq/skip-spaces
67
68 profession <- (pstr/take-till #(Character/isSpace %))
69 ;; ^ assigns profession to a string up until a space
70
71 ;; check for profession to change parse strategies
72 ;; dynamically
73 (cond
74 (= profession "actor")
75 (do-parser
76 movies <- (pc/sep-by1 parse-movie (pseq/char \,))
77 ;; ^ parse many movies separated by commas, using
78 ;; the parser of a single movie
79 (always (Actor. name movies)))
80
81 (= profession "doctor")
82 (do-parser
83 patients <- (pc/sep-by1 parse-patient (pseq/char \,))
84 ;; ^ parse many patients separated by commas, using
85 ;; the parser of a single patient
86 (always (Doctor. name patients)))
87
88 (= profession "programmer")
89 (do-parser
90 programs <- (pc/sep-by1 parse-program (pseq/char \,))
91 ;; ^ parse many programs separated by commas, using
92 ;; the parser of a single program
93 (always (Programmer. name programs)))
94
95 :else
96 (fail-parser (str "Invalid profession: " profession))
97 ;; ^ fail parser if an invalid profession is given
98 )))
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
99 ```
93f2c00 @roman Updating the formatting of the README
roman authored Feb 6, 2012
100
7859445 @roman Update the README and examples
roman authored Feb 12, 2012
101 ### Applicative Functors
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
102
103 Most of the times however, the behavior of your parser won't change
104 depending on the input you are parsing, this is when the `with-parser` macro
105 and the applicative functors macros come handy; zetta-parser provides
106 high order macros to go through the input and return the types you want.
107
7859445 @roman Update the README and examples
roman authored Feb 12, 2012
108 The `<$>` function will receive a normal function as it's first parameter,
8f54ad2 @roman Fixing some typos in the README
roman authored Feb 6, 2012
109 the rest of the parameters are going to be a parsers, at the end the result
110 of each parser is going to be an input parameter for the function that was
7859445 @roman Update the README and examples
roman authored Feb 12, 2012
111 specified in the first parameter of the function.
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
112
113 The `*>` macro will receive multiple parsers, is going to execute each of
114 them, and is going to return the value of the last parser to the right, there
115 is also the `<*` macro that will do the same thing, but will return the value
116 of first parser to the left.
117
118 Example:
119
120 ```clojure
121 (def parse-programmer
7859445 @roman Update the README and examples
roman authored Feb 12, 2012
122 (<$> #(Programmer. %1 %2)
123 ; ^ A function that is going to receive two parameters, two
124 ; parsers should follow this parameter.
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
125
7859445 @roman Update the README and examples
roman authored Feb 12, 2012
126 (*> spaces (many-till space)) ; this is %1
127 ; ^ this parser will parse spaces, ignore them and return the result
128 ; of the (many-till space) parser, this will be the %1 on the
129 ; function given on the first parameter.
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
130
7859445 @roman Update the README and examples
roman authored Feb 12, 2012
131 (*> spaces (many-till space))))
132 ; ^ this will do the same as the parser given in the second parameter
133 ; of <$>, the return value of this will be %2 on the the function
134 ; given on the first parameter.
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
135
136 ```
137
93f2c00 @roman Updating the formatting of the README
roman authored Feb 6, 2012
138 ### parse & parse-once
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
139
140 Most of the parser libraries out there will parse as long as you have all
9b4f407 @roman Adding link to the clojure/algo.monads lib in the README
roman authored Feb 6, 2012
141 the input you want to parse _at once_, this is really limiting given that
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
142 sometimes all the input to parse is not available (input streaming from
9b4f407 @roman Adding link to the clojure/algo.monads lib in the README
roman authored Feb 6, 2012
143 a connection and such).
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
144
9b4f407 @roman Adding link to the clojure/algo.monads lib in the README
roman authored Feb 6, 2012
145 zetta-parser provides the `parse` function which will parse the given input
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
146 using a given parser, if there is not enough input to either fail or return
147 a result, the parse function will return a continuation function that will
9b4f407 @roman Adding link to the clojure/algo.monads lib in the README
roman authored Feb 6, 2012
148 receive the remaining of the input when available, if this continuation
149 function receives a string, this function will either return a parsed result,
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
150 a failure or another function continuation. In case you have a continuation
9b4f407 @roman Adding link to the clojure/algo.monads lib in the README
roman authored Feb 6, 2012
151 and you pass an empty string to it, the parser will stop and will return either
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
152 a failure or a successful parsed result.
3c04fa6 @roman Adding a README and examples to the project
roman authored Feb 6, 2012
153
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
154 The `parse-once` function will behave like the parse function of any of the
155 other parser libraries.
3c04fa6 @roman Adding a README and examples to the project
roman authored Feb 6, 2012
156
0280f97 @roman Updating the README
roman authored Feb 29, 2012
157 ## I want more info!
158
768b3f3 @roman Bumping to version 0.0.3
roman authored Feb 28, 2012
159 For more info, please clone the project and execute `lein marg` to get a great
0280f97 @roman Updating the README
roman authored Feb 29, 2012
160 summary of the `zetta.parser.seq` and `zetta.combinators` namespaces.
161
7bb6714 @roman Updating the README with more info
roman authored Feb 6, 2012
162 ## Full Examples
3c04fa6 @roman Adding a README and examples to the project
roman authored Feb 6, 2012
163
164 ### Parsing a CSV file
165
166 ```clojure
2bd3d10 @roman Update README with bwo/monads notation
roman authored Mar 27, 2015
167 (ns zetta.examples.csv
168 ^{ :doc "Naive CSV parser" }
169 (:refer-clojure :exclude [char])
170 (:require [clojure.core :as core]
171 [clojure.string :as str]
172 [clojure.java.io :as io]
173 [zetta.core :refer :all]
174 [zetta.combinators
175 :refer [sep-by1 around many many1 choice]]
176 [zetta.parser.seq
177 :refer [char not-char spaces eol end-of-input]]))
178
179 (defrecord CSVFile [titles values])
180
181 (def csv-sep
182 (char \,))
183
184 (def csv-key
185 (<$> str/join
186 (many1
187 (around spaces (not-char #{\, \newline})))))
188
189 (def csv-entry
190 (<* (sep-by1 csv-key
191 csv-sep)
192 (<|> eol end-of-input)))
3c04fa6 @roman Adding a README and examples to the project
roman authored Feb 6, 2012
193
194 (def csv-file
7859445 @roman Update the README and examples
roman authored Feb 12, 2012
195 (<$> #(CSVFile. %1 %2)
2bd3d10 @roman Update README with bwo/monads notation
roman authored Mar 27, 2015
196 csv-entry
197 (many csv-entry)))
3c04fa6 @roman Adding a README and examples to the project
roman authored Feb 6, 2012
198 ```
d70dd5b @roman First commit of the zetta-parse
roman authored Jan 2, 2012
199
200 ## License
201
2bd3d10 @roman Update README with bwo/monads notation
roman authored Mar 27, 2015
202 Copyright (C) 2012-2015 Roman Gonzalez and contributors.
d70dd5b @roman First commit of the zetta-parse
roman authored Jan 2, 2012
203
204 Distributed under the Eclipse Public License, the same as Clojure.
Something went wrong with that request. Please try again.