The clj-re Reference Manual

This is the clj-re Reference Manual, version 1.0.2, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sat Dec 03 21:01:27 2022 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 clj-re

Implements Clojure-styled regexp operations such as ‘re-matches‘ and ‘re-find‘.

Author

Dave Tenny

License

MIT

Version

1.0.2

Dependencies
  • cl-ppcre (system).
  • named-readtables (system).
Source

clj-re.asd.

Child Components

3 Files

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


3.1 Lisp


3.1.1 clj-re/clj-re.asd

Source

clj-re.asd.

Parent Component

clj-re (system).

ASDF Systems

clj-re.

Packages

clj-re-asd.


3.1.2 clj-re/package.lisp

Source

clj-re.asd.

Parent Component

clj-re (system).

Packages

clj-re.


3.1.3 clj-re/clj-re.lisp

Dependency

package.lisp (file).

Source

clj-re.asd.

Parent Component

clj-re (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 clj-re

Functions that implement Clojure style regexp operations.

Source

package.lisp.

Use List
  • cl-ppcre.
  • common-lisp.
Public Interface
Internals

4.2 clj-re-asd

Source

clj-re.asd.

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

5 Definitions

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


5.1 Public Interface


5.1.1 Ordinary functions

Function: re-find (matcher-or-regexp &optional string)

Attempts to find the next subsequence of the input sequence that matches the pattern, as per java.util.regex.Matcher.find(). Uses re-groups to return the groups.

Returns:
* If there no match, nil.
* If there is a match, but no groups, returns the match. E.g.
(re-find "a*b" "ab") => "ab"
* If there is a match groups are involved, returns a list whose car is the full match, an whose remaining elements are the matched groups.

Call as ‘(re-find matcher)‘ or ‘(re-find regexp string)‘.

In the case where the first argument is not a matcher,
regexp may be a pattern or a string expression of a pattern.

Note that repeated calls to a matcher act like an iterator, while repeated calls with regexp and string arguments do not.

Package

clj-re.

Source

clj-re.lisp.

Function: re-groups (matcher)

Returns the groups from the most recent call to ‘re-find‘ or ‘re-matches‘. If there are no nested groups, returns a string of the entire match. If there are
nested groups, returns a list of the groups, the first element
being the entire match. Returns nil if there is no match indicated.

Package

clj-re.

Source

clj-re.lisp.

Function: re-matcher (regexp string)

Returns a matcher for use in operations such as ‘re-groups‘ or ‘re-find‘.

Regexp may be a pattern, or a string expression of a pattern.

Package

clj-re.

Source

clj-re.lisp.

Function: re-matches (regexp string)

Attempts to match the _entire region_ of string against the regexp as per java.util.regex.Matcher.matches(). Uses re-groups to return the groups. Returns nil if the pattern doesn’t match the entire string.

Regexp may be a pattern, or a string expressing a pattern.

Package

clj-re.

Source

clj-re.lisp.

Function: re-pattern (s)

In Clojure: Returns an instance of java.util.regex.Pattern, for use, e.g. in re-matcher. In Common Lisp: returns a compiled pattern (cl-ppcre scanner).
Note that clojure (and this module) allow ’s’ to be a pattern as well as a string expressing a pattern.

Package

clj-re.

Source

clj-re.lisp.

Function: re-quote-replacement (replacement-string)

In clojure this would be ‘clojure.string/re-quote-replacement‘.

Given a replacement string that you wish to be a literal
replacement for a pattern match in ‘re-replace‘ or ‘re-replace-first‘, do the necessary escaping of special characters in the replacement.

Package

clj-re.

Source

clj-re.lisp.

Function: re-replace (string match replacement)

In clojure this would be ‘clojure.string/replace‘.

Replaces all instances of ’match’ with ’replacement’ in ’string’.
If there are no matches, the input ’string’ value is returned.

Note that if you want more power, use ‘cl-ppcre:regex-replace[-all]‘ instead, but that it has different replacement directives which are disabled for clojure compatability.

‘match‘ / ‘replacement‘ can be:

string / string
char / char
pattern / (string or function of match).

See also ‘re-replace-first‘.

If replacement is a function it should take one argument (the match to be replaced) and return the replacement value. Note that the argument could be a list if the pattern contains capturing groups (as per ‘re-groups‘), i.e. ‘(match, register1, register2, ...)‘.

The ‘replacement‘ is literal (i.e. none of its characters are treated
specially) for all cases above except pattern / string.
NOTE: This behavior is different from most regexp functions in this package that interpret strings as patterns. A string as the ’match’ argument is treated literally and not as an expression of a pattern. This is for conformance with clojure’s behavior.

For pattern / string, $1, $2, etc. in the replacement string are
substituted with the string that matched the corresponding
parenthesized group in the pattern. If you wish your replacement
string ’r’ to be used literally, use ‘(re-quote-replacement r)‘ as the
replacement argument.

Example:
‘(/re-replace "Almost Pig Latin" "\b(\w)(\w+)\b" "$2$1ay")
-> "lmostAay igPay atinLay"

Package

clj-re.

Source

clj-re.lisp.

Function: re-replace-first (string match replacement)

In clojure this would be ‘clojure.string/replace-first‘.

Replaces the _first_ instance of ’match’ with ’replacement’ in ’string’. See ‘re-replace‘ for argument syntax and semantics.

Package

clj-re.

Source

clj-re.lisp.

Function: re-seq (regexp string)

Returns a list of successive matches of regexp in string as by using java.util.regex.Matcher.find(), each such match processed with re-groups.

Regexp may be a pattern or string expression of a pattern.

Note that the clojure version would return a lazy sequence, but we don’t have those and so the result is not lazy.

Package

clj-re.

Source

clj-re.lisp.

Function: re-split (string regexp &optional limit)

In clojure this would be clojure.string/split.

Splits string on a regular expression, which may be a pattern or a string
expression of a pattern. Optional argument limit is the maximum number of
splits. Returns list of the splits.

Resulting strings do not share structure with the input.

Note that capture groups (cl-ppcre registers) have no effect on the operation except perhaps to make it perform more slowly

Package

clj-re.

Source

clj-re.lisp.


5.2 Internals


5.2.1 Ordinary functions

Function: clojure-replacement-translation (replacement-string)

Translate clojure-style replacement operations, e.g. $1, into cl-ppcre replacement operations e.g. \1. Do NOT do the translations if the replacement string has ben quoted by the user via re-quote-replacement. Presently assumes repalcement-string has NOT been quoted with cl-ppcre:quote-meta-chars, but more selectively quoted just to ’literalize’ cl-ppcre replacement directives like N.

Package

clj-re.

Source

clj-re.lisp.

Function: copy-matcher (instance)
Package

clj-re.

Source

clj-re.lisp.

Function: make-matcher (&key scanner string done? match-start match-end reg-starts reg-ends)
Package

clj-re.

Source

clj-re.lisp.

Reader: matcher-done? (instance)
Writer: (setf matcher-done?) (instance)
Package

clj-re.

Source

clj-re.lisp.

Target Slot

done?.

Reader: matcher-match-end (instance)
Writer: (setf matcher-match-end) (instance)
Package

clj-re.

Source

clj-re.lisp.

Target Slot

match-end.

Reader: matcher-match-start (instance)
Writer: (setf matcher-match-start) (instance)
Package

clj-re.

Source

clj-re.lisp.

Target Slot

match-start.

Function: matcher-p (object)
Package

clj-re.

Source

clj-re.lisp.

Reader: matcher-reg-ends (instance)
Writer: (setf matcher-reg-ends) (instance)
Package

clj-re.

Source

clj-re.lisp.

Target Slot

reg-ends.

Reader: matcher-reg-starts (instance)
Writer: (setf matcher-reg-starts) (instance)
Package

clj-re.

Source

clj-re.lisp.

Target Slot

reg-starts.

Reader: matcher-scanner (instance)
Writer: (setf matcher-scanner) (instance)
Package

clj-re.

Source

clj-re.lisp.

Target Slot

scanner.

Reader: matcher-string (instance)
Writer: (setf matcher-string) (instance)
Package

clj-re.

Source

clj-re.lisp.

Target Slot

string.

Function: next (matcher)

Find the next match, return nil if there aren’t any T if there are, in which case the matcher values are updated.

Package

clj-re.

Source

clj-re.lisp.

Function: ppcre-replacement-quoter (replacement)

Given a string which may contain replacement directives for cl-pprcre:replace[-all] quote them, since they have no meaning under clojure replacement syntax and/or semantics. The directives we’re looking for are: N or {N} (for some digit), &, ‘, ’

Package

clj-re.

Source

clj-re.lisp.

Function: re-replace-aux (string match replacement replace-fn)

Does the work of re-replace and re-replace-first.
The logic is identical between the two except for which cl-ppcre function is called, as specified by the last argument.

Package

clj-re.

Source

clj-re.lisp.

Function: regex-literal-reader (stream char &optional numarg)

Reads a string as a regex literal and returns a compiled pattern.

E.g. Instead of "\\d+" you can specify #"\d+", with the added benefit
of a returned ’compiled’ regular expression in the form of a cl-ppcre scanner.

The main difference with respect to string char interpretation is that
the backslash is always read into the resulting string, whereas lisp would discard the first such backslash, allowing backslashes into the result only if double-backslash were found.

Like the lisp string reader, the character following the backslash
is effectively escaped, and will always be a part of the string. So you can use backslash-quote to escape a quote that would otherwise teriminate the string.

Package

clj-re.

Source

clj-re.lisp.


5.2.2 Structures

Structure: matcher

Emulate java Matcher binding to a string to be scanned.

Package

clj-re.

Source

clj-re.lisp.

Direct superclasses

structure-object.

Direct slots
Slot: scanner
Readers

matcher-scanner.

Writers

(setf matcher-scanner).

Slot: string
Package

common-lisp.

Type

string

Initform

""

Readers

matcher-string.

Writers

(setf matcher-string).

Slot: done?
Readers

matcher-done?.

Writers

(setf matcher-done?).

Slot: match-start
Type

integer

Initform

0

Readers

matcher-match-start.

Writers

(setf matcher-match-start).

Slot: match-end
Type

integer

Initform

0

Readers

matcher-match-end.

Writers

(setf matcher-match-end).

Slot: reg-starts
Type

(array (or null integer))

Initform

#()

Readers

matcher-reg-starts.

Writers

(setf matcher-reg-starts).

Slot: reg-ends
Type

(array (or null integer))

Initform

#()

Readers

matcher-reg-ends.

Writers

(setf matcher-reg-ends).


5.2.3 Types

Type: pattern ()

Alias for a compiled regexp emulating a java Pattern, in our case a cl-ppcre ’scanner’.

Package

clj-re.

Source

clj-re.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
C   F   M   N   P   R  
Index Entry  Section

(
(setf matcher-done?): Private ordinary functions
(setf matcher-match-end): Private ordinary functions
(setf matcher-match-start): Private ordinary functions
(setf matcher-reg-ends): Private ordinary functions
(setf matcher-reg-starts): Private ordinary functions
(setf matcher-scanner): Private ordinary functions
(setf matcher-string): Private ordinary functions

C
clojure-replacement-translation: Private ordinary functions
copy-matcher: Private ordinary functions

F
Function, (setf matcher-done?): Private ordinary functions
Function, (setf matcher-match-end): Private ordinary functions
Function, (setf matcher-match-start): Private ordinary functions
Function, (setf matcher-reg-ends): Private ordinary functions
Function, (setf matcher-reg-starts): Private ordinary functions
Function, (setf matcher-scanner): Private ordinary functions
Function, (setf matcher-string): Private ordinary functions
Function, clojure-replacement-translation: Private ordinary functions
Function, copy-matcher: Private ordinary functions
Function, make-matcher: Private ordinary functions
Function, matcher-done?: Private ordinary functions
Function, matcher-match-end: Private ordinary functions
Function, matcher-match-start: Private ordinary functions
Function, matcher-p: Private ordinary functions
Function, matcher-reg-ends: Private ordinary functions
Function, matcher-reg-starts: Private ordinary functions
Function, matcher-scanner: Private ordinary functions
Function, matcher-string: Private ordinary functions
Function, next: Private ordinary functions
Function, ppcre-replacement-quoter: Private ordinary functions
Function, re-find: Public ordinary functions
Function, re-groups: Public ordinary functions
Function, re-matcher: Public ordinary functions
Function, re-matches: Public ordinary functions
Function, re-pattern: Public ordinary functions
Function, re-quote-replacement: Public ordinary functions
Function, re-replace: Public ordinary functions
Function, re-replace-aux: Private ordinary functions
Function, re-replace-first: Public ordinary functions
Function, re-seq: Public ordinary functions
Function, re-split: Public ordinary functions
Function, regex-literal-reader: Private ordinary functions

M
make-matcher: Private ordinary functions
matcher-done?: Private ordinary functions
matcher-match-end: Private ordinary functions
matcher-match-start: Private ordinary functions
matcher-p: Private ordinary functions
matcher-reg-ends: Private ordinary functions
matcher-reg-starts: Private ordinary functions
matcher-scanner: Private ordinary functions
matcher-string: Private ordinary functions

N
next: Private ordinary functions

P
ppcre-replacement-quoter: Private ordinary functions

R
re-find: Public ordinary functions
re-groups: Public ordinary functions
re-matcher: Public ordinary functions
re-matches: Public ordinary functions
re-pattern: Public ordinary functions
re-quote-replacement: Public ordinary functions
re-replace: Public ordinary functions
re-replace-aux: Private ordinary functions
re-replace-first: Public ordinary functions
re-seq: Public ordinary functions
re-split: Public ordinary functions
regex-literal-reader: Private ordinary functions