| blob | 889b7cb50e54ddb57095356e9e367b92d783875e |
1 /** \mainpage RPN Documentation
2 *
3 * \section intro Introduction
4 *
5 * RPN is an easy-to-use Reverse Polish Notation calculator with a fair amount
6 * of useful features. It started out as a sort of pet project, but has become
7 * somewhat serious to me.
8 *
9 * At 1.0, this was a fully-function plain calculator, with not many bells and
10 * whistles. In 1.1, I added variables, and in 1.2 I ported this to the
11 * PlayStation portable. In 1.3, I ported this to the Nintendo Wii, and fixed
12 * some potential bugs with Valgrind.
13 *
14 * In the current version, 2.0.0.0, I've re-written the program in C++.
15 * The source code is now less than half of what the C code was, though the
16 * compiled executable is larger. This release has the same PSP and Wii
17 * ports, though I've not tested them well; however, I don't expect any problems
18 * with them.
19 *
20 * \section features Features
21 *
22 * Like any calculator, RPN can calculate, so it supports many operators:
23 * addition, subtraction, multiplication, division, exponentiation, bitwise
24 * operations, etc. Unlike some, however, RPN has support for commands and
25 * variables.
26 *
27 * Commands are like operators in implementation, but are separate because they
28 * affect the calculator as a whole--it's stack, variables, etc. Operators only
29 * affect the stack. This limitation is part of the design of the program. A
30 * downside to this is that operators can only have two operands. This isn't
31 * much of a problem yet, but it may be later if one wants to add a ternary
32 * operator. For now, anything that can't be implemented as an operator should
33 * be implemented as a command.
34 *
35 * Variables let you save the results of your expressions and keep shorthands
36 * for commonly used numbers. There are some predefined variables like PI, E,
37 * and kilobyte/kibibyte/etc. All predefined variables begin with an uppercase
38 * letter, but there are currently no limitations for a variable name except
39 * 1) it must have at least one non-numerical character, and 2) it cannot be the
40 * same as a command or operator. This gives you a lot of freedom to choose
41 * whatever name you want.
42 *
43 * \section about About the Program
44 *
45 * By default, the calculator uses "long doubles" to store values. On my 64-bit
46 * Pentium D processor, this is 128 bits wide, and can hold up to about 2 **
47 * 16383 before reaching "infinity"--a 4932 digit number. So, though this is not
48 * an arbitrary precision calculator, it should be good enough for most people.
49 * If you compile with the flag RPN_DOUBLE, however, then "doubles" will be used
50 * instead.
51 *
52 * I'm not quite sure how portable this program is. It compiles on Ubuntu Linux,
53 * so it will likely compile on any GNU/Linux system with the right libraries. I
54 * believe that all the functions I use are POSIX, so hopefully this program can
55 * be ported easily to just about anything. The PSP port wasn't too difficult,
56 * though, and that required creating a custom input system!
57 *
58 * \section comp Compiling
59 *
60 * Hopefully, compiling can be as simple as "make; make install". However, you
61 * may need to make changes to the Makefile, and may need to type, for instance,
62 * "sudo make install" instead.
63 *
64 * Compiling for the PSP should not present any difficulties if you already have
65 * a PSP SDK and toolchain installed. If not, you can find a great tutorial on
66 * the Gentoo wiki. I used it to install the toolchain and SDK on Ubuntu 7.10
67 * without problem. See \ref psp-spec for more information about the PSP port.
68 *
69 * Likewise, compiling for the Wii should be simple if you already have a
70 * properly setup DevkitPPC toolchain; but that's easier said than done. See
71 * \ref wii-spec for more information abouth the Wii port.
72 *
73 * \section using Using the Program
74 *
75 * When you first run the program, you're presented with a simple prompt:
76 *
77 * \code
78 * [0]>
79 * \endcode
80 *
81 * The number in barckets is the topmost item of the stack. To push a number to
82 * it, just type it in and press enter.
83 *
84 * \code
85 * [0]> PI
86 * [3.14159]>
87 * \endcode
88 *
89 * Great! But this is a calculator--how do you calculate? If you don't know what
90 * Reverse Polish Notation is, look it up on Wikipedia. Done yet? Good. If you
91 * want to multiply by five, type this.
92 *
93 * \code
94 * [3.14159]> 5 *
95 * [15.708]>
96 * \endcode
97 *
98 * You can even do more than one operation per line.
99 *
100 * \code
101 * [15.708]> 3 / 2 -
102 * [3.23599]>
103 * \endcode
104 *
105 * But what if you want to see the whole stack?
106 *
107 * \code
108 * [3.23599] 2 1
109 * [1]> ps
110 * [ 1, 2, 3.23599, ]
111 * [1]>
112 * \endcode
113 *
114 * How about removing the top item of the stack?
115 *
116 * \code
117 * [1]> pop
118 * [2]>
119 * \endcode
120 *
121 * How about duplicating the top item of the stack?
122 *
123 * \code
124 * [2]> dup ps
125 * [2, 2, 3.23599, ]
126 * \endcode
127 *
128 * Can you print the stack in more detail?
129 *
130 * \code
131 * [2]> psd
132 * [ 2.000000, 2.000000, 3.235988, ]
133 * \endcode
134 *
135 * \section thanks Thanks
136 *
137 * Much thanks to Troy Hanson for uthash. It made the program much better, and
138 * makes implementing hash tables wonderfully simple.
139 *
140 * The PSP port would not have been possible without the tutorials at
141 * psp-programming.com. The callback functions are almost carbon-copied form
142 * them.
143 *
144 * The Wii port would not have been possible without the help of wiibrew.org.
145 */
147 /**
148 * \page psp-spec Specific Information About the PSP Port
149 *
150 * In the current version, the PSP port is very, very simple. It works, and you
151 * can actually type, though not easily. It is basically a full port, though the
152 * error module is simplified. The highest calculatable value, I believe, is
153 * 2 ** 1023.
154 *
155 * Because not many people have a PSP toolchain on hand, I've included a
156 * pre-built EBOOT.PBP. Though compiled for firmware 1.50, I have successfully
157 * run it under 4.00 M33-2. To install it, simply copy EBOOT.PBP to
158 * ms0:/PSP/GAME/PSPRPN .
159 *
160 * \section psp-type How to Type on the PSP
161 *
162 * Typing numbers is a combination of cross, circle, and a directional button.
163 * Pressing cross alone is 0; pressing cross and up simultaneously is 1; cross
164 * and right 2; cross and down 3; and cross and left 4. This direction
165 * order--up, right, down, and left--is consistent thoughout all typing modes.
166 *
167 * There is also an alternate mod, accessed by pressing the right trigger once;
168 * think of it as a caps lock. Not all button combinations have alternate
169 * characters, however, so they do not change.
170 *
171 * If you make a mistake, there is no way (currently) to undo it. If you press
172 * the left trigger alone, however, any input you've entered will be discarded.
173 *
174 * Here is a table of typable characters.
175 *
176 * <TABLE>
177 * <TR>
178 * <TD><STRONG>Buttons</STRONG></TD>
179 * <TD><STRONG>Normal Character</STRONG></TD>
180 * <TD><STRONG>Alternate Character</STRONG></TD>
181 * </TR>
182 * <TR>
183 * <TD>X</TD>
184 * <TD>0</TD>
185 * <TD>0</TD>
186 * </TR>
187 * <TR>
188 * <TD>X Up</TD>
189 * <TD>1</TD>
190 * <TD>1</TD>
191 * </TR>
192 * <TR>
193 * <TD>X Right</TD>
194 * <TD>2</TD>
195 * <TD>2</TD>
196 * </TR>
197 * <TR>
198 * <TD>X Down</TD>
199 * <TD>3</TD>
200 * <TD>3</TD>
201 * </TR>
202 * <TR>
203 * <TD>X Left</TD>
204 * <TD>4</TD>
205 * <TD>4</TD>
206 * </TR>
207 * <TR>
208 * <TD>()</TD>
209 * <TD>5</TD>
210 * <TD>5</TD>
211 * </TR>
212 * <TR>
213 * <TD>() Up</TD>
214 * <TD>6</TD>
215 * <TD>6</TD>
216 * </TR>
217 * <TR>
218 * <TD>() Right</TD>
219 * <TD>7</TD>
220 * <TD>7</TD>
221 * </TR>
222 * <TR>
223 * <TD>() Down</TD>
224 * <TD>8</TD>
225 * <TD>8</TD>
226 * </TR>
227 * <TR>
228 * <TD>() Left</TD>
229 * <TD>9</TD>
230 * <TD>9</TD>
231 * </TR>
232 * <TR>
233 * <TD>[]</TD>
234 * <TD>.</TD>
235 * <TD>=</TD>
236 * </TR>
237 * <TR>
238 * <TD>[] Up</TD>
239 * <TD>+</TD>
240 * <TD>+</TD>
241 * </TR>
242 * <TR>
243 * <TD>[] Right</TD>
244 * <TD>-</TD>
245 * <TD>-</TD>
246 * </TR>
247 * <TR>
248 * <TD>[] Down</TD>
249 * <TD>*</TD>
250 * <TD>*</TD>
251 * </TR>
252 * <TR>
253 * <TD>[] Left</TD>
254 * <TD>/</TD>
255 * <TD>/</TD>
256 * </TR>
257 * <TR>
258 * <TD>^</TD>
259 * <TD>Space</TD>
260 * <TD>Space</TD>
261 * </TR>
262 * <TR>
263 * <TD>^ Up</TD>
264 * <TD>%</TD>
265 * <TD>%</TD>
266 * </TR>
267 * <TR>
268 * <TD>^ Right</TD>
269 * <TD>^</TD>
270 * <TD>^</TD>
271 * </TR>
272 * <TR>
273 * <TD>^ Down</TD>
274 * <TD>&</TD>
275 * <TD>&</TD>
276 * </TR>
277 * <TR>
278 * <TD>^ Left</TD>
279 * <TD>|</TD>
280 * <TD>|</TD>
281 * </TR>
282 * <TR>
283 * <TD>LT X</TD>
284 * <TD>a</TD>
285 * <TD>A</TD>
286 * </TR>
287 * <TR>
288 * <TD>LT X Up</TD>
289 * <TD>b</TD>
290 * <TD>B</TD>
291 * </TR>
292 * <TR>
293 * <TD>LT X Right</TD>
294 * <TD>c</TD>
295 * <TD>C</TD>
296 * </TR>
297 * <TR>
298 * <TD>LT X Down</TD>
299 * <TD>d</TD>
300 * <TD>D</TD> <!-- This is SPARTAAA!!! -->
301 * </TR>
302 * <TR>
303 * <TD>LT X Left</TD>
304 * <TD>e</TD>
305 * <TD>E</TD>
306 * </TR>
307 * <TR>
308 * <TD>LT ()</TD>
309 * <TD>f</TD>
310 * <TD>F</TD>
311 * </TR>
312 * <TR>
313 * <TD>LT () Up</TD>
314 * <TD>g</TD>
315 * <TD>G</TD>
316 * </TR>
317 * <TR>
318 * <TD>LT () Right</TD>
319 * <TD>h</TD>
320 * <TD>H</TD>
321 * </TR>
322 * <TR>
323 * <TD>LT () Down</TD>
324 * <TD>i</TD>
325 * <TD>I</TD>
326 * </TR>
327 * <TR>
328 * <TD>LT () Left</TD>
329 * <TD>j</TD>
330 * <TD>J</TD>
331 * </TR>
332 * <TR>
333 * <TD>LT []</TD>
334 * <TD>k</TD>
335 * <TD>K</TD>
336 * </TR>
337 * <TR>
338 * <TD>LT [] Up</TD>
339 * <TD>l</TD>
340 * <TD>L</TD>
341 * </TR>
342 * <TR>
343 * <TD>LT [] Right</TD>
344 * <TD>m</TD>
345 * <TD>M</TD>
346 * </TR>
347 * <TR>
348 * <TD>LT [] Down</TD>
349 * <TD>n</TD>
350 * <TD>N</TD>
351 * </TR>
352 * <TR>
353 * <TD>LT [] Left</TD>
354 * <TD>o</TD>
355 * <TD>O</TD>
356 * </TR>
357 * <TR>
358 * <TD>LT ^</TD>
359 * <TD>p</TD>
360 * <TD>P</TD>
361 * </TR>
362 * <TR>
363 * <TD>LT ^ Up</TD>
364 * <TD>q</TD>
365 * <TD>Q</TD>
366 * </TR>
367 * <TR>
368 * <TD>LT ^ Right</TD>
369 * <TD>r</TD>
370 * <TD>R</TD>
371 * </TR>
372 * <TR>
373 * <TD>LT ^ Down</TD>
374 * <TD>s</TD>
375 * <TD>S</TD>
376 * </TR>
377 * <TR>
378 * <TD>LT ^ Left</TD>
379 * <TD>t</TD>
380 * <TD>T</TD>
381 * </TR>
382 * <TR>
383 * <TD>LT RT X</TD>
384 * <TD>u</TD>
385 * <TD>U</TD>
386 * </TR>
387 * <TR>
388 * <TD>LT RT X Up</TD>
389 * <TD>v</TD>
390 * <TD>V</TD>
391 * </TR>
392 * <TR>
393 * <TD>LT RT X Right</TD>
394 * <TD>w</TD>
395 * <TD>W</TD>
396 * </TR>
397 * <TR>
398 * <TD>LT RT X Down</TD>
399 * <TD>x</TD>
400 * <TD>X</TD>
401 * </TR>
402 * <TR>
403 * <TD>LT RT X Left</TD>
404 * <TD>y</TD>
405 * <TD>Y</TD>
406 * </TR>
407 * <TR>
408 * <TD>LT RT ()</TD>
409 * <TD>z</TD>
410 * <TD>Z</TD>
411 * </TR>
412 * </TABLE>
413 */
415 /**
416 * \page wii-spec Specific Information about the Wii Port
417 *
418 * The Wii port, like the PSP port, is very simple. You can "type," and in a
419 * simpler way than the PSP, but it's still slow to use. In the future, I'll
420 * update the input module to be simpler to use, but for now it will suffice.
421 *
422 * \section wii-type How to Type on the Wii
423 *
424 * The input buffer is limited to 64 characters, and starts out as all spaces.
425 * Use the left and right buttons to navigate through the buffer, and the up and
426 * down buttons to change the character at that position of the buffer. Press A
427 * when done to evaluate the input.
428 */
430 /**
431 * \page spec Specific Information About the Program
432 *
433 * This section conveys the basic structure of the program so that you can get
434 * an idea of what the hell I was thinking when writing this program. Not
435 * everything here applies to the PSP port; see \ref psp-spec to read more about
436 * the port.
437 *
438 * \section exec Execution
439 *
440 * On startup, the program processes arguments. Some arguments, like "-v" and
441 * "-e", exit the program after completion.
442 *
443 * After this, a loop is entered that is controlled by the calculator's status.
444 * As long as the status equals RPN_STATUS_CONTINUE, the loop executes. Commands
445 * should exit the program by setting the status to RPN_STATUS_EXIT, unless some
446 * severe error occurs, in which case one should use exit() or a similar
447 * function.
448 *
449 * In the loop, the user is presented with a peek at the stack and a prompt to
450 * evaluate a string. Upon pressing Enter, the string is sent to RPN_eval, which
451 * uses RPN_splitString to get a list of tokens. It then iterates through the
452 * tokens, pushing numeric ones to the stack and delegating others to
453 * RPN_evalToken.
454 *
455 * RPN_evalToken tries to find an operator equal to the token; if it can't, it
456 * sends the token to RPN_executeCommand, and if that cannot, the token is added
457 * to the variable table and its value set to the value of the topmost stack
458 * item.
459 *
460 * \section structs Structures
461 *
462 * The quintessential Reverse Polish Notation calculator structure is the stack.
463 * My stack is RPNStack, which holds only a pointer to the first node of the
464 * stack. The node structure, RPNNode, holds the value of the node and a pointer
465 * to the next node in the stack.
466 *
467 * An RPNOperator holds the name and function of an operator. A callback
468 * function for an operator looks like this:
469 *
470 * \code
471 * void customOperator(RPNValue a, RPNValue b)
472 * {
473 * }
474 * \endcode
475 *
476 * RPNOperators is a hash table, implemented with UTHash. It contains just a
477 * pointer to the UTHash table.
478 *
479 * RPNCommand and RPNCommands are almost exactly like RPNOperator and
480 * RPNOperators, respectfully, except that command callbacks are passed the
481 * entire calculator structure to give them more power. Here is what it looks
482 * like:
483 *
484 * \code
485 * void customCommand(RPNCalculator *calculator)
486 * {
487 * }
488 * \endcode
489 *
490 * RPNVariable and RPNVariables are also similar, except they have values
491 * instead of function pointers.
492 */