Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 172 lines (128 sloc) 7.015 kb
0e4bf89 Jean-Philippe Paradis Initial commit.
authored
1 Project's home: http://www.hexstreamsoft.com/projects/parse-number-range/
2
3
5c7399d Jean-Philippe Paradis I guess that's a good enough README...
authored
4 parse-number-range parses LOOP's convenient "for-as-arithmetic" syntax
5 into 5 simple values: from, to, limit-kind (:inclusive, :exclusive or
6 nil if unbounded), by (step) and direction (+ or -)). Further related
7 utilities are provided. Intended for easy implementation of analogous
8 functionality in other constructs.
9
10 For a description of LOOP's "for-as-arithmetic", see:
11 http://www.lispworks.com/documentation/HyperSpec/Body/06_abaa.htm
12
13 Here's the package name, along with 2 nicknames:
14 - PARSE-NUMBER-RANGE
15 - PARSE-NUMRANGE
16 - PNUMRANGE
17
18 Explicit qualification of the exported symbols is recommended, and one
19 might (:import-from) select symbols, but (:use) is strongly discouraged.
20
21 Here are the exported symbols:
22 parse unparse canonicalize ; "parse" API
23 kind flags flags-to-keywords ; "info" API
24
25 Parse API
26 ---------
27
28 Here are the 5 "fundamental" values returned from PARSE and accepted by UNPARSE:
29
30 - FROM: The form introduced by :from, :upfrom or :downfrom. Defaults to 0;
31 - TO: The form introduced by :to, :upto, :downto, :below or :above. NIL means "unbounded";
32 - LIMIT-KIND: :inclusive or :exclusive if there's a limit, or NIL if unbounded;
33 - BY: The form introduced by :by;
34 - DIRECTION: + or -.
35
36 Some functions accept a KEYWORD-POLICY &key argument, which must be
37 either :strict or :loose. (from 1 to 10) would be valid with :loose
38 but not with :strict, which demands (:from 1 :to 10).
39
40 Use of :loose is strongly discouraged, as it's an unnecessary and evil
41 feature that typically results in arbitrary interning of symbols in
42 arbitrary packages.
43
44
45 Function PARSE range &key (keyword-policy :strict)
46 (extrasp nil)
47 (clause-kinds-p extrasp)
48 (clause-keywords-p extrasp)
49 (clauses-alist-p extrasp)
50 => from to limit-kind by direction
51 &key clause-kinds clause-keywords clauses-alist
52
53 By default, PARSE returns only the 5 "fundamental" values (see above):
54 - FROM: Defaults to 0;
55 - TO: Defaults to NIL;
56 - LIMIT-KIND: Defaults to NIL (unbounded);
57 - BY: Defaults to 1;
58 - DIRECTION: Defaults to +.
59
60 PARSE can compute and return 3 additional pieces of information, on request:
61 |-----------------|-------------------|----------------------------------------|
62 | return value | request-keyword | description |
63 |-----------------|-------------------|----------------------------------------|
64 |-----------------|-------------------|----------------------------------------|
65 | clause-kinds | clause-kinds-p | The clause kinds that were present, |
66 | | | in the order they appeared in. |
67 |-----------------|-------------------|----------------------------------------|
68 | clause-keywords | clause-keywords-p | The clause keywords that were present, |
69 | | | in the order they appeared in. |
70 |-----------------|-------------------|----------------------------------------|
71 | clauses-alist | clauses-alist-p | Alist: (clause-kind . clause-keyword) |
72 |-----------------|-------------------|----------------------------------------|
73
74
75 Function UNPARSE from to limit-kind by direction &key clause-kinds
76 => range
77
78 As you might have guessed, this does the reverse of PARSE...
79
80 UNPARSE uses FLAGS-TO-KEYWORDS internally and thus inherits its biases.
81
82 CLAUSE-KINDS should be a list of up to 3 elements being a permutation
83 of the clause-kinds :from, :to and :by. This determines the order that
84 the clauses will appear in, which might matter in the presence of
85 side-effects. NIL designates the default order, (:from :to :by).
86
87 If the list has 0 or 1 elements, then the default order is used, (:from :to :by).
88
89 If the list has 2 elements, then those clauses will appear in the
90 order specified but no order is specified between the other elements
91 and these ones and between the other elements among themselves.
92 (Yeah, a less simplistic implementation would allow simpler and more useful semantics.)
93
94 If the list has 3 elements, then the order is completely specified, explicitly.
95
96
97 Function CANONICALIZE range &key (clause-kinds :preserve) (keyword-policy :strict)
98
99 This simply feeds the results of PARSE into UNPARSE. If CLAUSE-KINDS
100 is :preserve, then :clause-kinds-p t will be specified for PARSE and
101 the resulting CLAUSE-KINDS result will be fed to UNPARSE. Else, the
102 provided CLAUSE-KINDS is fed directly to UNPARSE.
103
104
105 Info API
106 --------
107
108 Function KIND keyword &key (errorp t) (keyword-policy :strict)
109 => kind direction limit-kind
110 This function takes a LOOP keyword and returns the following information:
111
112 (I have to run away from plaintext for documentation. FAST.
113 I tried unicode box drawing characters but they wouldn't align.)
114
115 |-----------||--------------------------------|
116 | Argument || r e t u r n v a l u e s |
117 |-----------||--------------------------------|
118 | keyword || kind | direction | limit-kind |
119 |-----------||-------|-----------|------------|
120 |-----------||-------|-----------|------------|
121 | :from || :from | nil | nil |
122 |-----------||-------|-----------|------------|
123 | :downfrom || :from | - | nil |
124 |-----------||-------|-----------|------------|
125 | :upfrom || :from | + | nil |
126 |-----------||-------|-----------|------------|
127 |-----------||-------|-----------|------------|
128 | :to || :to | nil | :inclusive |
129 |-----------||-------|-----------|------------|
130 | :upto || :to | + | :inclusive |
131 |-----------||-------|-----------|------------|
132 | :downto || :to | - | :inclusive |
133 |-----------||-------|-----------|------------|
134 | :below || :to | + | :exclusive |
135 |-----------||-------|-----------|------------|
136 | :above || :to | - | :exclusive |
137 |-----------||-------|-----------|------------|
138 |-----------||-------|-----------|------------|
139 | :by || :by | nil | nil |
140 |-----------||-------|-----------|------------|
141
142
143 Function FLAGS keyword &key (errorp t) (keyword-policy :strict)
144 => direction limit-kind
145
146 This convenience function simply forwards to KIND
147 and returns all values but the first.
148
149
150 Function FLAGS-TO-KEYWORDS direction limit-kind
151 => from-keyword to-keyword
152
153 This function does roughly the opposite of the KIND function. It
154 returns a FROM-KEYWORD and a TO-KEYWORD (nil if unbounded) that
155 properly indicate the supplied DIRECTION and LIMIT-KIND.
156
157 There are typically multiple valid sets of answers that could be
158 returned. This function is currently biased as follows, with no way to
159 request a different bias:
160
161 1. The DIRECTION and LIMIT-KIND will always be represented in the
162 TO-KEYWORD, and never in the FROM-KEYWORD, except for the following
163 exception:
164
165 (flags-to-keywords '- :exclusive) => :downfrom, nil
166
167 2. :to is always returned in preference to :upto.
0e4bf89 Jean-Philippe Paradis Initial commit.
authored
168
169
170 This library is in the Public Domain.
171 See the UNLICENSE file for details.
Something went wrong with that request. Please try again.