source: project/wiki/eggref/5/abnf @ 37636

Last change on this file since 37636 was 36589, checked in by Ivan Raikov, 2 years ago

abnf doc

File size: 9.5 KB
Line 
1[[tags: egg]]
2[[toc:]]
3
4== abnf
5
6=== Description
7
8{{abnf}} is a collection of combinators to help constructing parsers
9for Augmented Backus-Naur form (ABNF) grammars
10([[http://www.ietf.org/rfc/rfc4234.txt|RFC 4234]]).
11
12=== Library Procedures
13
14The combinator procedures in this library are based on the interface
15provided by the [[lexgen]] library.
16
17==== Terminal values and core rules 
18
19<procedure>(char CHAR) => MATCHER</procedure>
20
21Procedure {{char}} builds a pattern matcher function that matches a
22single character.
23
24<procedure>(lit STRING) => MATCHER</procedure>
25
26{{lit}} matches a literal string (case-insensitive).
27
28
29The following primitive parsers match the rules described in RFC 4234, Section 6.1.
30
31<procedure>(alpha STREAM-LIST) => STREAM-LIST</procedure>
32
33Matches any character of the alphabet.
34
35<procedure>(binary STREAM-LIST) => STREAM-LIST</procedure>
36
37Matches [0..1].
38
39<procedure>(decimal STREAM-LIST) => STREAM-LIST</procedure>
40
41Matches [0..9].
42
43<procedure>(hexadecimal STREAM-LIST) => STREAM-LIST</procedure>
44
45Matches [0..9] and [A..F,a..f].
46
47<procedure>(ascii-char STREAM-LIST) => STREAM-LIST</procedure>
48
49Matches any 7-bit US-ASCII character except for NUL (ASCII value 0).
50
51<procedure>(cr STREAM-LIST) => STREAM-LIST</procedure>
52
53Matches the carriage return character.
54
55<procedure>(lf STREAM-LIST) => STREAM-LIST</procedure>
56
57Matches the line feed character.
58
59<procedure>(crlf STREAM-LIST) => STREAM-LIST</procedure>
60
61Matches the Internet newline.
62
63<procedure>(ctl STREAM-LIST) => STREAM-LIST</procedure>
64
65Matches any US-ASCII control character. That is, any character with a
66decimal value in the range of [0..31,127].
67
68<procedure>(dquote STREAM-LIST) => STREAM-LIST</procedure>
69
70Matches the double quote character.
71
72<procedure>(htab STREAM-LIST) => STREAM-LIST</procedure>
73
74Matches the tab character.
75
76<procedure>(lwsp STREAM-LIST) => STREAM-LIST</procedure>
77
78Matches linear white-space. That is, any number of consecutive
79{{wsp}}, optionally followed by a {{crlf}} and (at least) one more
80{{wsp}}.
81
82<procedure>(sp STREAM-LIST) => STREAM-LIST</procedure>
83
84Matches the space character.
85
86<procedure>(vspace STREAM-LIST) => STREAM-LIST</procedure>
87
88Matches any printable ASCII characterThat is, any character in the
89decimal range of [33..126].
90
91<procedure>(wsp STREAM-LIST) => STREAM-LIST</procedure>
92
93Matches space or tab.
94
95<procedure>(quoted-pair STREAM-LIST) => STREAM-LIST</procedure>
96
97Matches a quoted pair. Any characters (excluding CR and LF) may be
98quoted.
99
100<procedure>(quoted-string STREAM-LIST) => STREAM-LIST</procedure>
101
102Matches a quoted string. The slash and double quote characters must be
103escaped inside a quoted string; CR and LF are not allowed at all.
104
105The following additional procedures are provided for convenience:
106
107<procedure>(set CHAR-SET) => MATCHER</procedure>
108
109Matches any character from an SRFI-14 character set.
110
111<procedure>(set-from-string STRING) => MATCHER</procedure>
112
113Matches any character from a set defined as a string.
114
115
116==== Operators
117
118<procedure>(concatenation MATCHER-LIST) => MATCHER</procedure>
119
120{{concatenation}} matches an ordered list of rules. (RFC 4234, Section 3.1)
121
122
123<procedure>(alternatives MATCHER-LIST) => MATCHER</procedure>
124
125{{alternatives}} matches any one of the given list of rules. (RFC 4234, Section 3.2)
126
127
128<procedure>(range C1 C2) => MATCHER</procedure>
129
130{{range}} matches a range of characters. (RFC 4234, Section 3.4)
131
132<procedure>(variable-repetition MIN MAX MATCHER) => MATCHER</procedure>
133
134{{variable-repetition}} matches between {{MIN}} and {{MAX}} or more consecutive
135elements that match the given rule. (RFC 4234, Section 3.6)
136
137<procedure>(repetition MATCHER) => MATCHER</procedure>
138
139{{repetition}} matches zero or more consecutive elements that match the given rule.
140
141<procedure>(repetition1 MATCHER) => MATCHER</procedure>
142
143{{repetition1}} matches one or more consecutive elements that match the given rule.
144
145
146<procedure>(repetition-n N MATCHER) => MATCHER</procedure>
147
148{{repetition-n}} matches exactly {{N}} consecutive occurences of the given rule. (RFC 4234, Section 3.7)
149
150
151<procedure>(optional-sequence MATCHER) => MATCHER</procedure>
152
153{{optional-sequence}} matches the given optional rule. (RFC 4234, Section 3.8)
154
155<procedure>(pass) => MATCHER</procedure>
156
157This matcher returns without consuming any input.
158
159<procedure>(bind F P) => MATCHER</procedure>
160
161Given a rule {{P}} and function {{F}}, returns a matcher that first
162applies {{P}} to the input stream, then applies {{F}} to the returned
163list of consumed tokens, and returns the result and the remainder of
164the input stream.
165
166Note: this combinator will signal failure if the input stream is
167empty.
168
169<procedure>(bind* F P) => MATCHER</procedure>
170
171The same as {{bind}}, but will signal success if the input stream is
172empty.
173
174<procedure>(drop-consumed P) => MATCHER</procedure>
175
176Given a rule {{P}}, returns a matcher that always returns an empty
177list of consumed tokens when {{P}} succeeds.
178
179==== Abbreviated syntax
180
181{{abnf}} supports the following abbreviations for commonly used combinators:
182
183; {{::}} : {{concatenation}}
184; {{:?}} : {{optional-sequence}}
185; {{:!}} : {{drop-consumed}}
186; {{:s}} : {{lit}}
187; {{:c}} : {{char}}
188; {{:*}} : {{repetition}}
189; {{:+}} : {{repetition1}}
190
191
192=== Examples
193
194The following parser libraries have been implemented with {{abnf}}, in
195order of complexity:
196
197* [[csv]] 
198* [[internet-timestamp]] 
199* [[json-abnf]] 
200* [[mbox]]
201* [[smtp]] 
202* [[internet-message]] 
203* [[mime]] 
204
205==== Parsing date and time
206
207<enscript highlight="scheme">
208
209(import abnf)
210
211(define fws
212  (concatenation
213   (optional-sequence 
214    (concatenation
215     (repetition wsp)
216     (drop-consumed 
217      (alternatives crlf lf cr))))
218   (repetition1 wsp)))
219
220
221(define (between-fws p)
222  (concatenation
223   (drop-consumed (optional-sequence fws)) p
224   (drop-consumed (optional-sequence fws))))
225
226;; Date and Time Specification from RFC 5322 (Internet Message Format)
227
228;; The following abnf parser combinators parse a date and time
229;; specification of the form
230;;
231;;   Thu, 19 Dec 2002 20:35:46 +0200
232;;
233; where the weekday specification is optional.
234                             
235;; Match the abbreviated weekday names
236
237(define day-name 
238  (alternatives
239   (lit "Mon")
240   (lit "Tue")
241   (lit "Wed")
242   (lit "Thu")
243   (lit "Fri")
244   (lit "Sat")
245   (lit "Sun")))
246
247;; Match a day-name, optionally wrapped in folding whitespace
248
249(define day-of-week (between-fws day-name))
250
251
252;; Match a four digit decimal number
253
254(define year (between-fws (repetition-n 4 decimal)))
255
256;; Match the abbreviated month names
257
258(define month-name (alternatives
259                    (lit "Jan")
260                    (lit "Feb")
261                    (lit "Mar")
262                    (lit "Apr")
263                    (lit "May")
264                    (lit "Jun")
265                    (lit "Jul")
266                    (lit "Aug")
267                    (lit "Sep")
268                    (lit "Oct")
269                    (lit "Nov")
270                    (lit "Dec")))
271
272;; Match a month-name, optionally wrapped in folding whitespace
273
274(define month (between-fws month-name))
275
276
277;; Match a one or two digit number
278
279(define day (concatenation
280             (drop-consumed (optional-sequence fws))
281             (alternatives 
282              (variable-repetition 1 2 decimal)
283              (drop-consumed fws))))
284
285;; Match a date of the form dd:mm:yyyy
286(define date (concatenation day month year))
287
288;; Match a two-digit number
289
290(define hour      (repetition-n 2 decimal))
291(define minute    (repetition-n 2 decimal))
292(define isecond   (repetition-n 2 decimal))
293
294;; Match a time-of-day specification of hh:mm or hh:mm:ss.
295
296(define time-of-day (concatenation
297                     hour (drop-consumed (char #\:))
298                     minute (optional-sequence 
299                             (concatenation (drop-consumed (char #\:))
300                                         isecond))))
301
302;; Match a timezone specification of the form
303;; +hhmm or -hhmm
304
305(define zone (concatenation 
306              (drop-consumed fws)
307              (alternatives (char #\-) (char #\+))
308              hour minute))
309
310;; Match a time-of-day specification followed by a zone.
311
312(define itime (concatenation time-of-day zone))
313
314(define date-time (concatenation
315                   (optional-sequence
316                    (concatenation
317                     day-of-week
318                     (drop-consumed (char #\,))))
319                   date
320                   itime
321                   (drop-consumed (optional-sequence fws))))
322
323(define (err s)
324  (print "lexical error on stream: " s)
325  `(error))
326
327(import lexgen)
328(print (lex date-time err "Thu, 19 Dec 2002 20:35:46 +0200"))
329
330</enscript>
331
332
333=== Version History
334
335* 8.0 Ported to CHICKEN 5 and yasos collections interface 
336* 7.0 Added bind* variant of bind [thanks to Peter Bex]
337* 6.0 Using utf8 for char operations
338* 5.1 Improvements to the CharLex->CoreABNF constructor
339* 5.0 Synchronized with lexgen 5
340* 3.2 Removed invalid identifier :|
341* 3.0 Implemented typeclass interface
342* 2.9 Bug fix in consumed-objects (reported by Peter Bex)
343* 2.7 Added abbreviated syntax (suggested by Moritz Heidkamp)
344* 2.6 Bug fixes in consumer procedures
345* 2.5 Removed procedure memo
346* 2.4 Moved the definition of bind and drop to lexgen
347* 2.2 Added pass combinator
348* 2.1 Added procedure variable-repetition
349* 2.0 Updated to match the interface of lexgen 2.0
350* 1.3 Fix in drop
351* 1.2 Added procedures bind drop consume collect
352* 1.1 Added procedures set and set-from-string
353* 1.0 Initial release
354
355=== License
356
357
358  Copyright 2009-2018 Ivan Raikov
359
360
361  This program is free software: you can redistribute it and/or
362  modify it under the terms of the GNU General Public License as
363  published by the Free Software Foundation, either version 3 of the
364  License, or (at your option) any later version.
365
366  This program is distributed in the hope that it will be useful, but
367  WITHOUT ANY WARRANTY; without even the implied warranty of
368  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSESee the GNU
369  General Public License for more details.
370
371  A full copy of the GPL license can be found at
372  <http://www.gnu.org/licenses/>.
Note: See TracBrowser for help on using the repository browser.