A User Guide for the RPNCalc Calculator

Copyright 2011- 2024 by Michael Fross
This document, along RPNCalc, is licensed under the MIT License

The RPNCalc Github Homepage

INTRODUCTION

RPNCalc is the command-line based Reverse Polish Notation (RPN) calculator. RPN calculators make it very simple to do complex calculations, especially if there are parentheses involved. In essence, you enter your numbers first, then the operator.

So, to add 2 and 3 to get 5, you would first add the number 2 to the stack: 2 [Enter]. Then you would add 5 to the stack (pushing the 2 to the second position: 3 [Enter]. Now, to add them you would enter: + [Enter] and RPNCalc would remove the 2 and 3 from the stack, add them, and push 5 back onto the stack.

The following example can be tricky to get your head around in a traditional calculator but is quite easy with RPN. The chapter What is an RPN Calculator will go through solving this step by step.

x = SQRT(((((5+3) * 8)/2) * (2+1)) ^ 2)

RPN is based on a Last In First Out (LIFO) stack framework which sounds complicated, but makes intuitive sense when you use it. You can think of it as a stack of plates. When you put one on the top of the stack, everyone other one shifts down by one. On a RPN calculator, there is no equal sign, but there is an enter key to put a value onto the stack. The chapter on Stacks talks more about how this works with RPNCalc.

If you have not heard of reverse Polish notation, or just have a passion for various calculator notations (and seriously, who doesn't?), you can read more about RPN on Wikipedia or a (very) quick summary in the What is an RPN Calculator chapter.

My Brief History of RPNCalc

I studied Engineering in college and used the HP15C calculator (yes, I'm old.) I grew to love RPN and over the years I've used various RPN calculators. However, I failed to find a simple command line version that I liked. Therefore, I decided to write one back in 2011.

One key goal was to make it extensible so I could easily add new features, constants, and capabilities. A second goal was to allow it to run everywhere I needed it to run, which is mostly Windows and Linux. Therefore it's written in Java, it should run just about anywhere Java is supported. And, while this calculator doesn't have every function a complex scientific calculator would have, it has the basics covered.

Lastly, I didn't want to have to have a big uninstall/install task to upgrade to a new version. With RPNCalc, it's just one JAR file. You just run it (java -jar rpncalc.jar). Nothing to install or uninstall. If you want to remove it, just delete the rpncalc.jar file.

Contact Options & Links

The home page for RPNCalc is located on GitHub. It's open source with a very open usage license.

• Report issues or enhancement requests, please post at RPNCalc's issues page
• For RPNCalc discussions, you can post on the Discussion page
• The RPNCalc Snap Store Page
• You can also reach me directly at rpncalc@fross.org
• Checkout my other open source programs on GitHub

The Current Help Page from RPNCalc

From within the program, entering h, help or ? will show the program help screen. The help can also be viewed by starting RPNCalc with the -h or -? command line switch (i.e. rpncalc -h)

The current RPNCalc help screen:

What is an RPN Calculator?

For me, the way I thought about using RPN back in the early 1990s was to approach it with start on the inside and work your way out. Just look at the inner most calculation, and start working yourself back out. It also helps if you also understand the order of operations for the operands.

Order of Operations - PEMA

Walkthrough of the Example from the Introduction Page

x = SQRT( ((((5+3) * 8)/2) * (2+1)) ^ 2 )

This can be tricky with a traditional calculator. However, with a RPN Calculator, to solve for x you would start on the inner calculation and work outwards. Looking at the equation, 5 + 3 is about the lowest so lets start there. The approach will be work back up until you get to a peer of the same "level". Then do the 2+1. We'll walk through each step and explain what's happening. Go ahead and start RPNCalc and follow along - it's much easier to do it and see the stack rather than just reading it here.

The result is 96 which ends up on the top (line1) of an otherwise empty stack. I'll talk more about stacks and how RPNCalc uses them in future chapters.

By the way, this can also be dramatically shortened using the NumOps shortcut - see the Operands chapter for more information.

Traditional RPN Notation Limitations in RPNCalc

Please note that RPNCalc doesn't implement every RPN convention and there are a few as of yet unimplemented items.

For example, this won't work in RPNCalc:

10 + 10 + 10 can't be solved by entering 10 [Enter] 10 [Enter] 10 [Enter] ++ [Enter] as RPNCalc only allows one operand per command entry. You'll need an [Enter] between the last two + signs. Using the NumOp shortcut, this is an efficient way to solve that equation:

10 [Enter] 10+ [Enter] 10+ [Enter]

Wikipedia:

The following is directly from Wikipedia. There is a lot more information there, but here are a few highlights.

Explanation

In reverse Polish notation, the operators follow their operands; for instance, to add 3 and 4 together, one would write 3 4 + rather than 3 + 4. If there are multiple operations, operators are given immediately after their final operands (often an operator takes two operands, in which case the operator is written after the second operand); so the expression written 3 − 4 + 5 in conventional notation would be written 3 4 − 5 + in reverse Polish notation: 4 is first subtracted from 3, then 5 is added to it. An advantage of reverse Polish notation is that it removes the need for parentheses that are required by infix notation. While 3 − 4 × 5 can also be written 3 − (4 × 5), that means something quite different from (3 − 4) × 5. In reverse Polish notation, the former could be written 3 4 5 × −, which unambiguously means 3 (4 5 ×) − which reduces to 3 20 − (which can further be reduced to -17); the latter could be written 3 4 − 5 × (or 5 3 4 − ×, if keeping similar formatting), which unambiguously means (3 4 −) 5 ×.

Practical implications

In comparison, testing of reverse Polish notation with algebraic notation, reverse Polish has been found to lead to faster calculations, for two reasons. The first reason is that reverse Polish calculators do not need expressions to be parenthesized, so fewer operations need to be entered to perform typical calculations. Additionally, users of reverse Polish calculators made fewer mistakes than for other types of calculators. Later research clarified that the increased speed from reverse Polish notation may be attributed to the smaller number of keystrokes needed to enter this notation, rather than to a smaller cognitive load on its users. However, anecdotal evidence suggests that reverse Polish notation is more difficult for users to learn than algebraic notation.

Installation

There are two ways to install RPNCalc. The first is simply download rpncalc.jar file from the latest release on GitHub. I have embedded all of the dependencies into this one file and it is directly executable. You do not need to install anything. Of course, you will need a java runtime (JRE) installed in your path.

The second is to run it as a Snap. There are many advantages to using it as a snap and I'll get into that in the SNAP secion of this user guide. My personal preference is to install it via Snap for teh following reasons:

• No Java to worry about as it's built into the snap
• Protected as it runs in a sandbox and won't have access to other system objects
• No aliases needed to run it since rpncalc can be run directly from the command line. An example alias with Bash is below.
• Its automagically kept up to date
• Additional information is available in the SNAP chapter

Please note that I only have the ability to test it in Windows and Linux (Ubuntu). While I don't think there would be issues on other platforms, it's something to keep in mind. Snapcraft does compile them, however, without issue on the other platforms.

Standard Usage

To run RPNCalc use the following command:

java -jar /path/to/rpncalc.jar

This is much too long to type every time you need to run it, so I simply create an alias. Here is example from the Bash shell:

alias rpncalc='java -jar /path/to/rpncalc.jar

Now, I just need to type rpncalc to run it.

Standard Uninstall

If you wish to uninstall RPNCalc, just delete the file and, if you created an alias, remove that as well. Easy and simple.

However, RPNCalc does use the Java preferences to store the persistent stack contents, settings, and persistent memory slots. This system is located in different places depending on the OS and these are listed in the Stacks Chapter.

It is very small and removing it is not really necessary, but if you like to keep things exceptionally tidy, delete the org/fross/rpn/ entry (and everything below it) in the preference system.

Snap Installation

If you are on a Linux system and have Snap installed (it's comes default on most Ubuntu based distributions, but can be installed by most others if not already there), you can install RPNCalc as a snap. It does not require any special snap permissions. To install via snap use:

sudo snap install rpncalc

To run it after installation, simply execute:

rpncalc

Snap Uninstall

To uninstall, execute the following command:

sudo snap remove rpncalc

Stacks

The entire concept of a RPN calculator is based on a stack, which can be thoughts of as numbers stacked on top of each other. You add numbers to the stack and they are normally processed Last In First Out (LIFO).

With RPNCalc, when you leave the program, the current (and secondary) stacks are saved. If you didn't specify a named stack, the default stack is loaded. When you start the program you can specify which stack to load with the -l command. You may also load / create a new stack inside of the program with the load command. One use case is to create different aliases to open different stacks using the -l command.

When you perform calculations or commands, they generally work from the top of the stack down. In RPNCalc, the top of the stack is line1 and it's actually at the bottom of the display. When you perform calculations, you are working on your command line and the lines you are using are above the text entry area. This might be a bit hard to visualize, but makes a lot of sense when you actually use the calculator. Trust me.

For example, if you want to take the square root of 25, you enter 25 [ENTER] and it will be added to the top of the stack at line1. Anything else on the stack is pushed "up" on the display. Then execute the command SQRT [ENTER]. This will remove 25 from the stack on line1, perform the square root, then place the result 5 back onto the stack. Some operations require more than one stack item. The addition command +, for example, will take the last two numbers off the stack (line1 and line2), add them together, and then place the result on the stack.

The order of the numbers on the stack is important for some of the operands. This is detailed out in the Operand chapter.

Stack Management

Saving and loading stacks is fundamental to RPNCalc. You can have as many named stacks as you like. They are stored in the Java Preferences system which is located in various places depending on the OS:

It is safe to delete these if you wish, but of course you'll lose any saved stacks, memory slots, persistent configurations, and user defined functions which are stored there. The structure, not the data, will be recreated again when RPNCalc is restarted.

Each stack you load (default or a named stack) actually has 2 internal stacks defined; a primary and secondary. You can quickly swap stacks using the swap stack ss command. For example, you are working on something and need to do a few calculations that you wish to keep separate from your main work. You can swap stacks, do the work, then swap back. They do not communicate in any way and are distinctly separate. The primary and secondary stack data is saved and restored upon loading the stack. The primary and secondary stacks have their own unique undo stacks as of version 4.5. This was long standing issue that's now been resolved.

When you start up RPNCalc, you can load a named stack with the -l name command. If the stack name exists, it will be loaded. If it does not exist, the stack will be created and when you leave the program it will be saved under that name. You can always view the current stack you are using in the lower right of the dashed bar. The :1 or :2 after the stack name will tell you if you are on the primary or secondary stack.

As a side note, both stacks and memory slots are saved during shutdown. While the data in a stack is specific to that stack, memory slots and user created functions are global. The default stack items are restored at startup (or whatever stack you choose to load with -l name.) Memory slots are also restored at startup. list mem will show the values in current memory, and list stacks will show the existing stacks available to load.

High Level Usage

RPNCalc is a command line application that must be run from a console / command prompt. Executing it with a -h (or -?) switch, or starting the program and entering the h (or help or ?) command will display the in-program help page. This page lists all of the commands and operands that can be used, but it is fairly terse This can be also viewed at the bottom of the Introduction Chapter of this guide. This document is meant as a more comprehensive guide.

There are various command line switches that can be used when starting the program as are detailed in the Command Line Options Chapter. They generally exist so that aliases can be used to control several key parameters, most likely the -l StackName switch.

Once inside the program, you'll be presented a prompt where numbers, operands, and commands may be entered. Numbers will be added to the stack which you can think of as an upside down stack of plates. The top stack item (represented by line1 in the program) is on the bottom. You can think of this stack of plates as a Last In First Out (LIFO) approach.

For example, you could enter 2 [ENTER] it would be in the line1 position and would be on the top of the stack. If you then enter 3 [ENTER] the 2 would move up go line2 and the 3 would then be on line1 and be on the top of the stack. You can then enter in an operand, such as + to perform the action on the items opn the top of the stack. To continue our example, pressing + [ENTER] would take the top two items off of the stack, add them, and put the result back on top of the stack (line1).

I've gone into this in more detail in the What is an RPN Calculator Chapter and elsewhere and it's fairly easy and intuitive. Once you get the hang of it, you'll overwhelming regret having to use a standard calculator in the future. ;-)

Why is the stack "upside down?"

One question I get with RPNCalc is why is the top of the stack on the bottom? The reason is that it's simply more intuitive. The command line is on the bottom. You are usually dealing with the top of the stack so having line1 directly above makes sense. Also, for some operations, the order is important (think subtraction or division). Having line1 "underneath" line2 is easy to understand as that's how we learned to do subtraction. line1 is subtracted from line2.

Decimals & Fractions

In RPNCalc, the stacks always store numbers as decimals. You can, however, enter in fractions and they will be instantly converted to a decimal equivalent and added to the stack.

Example:

1 5/16 [ENTER]

will add 1.3125 to the top of the stack (line1)

14/8 [ENTER]

will add 1.75 to the stack

While you can never directly convert a decimal number on the stack back to a fraction, you can display an approximation of what the top of the stack (line1) value would be as a fraction. You do have to decide on the smallest denominator that will be used (called the base.) The default base is 64 which is the equivalent of 1/64 and will be used if no base is specified. Use the frac [base] command to display the approximate fractional equivalent. RPNCalc will simplify the fraction as much as it can so if line1 is 0.5, the command frac 4 won't convert and display 2/4. The result would be 1/2. Also note that frac [based] is a display command and will not actually change the stack in any way.

Example: 12.3456 [Enter] frac [Enter]

No base was entered, so use 64. It will display 12 11/32 RPNCalc converted it to 12 22/64 and then reduced it.

1 3/64 [Enter] frac 16 [Enter]

will display 1 1/16 as that's as close as it could get with a granularity of 1/16.

1 3/64 [ENTER] frac 100000

will display 1 293/6250. This is a closer approximation than using base 16. This also shows why this is an approximate.

Scientific Notation

As of version 5, scientific notation is supported. You can enter in values with the format 1.2345E18 and it will be saved as a value in the stack. There are a few areas where it's not 100% supported (i.e. NumOps at the time of this writing) but just about everything will work with it.

Operands, Numbers, and Commands

Numbers, whether decimal or fractions, can be entered on the command line and they get added to the stack. That's fairly self explanatory.

Operands perform basic match functions on those numbers.

Commands do the more exciting things. You can add the speed of light constant to the stack (sol) or PI (pi), take the sine of the number, add it to a memory slot, and then save that sequence of commands as a user defined function. Most of the rest of this guide will be talking about the various RPNCalc commands.

Lastly, as of v4.6.0, the arrow keys can be used within RPNCalc. Up/Down will move you through your historical entries, and Left/Right will move you within the current command line. This is probably what you would have expected it to do as it behaves similar to common consoles.

Precision

The intent of RPNCalc is to have unlimited precision in the numbers and calculations. RPNCalc leverages a Java technology called BigDecimal which limits precision only by the amount of memory in your machine. This is most likely more than you will ever need. However, the program does make use of several Java math methods which must be done via a Java Double.

A Double has the following characteristics:

• The upper range of a double in Java is 1.7976931348623157 x 10^308
• The lower range of a double in Java is 4.9 x 10^-324

I will attempt to point out in this guide when a command is using Double and therefore has a limit on precision. Double is, however, huge and shouldn't pose an issue for most use cases.

Command Line Options

Currently there are several command line options, and all are optional. Normally, one would simply run the program and you would enter in numbers, operands, and commands.

These options will either start RPNCalc in a certain "mode" such as Debug or No Color or will provide information and exist such as Version or Help.

Operands

Operands are the standard symbols used for basic mathematics on numbers. The following is the list of operands supported by RPNCalc. These are also supported by the NumOps shortcut described below.

With the exception of the addition (+) and multiplication (*) operands, the order of the items in the stack is important. It's fairly intuitive when you look at it in the calculator, but refer to the following table if needed.

Below are two very simple examples that show the order is important

Example: The minus - command will execute 3 - 2 and will yield 1

Example: Minus - will execute 2 - 3 and will yield -1

Hint: We'll discuss commands in later chapters, but the swap command s will swap the top two items in the stack (line1 and line2). Swap will also swap any two line numbers provided. See the Calculator Commands Chapter for more information.

The NumOps Shortcut

RPNCalc has an important shortcut that can speed up your calculations. You can append one of the above operands at the end of an entered number and the program will, behind the scenes, place the number on top of the stack (line1) and then execute the operand. The operand must directly follow the number without a space between. For example:

2 [ENTER]

3+ [ENTER]

When the second enter is pressed, the two stack items will be removed, added together, and the result, 5, will be added back. It's the same as entering this the following three commands:

2 [ENTER]

3 [ENTER]

+ [ENTER]

As an example of this NumOps shortcut, see the following example:

x = SQRT((((5+3) * 8)/2) ^ 6)

Leveraging the shortcut, this would become:

• 5
• 3+
• 8*
• 2/
• 6^
• SQRT

By the way, if you were wondering the answer is 32,768.

Please note that you can not use this NumOps shortcut with a fractional number entry or a scientific notation entry

Configuration

There are a few, although not many, configuration options available in RPNCalc. These are settings which control various aspects of the program and are persistent between executions. When these are changed, they are saved in the Java Preferences system.

There are currently three configuration options that can be changed the commands to do so are listed below. They are:

Program Width

Program Width controls the amount of characters the base program uses. This can be changed and is especially useful if using a terminal with a small number of characters per line.

Memory Slots

By default there are 10 memory slots numbers 0 through 9. This is probably more than most people would need, but if you save a lot of values, or have a User Defined Function that needs to store a lot of numbers, it can be changed. Each memory slot is simply an additional array element, so I don't think there is much of a memory impact, but I suppose if you have thousands it would increase memory usage.

Display Alignment

By default, the numbers displayed on the stack are left aligned. There are times when it is prefered to be right aligned (for example if you are working with money and always want two decimal places), or decimal aligned which is nice to easily see the integer from the decimal. Play around with it and see which one you like for difference circumstances.

Reset

Ok, this isn't really a configuration option, but the command can be used to reset everything back to the defaults. At the time of this writing, the defaults are:

• Program Width: 80 Current minimum width is 46 characters
• Memory Slots: 10 Numbered 0 through 9
• Display Alignment: l(eft)

f

Calculator Commands

We've discussed numbers, fractional, scientific notation, and decimal, as well as operands that perform basic mathematical functions. This chapter starts discussing commands which are the heart and soul of RPNCalc.

Calculator Commands are the basic commands that operations on the numbers you've placed on the stack. Most are fairly simple and intuitive, but there are a few that are a bit odd. I'm looking at you dice.

These commands, like the others you'll read about later, are executed by typing the command name, and any needed arguments into RPNCalc. Often there are several different names and abbreviations for the same command. This is just to make it easier to remember. Brackets, [] around an option denotes it is optional.

Conversions

The conversion commands will simply convert from one unit to another. As an example, I frequently use RPNCalc to convert from inches to millimeters or back.

I've included the ones I use the most, but I'm happy to include others if you'd find something else useful.

Fractional Display

The RPNCalc stack only contains decimal numbers. Therefore, we can't directly store fractional values on the stack. If a fraction is entered, it is converted to a decimal. There could be a loss of precision when this is done. For example, there is no exact fractional equivalent for PI much like there is no exact decimal equivalent for 1/3. However, the difference is usually so small that it's acceptable.

The frac [base] command takes the item on the top of the stack (line1) and displays the approximate fractional equivalent. [base] sets the precision of the calculation. If a base is not provided, RPNCalc will use 64 (1/64) as the default.

For example, if you had 1.1234 on the stack, frac would show you 1.1234 is approximately 1 1/8 No base was given so it would have used a base of 64 (which means maximum granularity would be 1/64) and auto reduced the result which is why you get the 1 1/8.

if frac 5 would have been entered (which means 1/5 is maximum granularity), you get 1.1234 is approximately 1 1/5.

Trigonometry Functions

RPNCalc does not consider itself a fully fledged scientific calculator (at least not currently). However, it's certainly beyond a very basic calculator. The trigonometry commands listed here are basic, but do fill a need if you need to do a few basic calculations.

Lastly, I'm happy to add more capabilities if there is a desire (and an offer to help test).

Memory Commands

The memory capabilities are fairly flexible. By default, there are 10 memory slots you can use (slot0 - slot9). This amount can be increased with the set memslots command. If you increase or decrease the number of memory slots, it is persistent across RPNCalc executions. You can change it as will, but if you decrease the number of slots, anything held in the "no longer there" slots will be discarded.

For example, say you set memslots 20 and store values in all of them. If you later set memslots 10, the values in the upper 10 slots will be discarded.

The operational command reset will reset all of the persistant settings back to their defaults including the number of memory slots.

The normal usage to is to save a value from the current line1 into a memory slot and copy it back later. The memory slots are saved between program executions so if you need it in a later session, it will be there. It's saved in the Java preferences system as discussed earlier.

Constants

These commands simply take a defined constant and add that number to the top of the stack (line1). There are currently not that many constants defined, but if there is a desire to add additional ones please me know. It's quick and easy.

To use a constant, simply run the command and the value of the requested constant will be added to the top of the stack (line1)

User Defined Functions

RPNCalc can record your commands and save them as a user defined function. In essence, you are creating a new command that can be run.

When recording a new function, start by adding data to your stack that would emulate when you would run your function. The only data that will be part of your recording will be data & commands entered after recording has been turned on. When you are ready, enter the record on command. A red [Recording] alert will appear in the status line. Anything you add during this period will be recorded with the exception of the commands listed below. Enter your commands, numbers, etc. until you are done.

When recording is complete, enter record off to complete your recording. You'll be prompted for a function name. Your new command will be this name so choose a name without spaces and that is easy to type when you wish to execute the function in the future. You should also not choose a name of an existing command as your function will not be able to be called. If you do not provide a name, i.e, just hit enter, the recording will be discarded.

Then you can run your function whever you like on the stack currently available. To run the function, simply type the name of your function as a standard command. To see a list of the saved functions, execute list func and it will display the name and the steps you recorded.

User defined functions can be deleted with the func del NAME command or you can delete all of the functions with func delall

Functions are global and can work across any stack. They are saved in the preferences system and will be reloaded when RPNCalc starts. They are saved immediatly after you give a new recording a name and press enter.

When you execute a function, the steps of that function are executed one after the other. Therefore when you execute undo you will undo back through your function step by step. You do not undo the entire function in one command. Of course you can always run undo NUM where NUM is the steps to undo.

The following commands can be entered during a recording, but are not recorded.

• list
• debug
• ver, version
• help, h, ?
• rec, record
• func, function
• set, reset
• cx, x, quit, exit

Example

Here is a full real world example. Lets say you'd like to make a user defined function to take the cube of number. Here are the steps you'd take to do that.

From now on, just type cube and line1 will be cubed! Go You!

Operational Commands

Operational commands are commands that do not directly impact your stack numbers. These tend to be display commands or those the interact with the the setting of RPNCalc directly.

Building RPNCalc from the Source

RPNCalc is written in Java and uses Maven as it's build tool. To build, you'll need to have the Java Development Kit (JDK) installed on your system. Make sure you get the JDK and not the Java Runtime Environment (JRE) which most people would have on their machines. The JRE allows you to run Java applications, but not build them. At the time of this writing, you'll need Java 11 or newer.

After the JDK is installed, you'll need to install the Apache Maven build tool. Then download/clone of the source code from Github along with my library package. This library package contains many methods that I use across my applications.

To install the library, execute the following from the top level library directory (the one with the pom.xml file in it):

mvn install

That should install the library into the Maven cache on your computer. You can remove the library directory.

Secondly, you'll need to build the executable RPNCalc jar file. Download, or clone, the RPNCalc source code from the link provided above. Unzip it to a directory and from the top level directory of RPNCalc, execute:

mvn package

Assuming all goes well, you'll have a new shiny rpncalc.jar file in the target directory.

Automated testing in RPNCalc (using JUnit5) is fairly complete (although testing can always be more extensive) and should catch most issues with the code. The hope is I find them before it's released, but pay attention to the Maven output and you'll see if there are issues.

I'll discuss this more in the Snap chapter, but if you are on a Linux system that supports snaps, I would encourage that you leverage it. Not only are Snap applications "sandboxed" so it's more secure, all of the dependencies are bundled in so you don't even need to have java installed on the machine. It is also automatically updated so you'll always have the latest. Although this can also be forced with sudo snap refresh.

My preference is to use the Snap installation which is what I do on my Ubuntu machines.

SNAP

I would encourage anyone with a supported Linux platform to use the Snap package of RPNCalc. You can learn more about Snap from the Snapcraft Homepage.

At a high level, a Snap is a fully contained container with your application and it's dependencies bundled in. It runs in a sandbox so it can't interfere with other parts of your system until it's given access. Snaps are automatically kept up to date and are easily removed leaving no trace on the system. There is even a nice App Store where you can find software.

As an example, RPNCalc uses Java, but you don't have to have Java installed on your machine as it's bundled in with the Snap.

As a shameless plug, you can Search for 'Fross' to see all of my Snap packages, or visit my GitHub home for my other open source software.

While I'm a fan of Snaps, there are positives and negatives to using them.

Snap: The Good and the Bad

-- Thanks to the good folks at MakeUseOf.com for this! --

MakeUseOf.com has a good breakdown of everything that's good and bad about Snap.

Ever since Canonical announced Snap, there's been a stir in the Linux community about whether Snap is the right approach to improve package distribution on Linux. This has given rise to two opposing camps: one in favor of Snap and the other critical of its approach in the long run.

Here's a breakdown of everything that's good and bad about Snap.

Advantages of Using Snap

• Snaps come bundled with dependencies (libraries) that facilitate instant access to a program, as you no longer have to manually install the missing dependencies to make it work on your system.
• Each snap runs in its own containerized sandbox to avoid interference with other system packages. As a result, when you remove a snap, the system removes all of its data, including dependencies, without affecting other packages. Needless to say, this also offers a more secure environment since one package can't access the information of another.
• Snap updates snaps automatically at set intervals. Hence, you always run the latest version of a program on your system.
• Snap makes it easier for developers to distribute their software directly to users, so they don't have to wait for their Linux distribution to roll them out.
• Adding to the previous point, another advantage of putting developers in charge of packaging and distributing their software is that they don't have to create distro-specific packages, as it comes bundled with the required dependencies.

Disadvantages of Snap

• Since snaps come bundled with dependencies, they're larger in size and occupy more disk space than their counterparts from other package managers.
• As a result of the bundled dependencies, snaps are distributed as compressed filesystem images and you need to mount them first before installing. Because of this, snaps are slower to run than traditional packages.
• Although Snap enables developers to distribute their snaps directly to users, the distribution pipeline requires them to set up an account with Canonical and host their snaps on it. This goes against the true nature of the open-source methodology because even though the software is still open source, the package management system is controlled by an entity.
• Another downside to allowing developers to distribute packages is that the packages don't go through stringent checks and reviews by the community and therefore carry the risk of containing malware---as seen a few years back.
• Due to the fact that Snap's back-end is still closed-source and controlled by Canonical, many major Linux distros aren't on board with the idea of putting Snap as the default package manager on their system.

Wrapup

Well, if you've read this far you probably know more about RPNCalc than I do. I needed a command line based RPN calculator and have been very happy with this one. I've added features as I've needed them and use it daily for many years now. Some time ago I decided to make the program, source, and documentation available so others could use it if they wished. For those that have, I hope you found it useful.

I'll continue to add new features as I think about them. If you have suggestions, issues, or ideas, the links to reach out to me are on the Introduction page.

Best wishes and happy reverse Polish notation calculating...

Licenses

RPNCalc is licensed under the MIT license as documented below. However, it does make use of several libraries that may use a different license, so please ensure you comply with all of the licenses contained herein.

RPNCalc License

The RPNCalc software as well as this User Guide are licensed via the MIT License. You can read more about this license in the link below.

The MIT License

Copyright (C) 2011-2024 by Michael Fross

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

jAnsi Library
jCommander Library
Apache Maven

These software packages are licensed under the Apache Software License v2.0 as detailed below.

The Apache License, Version 2.0

Apache License Version 2.0, January 2004 http://www.apache.org/licenses/

TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

1. Definitions.

"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.

"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.

"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.

"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.

"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.

"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.

"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).

"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.

"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."

"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.

2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.

3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.

4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:

You must give any other recipients of the Work or Derivative Works a copy of this License; and You must cause any modified files to carry prominent notices stating that You changed the files; and You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.

You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.

6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.

7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.

8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.

9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.

END OF TERMS AND CONDITIONS

jUnit5
OpenJDK

The above packages aresubject to the Eclipse Public License - v2.0 as detailed below.

Eclipse Public License - v 2.0 THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC LICENSE (“AGREEMENT”). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.

1. Definitions “Contribution” means:

a) in the case of the initial Contributor, the initial content Distributed under this Agreement, and b) in the case of each subsequent Contributor: i) changes to the Program, and ii) additions to the Program; where such changes and/or additions to the Program originate from and are Distributed by that particular Contributor. A Contribution “originates” from a Contributor if it was added to the Program by such Contributor itself or anyone acting on such Contributor's behalf. Contributions do not include changes or additions to the Program that are not Modified Works. “Contributor” means any person or entity that Distributes the Program.

