source: project/wiki/eggref/5/srfi-105 @ 37969

Last change on this file since 37969 was 37969, checked in by dieggsy, 12 months ago

Create wiki page for srfi-105

File size: 7.4 KB
Line 
1[[tags: egg]]
2
3[[toc:]]
4
5== srfi-105
6
7Curly infix expressions. For more information, see
8[[http://srfi.schemers.org/srfi-105/srfi-105.html|SRFI-105]].
9
10=== Modules
11==== srfi-105
12
13The core srfi as specified in
14[[http://srfi.schemers.org/srfi-105/srfi-105.html|SRFI-105]]. Note that the
15srfi does not on its own handle mixed operators or square-bracket neoteric
16expressions.
17
18===== Notes
19====== Dot notation
20
21The special dot notation described in the original srfi is not supported,
22meaning the following examples do not work with this implemenation:
23
24* {{ {read(. options)} ⇒ (read . options) }}
25* {{ {a . z} ⇒ ($nfx$ a . z) }}
26
27This is because chicken reserves the {{.}} symbol for special use, and I didn't
28feel it would be consistent (or worth jumping through hoops) to support it
29inside curly braces.
30
31====== Neoteric expressions
32
33n-expressions (neoteric expressions) inside curly braces (e.g. {{f(x)}}) are
34implemented in a different way from the reference implementation's
35recommendation, but '''should be fully supported''', including arbitrary
36nesting ({{f(g(x))}}) and chaining ({{f(x)(y)}}). If any neoteric expression
37does not work correctly, this should be considered a bug.
38
39==== srfi-105.extra
40
41Adds support for mixed operators and square bracket neoteric expressions.
42Importing this implies {{(import srfi-105)}}, so one should not have to import
43both. {{$nfx$}} as specified in the original SRFI document is implemented as
44syntax in order to be able to handle syntax operators like {{and}}, {{or}}, and
45some of the aliases defined in this module.
46
47===== Usage
48
49Upon importing this module, curly infix expressions with mixed operators as
50well as neoteric calls of the form {{x[a]}} should just work. Certain operators
51are handled specially by default. See {{mixed-operator-precedence}} for more
52information.
53
54===== Notes
55====== Unary operators in mixed expressions
56
57"Loose" unary operators in mixed expressions are not supported. That is,
58something like {{ {#t and not #f} }} should result in an error. To use unary
59operators, use lisp syntax ({{ {#t and (not #f)} }}) or n-expressions {{ {#t
60and not(#f)} }}.
61
62====== Neoteric square bracket expressions
63
64Square bracket n-expressions such as {{a[x]}} are handled using SRFI-123's
65{{ref*}}. See [[https://wiki.call-cc.org/eggref/5/srfi-123|srfi-123]] for more
66information.
67
68===== Precedence
69
70<parameter>(mixed-operator-precedence)</parameter>
71
72Defines the order of operations, or operator precedence, for supported
73operations. This should be a list of lists of symbols, each specifying a
74precedence group, ordered from highest to lowest precedence. Symbols are
75grouped with left-associativity by default. Instead of a symbol, {{(#:right
76symbol)}} can be used instead, indicating that {{symbol}} is an operator with
77right associativity.
78
79If the first element of a group is the keyword {{#:comparison}}, the following
80members of that group should be treated as comparison operators that return a
81boolean, and are grouped as non-associative operators with {{and}}. For
82example, the group {{(#:comparison < >)}} implies that {{ {1 > 3 < 4} }} will
83be grouped as {{ (and (1 > 3) (3 > 4)) }}
84
85The special group {{(#:other)}} is a placeholder for any operators not present
86in (mixed-operator-precedence). These are grouped with left associativity. The
87parameter should contain at least this group, and is properly guarded as such.
88
89The default roughly matches
90[[https://docs.python.org/3/reference/expressions.html#operator-precedence|python's
91operator precedence]]:
92
93<enscript highlight=scheme>
94'(((right: expt) (right: **))
95  (* / modulo % quotient remainder
96     fx* fx/ fxmod fxrem
97     fp* fp/)
98  (+ - fx+ fx- fp+ fp-)
99  (arithmetic-shift << >> fxshl fxshr)
100  (bitwise-and & fxand)
101  (bitwise-xor ^ fxxor)
102  (bitwise-ior ior fxior)
103  (other:)
104  (comparison: < <= > >= =
105               fx< fx<= fx> fx>= fx=
106               fp< fp<= fp> fp>= fp=)
107  (and)
108  (or))
109</enscript>
110
111===== Aliases
112
113These are provided because of the way the core srfi (unmixed operators) works.
114By default, something like {{ {1 expt 3 expt 4} }} will not work. Since the
115srfi is associativity and precedence neutral, it will simply expand this to {{
116(expt 1 3 4) }}, which will result in an error since the {{ expt }} procedure
117only takes 2 arguments.
118
119Thus, most of the following are syntax wrappers for common infix operators
120whose chicken scheme implementation only takes two arguments. The macros handle
121more than two arguments with the correct associativity, and are fit for use in
122'simple' (unmixed) curly infix expressions.
123
124The procedure aliases simply provide common shorthand for some unary operators.
125
126<syntax>(** . rest)</syntax>
127
128Applies {{expt}} on all arguments right-associatively.
129
130<syntax>(% . rest)</syntax>
131
132Applies {{modulo}} on all arguments left-associatively.
133
134<syntax>(<< . rest)</syntax>
135
136Applies {{arithmetic-shift}} on all arguments left-associatively. Equivalent to
137a left shift if shift is positive, right shift if shift is negative.
138
139<syntax>(>> . rest)</syntax>
140
141Applies {{arithmetic-shift}} (with inverted direction) on all arguments
142left-associatively. Equivalent to a right shift if shift is positive, left
143shift if shift is negative.
144
145<syntax>(^ . rest)</syntax>
146
147Applies {{bitwise-xor}} on all arguments left-associatively.
148
149<syntax>(ior . rest)</syntax>
150
151Applies {{bitwise-ior}} on all arguments left-associatively.
152
153<syntax>(& . rest)</syntax>
154
155Applies {{bitwise-and}} on all arguments left-associatively.
156
157<procedure>(~ arg)</procedure>
158
159An alias for {{bitwise-not}}.
160
161<procedure>(~ arg)</procedure>
162An alias for boolean {{not}}.
163
164===== Special symbols
165
166In general, you shouldn't need to use the following directly, as curly
167expressions containing mixed operators or neoteric calls of the form {{x[a]}}
168will simply automatically expand into {{($nfx$ ...)}} or {{($bracket-apply$
169x a)}}, respectively.
170
171<syntax>($nfx$ . rest)</syntax>
172
173Group the infix expression specified by the elements of {{rest}} according to
174{{mixed-operator-precedence}}.
175
176<procedure>($bracket-apply$ obj i)</procedure>
177An alias for SRFI-123's {{ref*}}.
178
179=== Author
180
181Reference implementation by David A. Wheeler and Alan Manual K. Gloria,
182Chicken-specific implementation and extras by Diego A. Mundo.
183
184=== License
185
186Copyright (C) 2012 David A. Wheeler and Alan Manuel K. Gloria. All Rights
187Reserved.
188Copyright (C) 2019 Diego A. Mundo
189
190Permission is hereby granted, free of charge, to any person obtaining a copy of
191this software and associated documentation files (the "Software"), to deal in
192the Software without restriction, including without limitation the rights to
193use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
194of the Software, and to permit persons to whom the Software is furnished to do
195so, subject to the following conditions:
196
197The above copyright notice and this permission notice shall be included in all
198copies or substantial portions of the Software.
199
200THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
201IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
202FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
203AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
204LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
205OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
206SOFTWARE.
207
208=== Version History
209
210; 0.1.3 : Rename extras module to srfi-105.extra
211; 0.1.2 : Use standard keyword syntax, properly check for (#:other) group
212; 0.1.1 : Initial implementation of base srfi + extras
Note: See TracBrowser for help on using the repository browser.