-
Notifications
You must be signed in to change notification settings - Fork 0
/
lrpl.1
278 lines (278 loc) · 7.54 KB
/
lrpl.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
.\" lrpl
.TH LRPL 1 "2011-11-20" "" "User Commands"
.SH NAME
lrpl \- interactive RPL shell
.SH SYNOPSIS
.B lrpl
.SH DESCRIPTION
This RPL implementation consists of two parts:
.IP -
An extensible library implementing the core RPL data-types and operators, and
.IP -
A text-based shell intended to give the user the experience similar to that
of using a HP-28 calculator.
.PP
This is a reference manual
.B only
and assumes that the reader is well acquainted with the philosophy behind the
reverse Polish notation
.SM (RPN)
and the
.SM RPL
language. The following sections describe the particulars of this
.SM RPL
implementation (contained in the
.SM RPL
module), features of the
.I lrpl
interactive shell, and gives pointers to introductions and tutorials about the
RPN notation and the RPL language.
.SH LANGUAGE
The implementation follows the fundamental
.SM RPL
philosophy: there are a variety of data-types, a (global) stack holding
values, named variables, and operators that are overloadable by the number and
type of arguments.
.PP
As in
.SM RPL,
operators and variables live in the same namespace, but the implementation,
will
.B not
allow redefinitions of operators; only new overloads may be added. By
convention, all system-defined names, with the exception of
.I E
and
.I PI,
begin with a lower-case letter or a special symbol. Thus, using capitalized
variable names will ensure that there won't occur any clashes with already
existing names.
.PP
A
.B major difference
from other
.SM RPL
implementations is that general programmability "from within" is not
supported: new functions and data-types must be defined by extending existing
Ruby code.
.PP
The following two subsections describe currently implemented data-types and
operators.
.SS Data types
.IP Integer
Integers are signed and of unlimited precision. They may be entered in
decimal (optionally with leading minus sign), hexadecimal (with
.IR 0x )
prefix,
binary (with
.IR 0b )
prefix, or octal (with
.IR 0 )
prefix. Binary and hexadecimal numbers cannot have a leading sign.
.IP
.BR Note :
The RPL parser accepts octal numbers by accident; this feature may be removed
in a future release.
.IP Float
Floating-point numbers are accepted in the usual syntax, including scientific
notation. The decimal dot and fractional part are
.B required
for the number to be recognized as floating-point:
.I 3.0
and
.I 3.0e-4
will be parsed as floating-point numbers, whereas
.I 3
and
.I 3e-4
will be parsed as
.IR 3 ,
and
.I 3
followed by
.IR e-4 .
.IP List
Lists are heterogeneous collections of different objects delimited by
.IR {} ,
for example:
.RS
{ 1 2 a }
.RE
.IP
Unlike vectors and matrices, which can contain only numbers, lists can contain
also
.B unevaluated
names. Lists serve thus also as a quoting mechanism: wrapping a name into a
list will prevent its evaluation. This feature can be used to emulate a
simple macro facility: lists of commands can be stored to and recalled from
variables, and executed with the
.I eval
operator.
.IP
.BR Note :
In current implementation, lists cannot be nested and can conatin only numbers
and names. This restriction will be lifted in future revisions.
.IP Vector
Vectors are collections of elements delimited by
.IR [] ,
with individual elements delimited by spaces, e.g.:
.RS
[ 1 2 ]
.RE
.PP
.IP Matrix
Matrices are entered as vectors of vectors. For example, a 2x3 matrix is
entered (on a single line!) as:
.RS
[[1 2 3] [4 5 6]]
.RE
.IP Name
Variable names may be constructed from all alphanumeric and some punctuation
characters. A name can refer to a function or a data object (one of the types
listed above). Unless placed in a list, names are automatically looked up and
their contents evaluated.
.SM RPL
code may store only data objects into variables; new functions can be defined
only in Ruby.
.SS Operator reference
This section lists currently implemented functions by group. Where reasonable,
functions are overloaded with their established meanings, e.g.,
.IR + ,
can add any combination of integer and floating-point numbers, as well as
vectors and matrices of compatible dimensions.
.IP Constants
.IR PI , E
.IP "Arithmetic and transcedental functions"
.IR + ,
.IR - ,
.IR * ,
.IR / ,
.IR % ,
.IR pow ,
.IR mod ,
.IR neg ,
.IR abs ,
.IR inv ,
.IR floor ,
.IR ceil ,
.IR trunc ,
.IR r>d " (radians to degrees),"
.IR d>r " (degrees to radians),"
and all unary and binary functions from the
.I Math
module.
.IP "Bitwise operators"
.IR stws ", " rcws
set and recall the current word size for integer arithmetic. If 0, all integer
arithmetic is performed in unlimited precision.
.IP
.IR and ", " or ", " xor ", " not
perform the usual bitwise Boolean operations.
.IP
.IR shl ", " shr ", " shlx ", " shrx
shift an integer to left or right by one or multiple bits.
.IP "Relational operators"
.IR < ,
.IR <= ,
.IR > ,
.IR >= ,
.IR <> ,
.IR ==
.P
.IP
.BR Note :
These operators return Boolean flags (true/false), which cannot be used by any
other functions at the moment.
.IP "Stack manipulation"
.IR drop ", " dup ", " over ", " swap ", " rot ", " unrot ", " clear ", " eval
.IP "Variable manipulation"
.I !
takes a list of names and pops stack elements storing each into the
corresponding variable named in the list. Top of stack is stored into the
.B last
variable. An error will be reported if there is insufficient number of
elements on the stack or a name refers to a function.
.IP
.I purge
takes a list of names and removes definition of each variable. An error is
reported if a variable does not exist or refers to a function.
.IP "Matrix and vector algebra"
.IR +,
.IR -,
.IR *
are defined for all meaningful combinations of vectors, matrices and scalars.
.IP
.I /
can be used to divide a vector with a number, as well as to solve linear
systems: \&"dividing" a vector by a matrix computes the matrix inverse and
multiplies it with the vector.
.IP
.IR dot ", " cross
compute dot and cross products. The latter is defined only for 3-D vectors.
.IP
.IR det , inv , trn
compute matrix determinant, inverse, and transpose.
.IP
.I idn
takes a numeric argument N and constructs an NxN identity matrix.
.IP
.I "diag->"
takes a vector and creates a diagonal matrix with the vector elements on the
diagonal.
.IP "Collective functions"
.IR ~ " (mnemonic: thread)"
applies a unary or binary operation elementwise on any combination of vectors
and numbers. For example, the following subtracts 10 from each element of a
vector:
.RS
[1 2 3] { 10 - } ~
.RE
resulting in
.I "[-9 -8 -7]"
.SS THE INTERACTIVE SHELL
The shell implements a simple REPL (read-eval-print loop) and must be invoked
executing the Ruby interpreter on the
.I lrpl.rb
script, as in:
.RS
ruby lrpl.rb
.RE
Currently, no command-line options are defined.
.PP
The input is line-based, i.e., an input line
.B must
be complete. In other words, it is not allowed to split a long input, such as
a matrix, into multiple lines. The input is immediately parsed and executed,
and if no errors occurred, the resulting stack is displayed; otherwise, only
an error reported.
.PP
The shell behavior can be controlled by
.I pseudo-commands
which
.B always
begin with a period, e.g.
.I ".hex"
.SS Pseudo-command reference
.Bl -tag
.IP "Display control"
.IR ".hex" ,
.IR ".dec"
set integer base.
.IP Miscellaneous
.I .quit
.SH REFERENCES
Stable links to the original user manual for HP's calculators are somewhat
hard to find. A lot of documentation and tutorials may be found in the
documentation sections on the following sites:
.IP
http://www.hpcalc.org
.IP
http://hpmuseum.org
.IP
http://www.hpmuseum.org/rpn.htm
.PP
The last link gives a short introduction to the
.SM RPN
notation and further pointers.
.Sh AUTHORS
.An Zeljko Vrba