“Licensed Patents” mean patent claims licensable by a Contributor which are necessarily infringed by the use or sale of its Contribution alone or when combined with the Program.

“Program” means the Contributions Distributed in accordance with this Agreement.

“Recipient” means anyone who receives the Program under this Agreement or any Secondary License (as applicable), including Contributors.

“Derivative Works” shall mean any work, whether in Source Code or other form, that is based on (or derived from) the Program and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship.

“Modified Works” shall mean any work in Source Code or other form that results from an addition to, deletion from, or modification of the contents of the Program, including, for purposes of clarity any new file in Source Code form that contains any contents of the Program. Modified Works shall not include works that contain only declarations, interfaces, types, classes, structures, or files of the Program solely in each case in order to link to, bind by name, or subclass the Program or Modified Works thereof.

“Distribute” means the acts of a) distributing or b) making available in any manner that enables the transfer of a copy.

“Source Code” means the form of a Program preferred for making modifications, including but not limited to software source code, documentation source, and configuration files.

“Secondary License” means either the GNU General Public License, Version 2.0, or any later versions of that license, including any exceptions or additional permissions as identified by the initial Contributor.

2. Grant of Rights a) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, Distribute and sublicense the Contribution of such Contributor, if any, and such Derivative Works.

b) Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, worldwide, royalty-free patent license under Licensed Patents to make, use, sell, offer to sell, import and otherwise transfer the Contribution of such Contributor, if any, in Source Code or other form. This patent license shall apply to the combination of the Contribution and the Program if, at the time the Contribution is added by the Contributor, such addition of the Contribution causes such combination to be covered by the Licensed Patents. The patent license shall not apply to any other combinations which include the Contribution. No hardware per se is licensed hereunder.

