The proc-parse Reference Manual

This is the proc-parse Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sat Dec 03 22:56:34 2022 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 proc-parse

Procedural vector parser

Author

Eitaro Fukamachi

License

BSD 2-Clause

Long Description

# Proc-Parse

[![Build Status](https://travis-ci.org/fukamachi/proc-parse.svg?branch=master)](https://travis-ci.org/fukamachi/proc-parse)
[![Coverage Status](https://coveralls.io/repos/fukamachi/proc-parse/badge.svg?branch=master)](https://coveralls.io/r/fukamachi/proc-parse)

<blockquote>
Question: Are these parser macros for speed or just to make your application look cool?<br>
Answer: Both.
</blockquote>

This is a string/octets parser library for Common Lisp with speed and readability in mind. Unlike other libraries, the code is not a pattern-matching-like, but a char-by-char procedural parser.

Although the design is good for speed, the code could look ugly with ‘tagbody‘ and ‘go‘. Proc-Parse wraps the code with sexy macros.

I believe we don’t have to give up speed for the readability while we use Common Lisp.

## Usage

“‘common-lisp
(defun parse-url-scheme (data &key (start 0) end)
"Return a URL scheme of DATA as a string."
(declare (optimize (speed 3) (safety 0) (debug 0)))
(block nil
(with-vector-parsing (data :start start :end end)
(match-i-case
("http:" (return "http"))
("https:" (return "https"))
(otherwise (unless (standard-alpha-char-p (current))
(return nil))
(bind (scheme (skip* (not #\:)))
(return scheme)))))))
“‘

## API

### with-vector-parsing

- can parse both string and octets.

“‘Lisp
(with-vector-parsing ("It’s Tuesday!" :start 5 :end 12)
(bind (str (skip-until
(lambda (c)
(declare (ignore c))
(eofp))))
(print str))) ; "Tuesday"

(with-vector-parsing ((babel:string-to-octets "It’s Tuesday!") :start 5 :end 12)
(bind (str (skip-until
(lambda (c)
(declare (ignore c))
(eofp))))
(print str))) ; "Tuesday"
“‘

### with-string-parsing

- can parse string.

“‘Lisp
(with-string-parsing ("It’s Tuesday!" :start 5 :end 12)
(bind (str (skip-until
(lambda (c)
(declare (ignore c))
(eofp))))
(print str))) ; "Tuesday"
“‘

### with-octets-parsing

- can parse octets.

“‘Lisp
(with-octets-parsing ((babel:string-to-octets "It’s Tuesday!") :start 5 :end 12)
(bind (str (skip-until
(lambda (c)
(declare (ignore c))
(eofp))))
(print str))) ; "Tuesday"
“‘

### eofp

- can return EOF or not.

“‘Lisp
(with-vector-parsing ("hello")
(print (eofp)) ; NIL
(match "hello")
(print (eofp))) ; T
“‘

### current

- can return the character of the current position.

“‘Lisp
(with-vector-parsing ("hello")
(print (current)) ; #\h
(skip #\h)
(print (current))) ; #\e
“‘

### peek

- can peek next character from the current position

“‘Lisp
(with-vector-parsing ("hello")
(print (current)) ; #\h
(print (peek)) ; #\e
(print (current))) ; #\h
“‘

- and you can specify the eof-value

“‘Lisp
(with-vector-parsing ("hello")
(match "hell")
(print (pos)) ; #\4
(print (peek :eof-value ’yes))) ; YES
“‘

### pos

- can return the current position.

“‘Lisp
(with-vector-parsing ("hello")
(print (pos)) ; 0
(skip #\h)
(print (pos))) ; 1
“‘

### advance

- can put the current postion forward.
- can cease parsing with EOF.

“‘Lisp
(with-vector-parsing ("hello")
(print (current)) ; #\h
(advance)
(print (current)) ; #\e
(match "ello")
(print (current)) ; #\o
(advance)
(print "Hi")) ; "Hi" won’t displayed.
“‘

### advance*

- can put the current postion forward.
- just returns NIL with EOF.

“‘Lisp
(with-vector-parsing ("hello")
(print (current)) ; #\h
(advance*)
(print (current)) ; #\e
(match "ello")
(print (current)) ; #\o
(advance*)
(print (current)) ; #\o
(print "Hi")) ; "Hi"
“‘

### skip

- can skip the specified character.
- can raise MATCH-FAILED error with unmatched characters.

“‘Lisp
(with-vector-parsing ("hello")
(print (current)) ; #\h
(skip #\h)
(print (current)) ; #\e
(skip (not #\h))
(print (current)) ; #\l
(skip #\f))
;; => Condition MATCH-FAILED was signalled.
“‘

### skip*

- can skip some straignt specified characters.
- just returns NIL with unmatched characters.

“‘Lisp
(with-vector-parsing ("hello")
(skip* #\h)
(print (current)) ; #\e
(skip* (not #\l))
(print (current)) ; #\l
(skip* #\l)
(print (current)) ; #\o
(skip* #\f)) ; MATCH-FAILED won’t be raised.
“‘

### skip+

- can skip some straignt specified characters.
- can raise MATCH-FAILED error with unmatched characters.

“‘Lisp
(with-vector-parsing ("hello")
(skip+ #\h)
(print (current)) ; #\e
(skip* (not #\l))
(print (current)) ; #\l
(skip+ #\l)
(print (current)) ; #\o
(skip+ #\f))
;; => Condition MATCH-FAILED was signalled.
“‘

### skip?

- can skip the specified character.
- just returns NIL with unmatched characters.

“‘Lisp
(with-vector-parsing ("hello")
(print (current)) ; #\h
(skip? #\h)
(print (current)) ; #\e
(skip? (not #\h))
(print (current)) ; #\l
(skip? #\f)) ; MATCH-FAILED won’t be raised.
“‘

### skip-until

- can skip until form returned T or parsing reached EOF.

“‘Lisp
(with-vector-parsing ("hello")
(skip-until (lambda (char) (char= char #\o)))
(print (current)) ; #\o
(print (eofp)) ; NIL
(skip-until (lambda (char) (char= char #\f)))
(print (eofp))) ; T
“‘

### skip-while

- can skip while form returns T and parsing doesn’t reach EOF.

“‘Lisp
(with-vector-parsing ("hello")
(skip-while (lambda (char) (char/= char #\o)))
(print (current)) ; #\o
(print (eofp)) ; NIL
(skip-while (lambda (char) (char/= char #\f)))
(print (eofp))) ; T
“‘

### bind

- can bind subseqed string.

“‘Lisp
(with-vector-parsing ("hello")
(bind (str1 (skip-until (lambda (c) (char= c #\l))))
(print str1)) ; "he"
(bind (str2 (skip* (not #\f)))
(print str2))) ; "llo"
“‘

### match

- can skip matched one of the specified strings.
- can raise MATCH-FAILED error with unmatched characters.

“‘Lisp
(with-vector-parsing ("hello")
(match "he")
(print (current)) ; #\l
(match "l" "ll")
(print (current)) ; #\o
(match "f"))
;; => Condition MATCH-FAILED was signalled.
“‘

### match-i

- can skip case-insensitively matched one of the specified strings.
- can raise MATCH-FAILED error with case-insensitively unmatched characters.

“‘Lisp
(with-vector-parsing ("hello")
(match-i "He")
(print (current)) ; #\l
(match-i "L" "LL")
(print (current)) ; #\o
(match-i "F"))
;; => Condition MATCH-FAILED was signalled.
“‘

### match?

- can skip matched one of the specified strings.
- just returns NIL with unmatched characters.

“‘Lisp
(with-vector-parsing ("hello")
(match? "he")
(print (current)) ; #\l
(match? "l" "ll")
(print (current)) ; #\o
(match? "f")) ; MATCH-FAILED won’t be raised.
“‘

### match-case

- can dispatch to the matched case.
- aborts parsing when reaching EOF.

“‘Lisp
(with-vector-parsing ("hello")
(match-case
("he" (print 0))
("ll" (print 1))
(otherwise (print 2))) ; 0
(print (current)) ; #\l
(match-case
("he" (print 0))
("ll" (print 1))
(otherwise (print 2))) ; 1
(print (current)) ; #\o
(match-case
("he" (print 0))
("ll" (print 1))
(otherwise (print 2))) ; 2
(print (current)) ; #\o
(match-case
("he" (print 0))
("ll" (print 1))))
;; => Condition MATCH-FAILED was signalled.

(with-vector-parsing ("hello")
(print
(match-case
("hello" 0))) ;; Nothing will be printed.
(print "It shold not be printed.")) ;; Nothing will be printed.
;; => NIL
“‘

### match-i-case

- can dispatch to the case-insensitively matched case.
- aborts parsing when reaching EOF.

“‘Lisp
(with-vector-parsing ("hello")
(match-i-case
("He" (print 0))
("LL" (print 1))
(otherwise (print 2))) ; 0
(print (current)) ; #\l
(match-i-case
("He" (print 0))
("LL" (print 1))
(otherwise (print 2))) ; 1
(print (current)) ; #\o
(match-i-case
("He" (print 0))
("LL" (print 1))
(otherwise (print 2))) ; 2
(print (current)) ; #\o
(match-i-case
("He" (print 0))
("LL" (print 1))))
;; => Condition MATCH-FAILED was signalled.

(with-vector-parsing ("hello")
(print
(match-i-case
("Hello" 0))) ;; Nothing will be printed.
(print "It shold not be printed.")) ;; Nothing will be printed.
;; => NIL
“‘

### match-failed

- is the condition representing failure of matching.

“‘Lisp
(with-vector-parsing ("hello")
(print (current)) ; #\h
(skip #\f))
;; => Condition MATCH-FAILED was signalled.
“‘

## Author

* Eitaro Fukamachi
* Rudolph Miller

## Copyright

Copyright (c) 2015 Eitaro Fukamachi & Rudolph Miller

## License

Licensed under the BSD 2-Clause License.

Version

0.1

Dependencies
  • alexandria (system).
  • babel (system).
  • sb-cltl2 (system).
Source

proc-parse.asd.

Child Component

src (module).


3 Modules

Modules are listed depth-first from the system components tree.


3.1 proc-parse/src

Source

proc-parse.asd.

Parent Component

proc-parse (system).

Child Component

proc-parse.lisp (file).


4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


4.1 Lisp


4.1.1 proc-parse/proc-parse.asd

Source

proc-parse.asd.

Parent Component

proc-parse (system).

ASDF Systems

proc-parse.

Packages

proc-parse-asd.


4.1.2 proc-parse/src/proc-parse.lisp

Source

proc-parse.asd.

Parent Component

src (module).

Packages

proc-parse.

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 proc-parse-asd

Source

proc-parse.asd.

Use List
  • asdf/interface.
  • common-lisp.

5.2 proc-parse

Source

proc-parse.lisp.

Use List

common-lisp.

Public Interface
Internals

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


6.1 Public Interface


6.1.1 Macros

Macro: bind ((symb &body bind-forms) &body body)
Package

proc-parse.

Source

proc-parse.lisp.

Macro: with-octets-parsing ((data &key start end) &body body)
Package

proc-parse.

Source

proc-parse.lisp.

Macro: with-string-parsing ((data &key start end) &body body)
Package

proc-parse.

Source

proc-parse.lisp.

Macro: with-vector-parsing ((data &key start end) &body body)
Package

proc-parse.

Source

proc-parse.lisp.


6.1.2 Conditions

Condition: match-failed
Package

proc-parse.

Source

proc-parse.lisp.

Direct superclasses

error.

Direct slots
Slot: elem
Initform

(quote nil)

Initargs

:elem

Slot: expected
Initform

(quote nil)

Initargs

:expected


6.2 Internals


6.2.1 Macros

Macro: get-elem (form)
Package

proc-parse.

Source

proc-parse.lisp.

Macro: parsing-macrolet ((elem data p end) (&rest macros) &body body)
Package

proc-parse.

Source

proc-parse.lisp.

Macro: subseq* (data start &optional end)
Package

proc-parse.

Source

proc-parse.lisp.

Macro: tagbody-with-match-failed (elem &body body)
Package

proc-parse.

Source

proc-parse.lisp.

Macro: vector-case (elem-var vec-and-options &body cases)
Package

proc-parse.

Source

proc-parse.lisp.


6.2.2 Ordinary functions

Function: check-match-cases (cases)
Package

proc-parse.

Source

proc-parse.lisp.

Function: check-skip-elems (elems)
Package

proc-parse.

Source

proc-parse.lisp.

Function: convert-case-conditions (var chars)
Package

proc-parse.

Source

proc-parse.lisp.

Function: ensure-char-elem (elem)
Package

proc-parse.

Source

proc-parse.lisp.

Function: typed-case-tagbodies (var &rest cases)
Package

proc-parse.

Source

proc-parse.lisp.

Function: variable-type (var &optional env)
Package

proc-parse.

Source

proc-parse.lisp.

Function: variable-type* (var &optional env)
Package

proc-parse.

Source

proc-parse.lisp.


6.2.3 Types

Type: octets (&optional len)
Package

proc-parse.

Source

proc-parse.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   B   C   E   F   G   M   P   S   T   V   W  
Index Entry  Section

B
bind: Public macros

C
check-match-cases: Private ordinary functions
check-skip-elems: Private ordinary functions
convert-case-conditions: Private ordinary functions

E
ensure-char-elem: Private ordinary functions

F
Function, check-match-cases: Private ordinary functions
Function, check-skip-elems: Private ordinary functions
Function, convert-case-conditions: Private ordinary functions
Function, ensure-char-elem: Private ordinary functions
Function, typed-case-tagbodies: Private ordinary functions
Function, variable-type: Private ordinary functions
Function, variable-type*: Private ordinary functions

G
get-elem: Private macros

M
Macro, bind: Public macros
Macro, get-elem: Private macros
Macro, parsing-macrolet: Private macros
Macro, subseq*: Private macros
Macro, tagbody-with-match-failed: Private macros
Macro, vector-case: Private macros
Macro, with-octets-parsing: Public macros
Macro, with-string-parsing: Public macros
Macro, with-vector-parsing: Public macros

P
parsing-macrolet: Private macros

S
subseq*: Private macros

T
tagbody-with-match-failed: Private macros
typed-case-tagbodies: Private ordinary functions

V
variable-type: Private ordinary functions
variable-type*: Private ordinary functions
vector-case: Private macros

W
with-octets-parsing: Public macros
with-string-parsing: Public macros
with-vector-parsing: Public macros


A.3 Variables

Jump to:   E   S  
Index Entry  Section

E
elem: Public conditions
expected: Public conditions

S
Slot, elem: Public conditions
Slot, expected: Public conditions