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