c) Recipient understands that although each Contributor grants the licenses to its Contributions set forth herein, no assurances are provided by any Contributor that the Program does not infringe the patent or other intellectual property rights of any other entity. Each Contributor disclaims any liability to Recipient for claims brought by any other entity based on infringement of intellectual property rights or otherwise. As a condition to exercising the rights and licenses granted hereunder, each Recipient hereby assumes sole responsibility to secure any other intellectual property rights needed, if any. For example, if a third party patent license is required to allow Recipient to Distribute the Program, it is Recipient's responsibility to acquire that license before distributing the Program.

d) Each Contributor represents that to its knowledge it has sufficient copyright rights in its Contribution, if any, to grant the copyright license set forth in this Agreement.

e) Notwithstanding the terms of any Secondary License, no Contributor makes additional grants to any Recipient (other than those set forth in this Agreement) as a result of such Recipient's receipt of the Program under the terms of a Secondary License (if permitted under the terms of Section 3).

3. Requirements 3.1 If a Contributor Distributes the Program in any form, then:

a) the Program must also be made available as Source Code, in accordance with section 3.2, and the Contributor must accompany the Program with a statement that the Source Code for the Program is available under this Agreement, and informs Recipients how to obtain it in a reasonable manner on or through a medium customarily used for software exchange; and

b) the Contributor may Distribute the Program under a license different than this Agreement, provided that such license:

i) effectively disclaims on behalf of all other Contributors all warranties and conditions, express and implied, including warranties or conditions of title and non-infringement, and implied warranties or conditions of merchantability and fitness for a particular purpose; ii) effectively excludes on behalf of all other Contributors all liability for damages, including direct, indirect, special, incidental and consequential damages, such as lost profits; iii) does not attempt to limit or alter the recipients' rights in the Source Code under section 3.2; and iv) requires any subsequent distribution of the Program by any party to be under a license that satisfies the requirements of this section 3. 3.2 When the Program is Distributed as Source Code:

a) it must be made available under this Agreement, or if the Program (i) is combined with other material in a separate file or files made available under a Secondary License, and (ii) the initial Contributor attached to the Source Code the notice described in Exhibit A of this Agreement, then the Program may be made available under the terms of such Secondary Licenses, and b) a copy of this Agreement must be included with each copy of the Program. 3.3 Contributors may not remove or alter any copyright, patent, trademark, attribution notices, disclaimers of warranty, or limitations of liability (“notices”) contained within the Program from any copy of the Program which they Distribute, provided that Contributors may add their own appropriate notices.

4. Commercial Distribution Commercial distributors of software may accept certain responsibilities with respect to end users, business partners and the like. While this license is intended to facilitate the commercial use of the Program, the Contributor who includes the Program in a commercial product offering should do so in a manner which does not create potential liability for other Contributors. Therefore, if a Contributor includes the Program in a commercial product offering, such Contributor (“Commercial Contributor”) hereby agrees to defend and indemnify every other Contributor (“Indemnified Contributor”) against any losses, damages and costs (collectively “Losses”) arising from claims, lawsuits and other legal actions brought by a third party against the Indemnified Contributor to the extent caused by the acts or omissions of such Commercial Contributor in connection with its distribution of the Program in a commercial product offering. The obligations in this section do not apply to any claims or Losses relating to any actual or alleged intellectual property infringement. In order to qualify, an Indemnified Contributor must: a) promptly notify the Commercial Contributor in writing of such claim, and b) allow the Commercial Contributor to control, and cooperate with the Commercial Contributor in, the defense and any related settlement negotiations. The Indemnified Contributor may participate in any such claim at its own expense.

For example, a Contributor might include the Program in a commercial product offering, Product X. That Contributor is then a Commercial Contributor. If that Commercial Contributor then makes performance claims, or offers warranties related to Product X, those performance claims and warranties are such Commercial Contributor's responsibility alone. Under this section, the Commercial Contributor would have to defend claims against the other Contributors related to those performance claims and warranties, and if a court requires any other Contributor to pay any damages as a result, the Commercial Contributor must pay those damages.

5. No Warranty EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE PROGRAM IS PROVIDED ON AN “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the appropriateness of using and distributing the Program and assumes all risks associated with its exercise of rights under this Agreement, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and unavailability or interruption of operations.

6. Disclaimer of Liability EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT PERMITTED BY APPLICABLE LAW, NEITHER RECIPIENT NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

7. General If any provision of this Agreement is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this Agreement, and without further action by the parties hereto, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.

If Recipient institutes patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Program itself (excluding combinations of the Program with other software or hardware) infringes such Recipient's patent(s), then such Recipient's rights granted under Section 2(b) shall terminate as of the date such litigation is filed.

All Recipient's rights under this Agreement shall terminate if it fails to comply with any of the material terms or conditions of this Agreement and does not cure such failure in a reasonable period of time after becoming aware of such noncompliance. If all Recipient's rights under this Agreement terminate, Recipient agrees to cease use and distribution of the Program as soon as reasonably practicable. However, Recipient's obligations under this Agreement and any licenses granted by Recipient relating to the Program shall continue and survive.

Everyone is permitted to copy and distribute copies of this Agreement, but in order to avoid inconsistency the Agreement is copyrighted and may only be modified in the following manner. The Agreement Steward reserves the right to publish new versions (including revisions) of this Agreement from time to time. No one other than the Agreement Steward has the right to modify this Agreement. The Eclipse Foundation is the initial Agreement Steward. The Eclipse Foundation may assign the responsibility to serve as the Agreement Steward to a suitable separate entity. Each new version of the Agreement will be given a distinguishing version number. The Program (including Contributions) may always be Distributed subject to the version of the Agreement under which it was received. In addition, after a new version of the Agreement is published, Contributor may elect to Distribute the Program (including its Contributions) under the new version.

Except as expressly stated in Sections 2(a) and 2(b) above, Recipient receives no rights or licenses to the intellectual property of any Contributor under this Agreement, whether expressly, by implication, estoppel or otherwise. All rights in the Program not expressly granted under this Agreement are reserved. Nothing in this Agreement is intended to be enforceable by any entity that is not a Contributor or Recipient. No third-party beneficiary rights are created under this Agreement.

Exhibit A - Form of Secondary Licenses Notice “This Source Code may also be made available under the following Secondary Licenses when the conditions for such availability set forth in the Eclipse Public License, v. 2.0 are satisfied: {name license(s), version(s), and exceptions or additional permissions here}.”

Simply including a copy of this Agreement, including this Exhibit A is not sufficient to license the Source Code under Secondary Licenses.

If it is not possible or desirable to put the notice in a particular file, then You may include the notice in a location (such as a LICENSE file in a relevant directory) where a recipient would be likely to look for such a notice.

You may add additional accurate notices of copyright ownership.

Acknowledgments

This is a simple user guide for a tiny piece of software. But I have used other people's art and applications to create RPNCalc and I want to ensure I recognize them and give them thanks.

Libraries

Extensive use of several libraries were used in RPNCalc. I'd like to publicly thank the authors and give them credit for their hard work. The licenses for these libraries is detailed in the Licenses chapter.

• JCommander is used to parse the command line for options and parameters

• jAnsi allows for colorized output in the consoles

• jUnit5 is used for automated unit testing

• Maven build tool is used extensively in RPNCalc

• OpenJDK is the engine that runs Java on my systems. You may be running another Java Development Kit (JDK) or Java Runtime Environment (JRE)

Graphics

I'd like to give recognition and attribution to the authors of the icons used in this guide.

• Configure: Easy installation icons created by Freepik - Flaticon

• High Level Usage: Calculator icons created by srip - Flaticon

• Stacks: Maguro icons created by Kanyanee Watanajitkasem - Flaticon

• Operands: Calculator icons created by Freepik - Flaticon

• Install: Save file icons created by Tanah Basah - Flaticon

• Calculator Commands: Maths icons created by Freepik - Flaticon

• Conversion: Data transfer icons created by Freepik - Flaticon

• Trigonometry Functions: Trigonometry icons created by Freepik - Flaticon

• Memory: Memory icons created by Victoruler - Flaticon

• Constants: Pi icons created by Freepik - Flaticon

• User Defined Functions: Path icons created by Freepik - Flaticon

• Acknowledgment: Agreement icons created by Freepik - Flaticon

• Other icons were sourced from IconFinder and were licensed via the Creative Commons License

mdBook

This book was generated using mdBook. mdBook is a utility to create modern online books from Markdown files and it is fantastic. If you need to do something like this, mdBook is where you shoud look first in my humble opinion.