Introduction

This project came from a need for a quick calculator application that is not as basic as a typical 1-line calculator, but not as complex as a full Scilab or Matlab console. This would be an application where it is possible to deal with long multi-step formulas concisely, and which would not require long start-up times or large installation files or a lot of screen space. There should be minimal visual clutter and calculations should be entered step by step to match the mental layout of the formula, allowing to enter and store numeric values so they do not have to be held in mind for long. The syntax itself should be terse so mental effort is not wasted on unnecessary keystrokes or editing of entries. Many of these ideals are seen in the APL-like (tacit) and stack-based programming languages, from which the syntax used here is inspired. Unlike APL / Dyalog, the MCalc input does not use anything other than standard ASCII characters, so it can run in a console window. The use of a console is also inspired by Zoesoft's Console Calculator, a great program with similar goals which also gave me incentive to implement unit conversion for MCalc.

The overall concept is as follows: the calculator is equipped with a stack, where all values are stored. Entries are added to the stack one line at a time, and a line contains one numeric value which is either manually entered or the result of a computation. Values must be entered in the stack before a computation is called, so instead of "5+7" one enters [5] [7] [+](12) resulting in 3 lines added to the stack where the 3rd line is the result of the summation. The most recent entries in the stack are referenced implicitly, and other than most recent ones may be referenced usually by a single character. This may seem clunky, however it has some unique advantages:

• Any number in the computation is clearly visible on its own line and may be referenced later on without having to re-type it or clicking and dragging the cursor to make a selection in a past entry. This is helpful because often at the beginning of a calculation I don't know whether or not a number will be useful later on, but it remains individually accessible by reference in case it turns out to be.
• Any entry may contain a comment to help clarify its meaning. This allows the stack to serve as a visual notepad or log book, to effectively transfer information from memory or from another document into the stack so a computation may be set up. This is helpful when carrying out experimental measurements, holding the result in mind, and typing it in the computer, as it is possible to think about one entry at a time without worrying about the rest of the formula.
• There is no need for parentheses to define the order of operations; if an operation on an output is desired, there is no need to move the cursor back and forth on a line of text to insert opening and closing parentheses. Often when typing a formula in an expression-based environment I realize half-way through that what I recently typed should now be enclosed in parentheses, which requires the annoying aforementioned editing, and this is entirely avoided with the MCalc syntax.
• Many times there is no need to specify references as they are implicit, which makes it easier and cleaner to type commands. When references are needed, they are usually a single letter or digit, and there is no need for commas to separate references, again improving typing efficiency. Special reference symbols, such as iterators and context-based references, further optimize the process.
• Multiple-output commands may be implemented by simply adding multiple result entries to the stack. This allows the calculator to work with vectors and allows the concise definition of commands which are time-consuming (and annoying to mental clarity) to carry out one step at a time, such as division with a remainder, two roots of a quadratic equation, or sum and difference of two values.
• A new computation may be defined by changing one of the referenced values, enabled by the hypothetical evaluation command. There is no visual clutter of repeating the formula structure or unmodified entries, and all results are clearly delineated. Many times when doing engineering calculations in an expression-based environment, I would look to run the same formula with slightly changed values. This would require scrolling through a list of past entries to find the formula, then manually moving the cursor back and forth and carefully pressing backspace to erase an old number before typing in a new number, possibly repeating this multiple times, then evaluating the new expression (possibly in turn repeating this if I had chained multiple expressions together using "ans"). Of course this could have been done using variables, but with these experimental calculations, one is usually not sure at the beginning what sort of change one would make at the end.

A screenshot of the MCalc console window with entries to solve the equation x^2+8*x+15=0 using the quadratic formula (-B+-sqrt(B^2-4*A*C))/(2*A). The first 3 lines are the coefficients (A,B,C)=(1,8,15) and the last 2 lines are the results x=(-3,-5). The leftmost column is the absolute reference letter for each entry, the next column is the typed text, followed by the numeric result and the comment. Each entry is followed by comments for clarity and the comments show up twice (on the left as typed, and on the right as parsed).

In principle, many of these things could be done in a spreadsheet application such as Excel, which also allows referencing of other cells. The difference here is a terse syntax and a lean layout requiring minimal typing or editing of previously typed values (and no need to use a mouse), an implicit referencing system which can minimize or eliminate the need to type references, and the hypothetical evaluation command which can effectively make a function out of anything entered in the stack with no foresight required as to which variables are expected to be useful later on. This is in addition to MCalc being fast to load and having low resource requirements (though it is implemented in the .NET framework (for ease of programming in C#) and not bare bones C++ speed). To extend the calculator's functionality, custom commands and unit conversions may be defined using a simple text editor.

Syntax Guide

When examples are provided in this guide, text to type in MCalc appears inside square brackets [] and numeric results appear in parentheses (). Both square brackets and parentheses are not used inside MCalc. For instance to evalue 3+7 one enters [3](3) [7](7) [+](10), with the Enter key pressed after each bracketed entry to evaluate the input string and add it to the stack. Since numeric entries evaluate as themselves, this will be shortened as [3] [7] [+](10).

After starting MCalc, a console window opens with text entry on the first line. Use the keyboard to enter an input, then press enter to add the input to the stack. The stack starts at the visual top of the console and grows downwards. Once added to the stack, an entry cannot be modified, and it can be referenced by future commands. The entry may be a numeric value (such as [1.23e5]) or a command (such as [+]), and these may be followed by a space and comment (such as [1.23 m radius] or [+ adding sides for circumference]). An entry may also be a comment by itself (such as [ next equation]), which will show up as a line in the stack in the same manner as a numeric value. Since the stack may be referenced at any point, there are no commands to swap, rotate, or delete (other than the final) stack elements. Each command can only add new values to the stack and cannot change previous ones. Commands can only reference values already in the stack. Values cannot be entered on the same line as a command, and only one command may be entered per line. Commands may explicitly reference entries in the stack, or in the absence of that, will implicitly reference the immediately preceding entries. Absolute address references are capital letters A-Z. The entries precede a command statement, so two numbers stored as Z and Y are summed by the expression [ZY+]. The summation command takes 2 or more arguments, so [+] will sum the previous 2 entries in the stack, [Z+] will sum the previous entry with Z, [ZY+] will sum Z with Y, [ZYX+] will sum Z with Y with X.

Numeric entries

A number causes the entered value to be parsed and stored in the stack (as 64-bit floating point), with an optional comment. Examples: [7] [1.9 L] [.5] [-2] [3e6] [+5E+5]

References

Items in the stack may be referenced by an absolute address which starts at Z and on down to C,B,AZ,AY..AB,AAZ,AAY (each 'A' serves as an extending character, as otherwise the reference is assumed to end with 1 character). This address does not change as the stack grows, and for convenience is shown at the beginning of each line. Items may also be referenced by their relative position to the current line. These references are digits 1-9 where 1 is the previous item, 2 is the previous-1 item, and on to 9,01,02..09,001,002 (each '0' again serves as an extending character). Examples: [21+] sums the previous 2 entries and is equivalent to [+] which is implicitly completed. [YZ/] divides Y by Z (that is, Y/Z) while [ZY/] is the opposite (Z/Y), and may be read as transposing the division sign left one character to place it between the references. [/] is equivalent to [21/] and evaluates as the 2nd to last entry divided by the last entry (2/1), while [2/] expands into [12/] and evaluates as (1/2) because implicit references are prepended to the expression. Similarly, [ZY/] expands as (Z/Y) while [Z/] expands as [1Z/] which is (1/Z).

Each command has a minimum and a maximum number of arguments. It will take up to the minimum number of arguments from the end of the stack implicitly, while supplying more arguments than the minimum requires all of them to be entered individually. Special reference characters simplify this task.

• A range of adjacent entries may be specified by using underscore between references; [Z_V] expands into [ZYXWV]. Example: [Z_V+] is evaluated as (Z+Y+X+W+V).
• [#] refers to the most recent numeric value that has been typed in (is not the output of a command). Example: [1] [4] [+](5) [*](20) [#/](5)
• [$] refers to the oldest numeric value that has been typed in (is not the output of a command) in a continuous region preceding [#]. Example: [1] [4] [+](5) [$#-](-3)
• [!] refers to the most recent command result. In case of multiple-output commands, this is the last output line. Example: [1] [4] [+](5) [15] [!/](3)
• [:] refers to all the lines of the most recent multiple-output command result.
• ["] copies the references of the previous command (if references were relative originally, they do not change for the new command but refer to the same elements; if previous command used iterators, only the last iteration is copied). Example: [1] [4] [+](5) ["-](-3)

Iterators

It is possible to produce multiple outputs by using iterators. An iterator causes the same command to be evaluated multiple times with different arguments. An iterator contains a list of references in curly brackets [{XYZ}], and executes the command once for each reference from left to right. For instance to evaluate 7-1 and 7-5 in one line, [1] [5] [7] [{32}-](6)(2). An iterator takes place of one argument for a command. Multiple iterators may be used if they all contain the same number of references, and they will be scanned through concurrently. For instance to evaluate 1-5 and 5-7 in one line, [1] [5] [7] [{32}{21}-](-4)(-2). There are also special reference symbols for iterators.

• [{}] duplicates all the output lines of the most recent iterator as an iterator.
• [&] refers to all the output lines of the most recent iterator as a range.

Commands

A command causes an action to be carried out and the result(s) written to the bottom of the stack. Commands will get data from the most recent entries in the stack unless preceded by manually specified stack references. Numeric values for the command may not be entered on the same line as a command; rather the values should first be entered into the stack and then be referenced when entering the command. Command words start by a sequence of special characters (such as [+] or [-']) or lower case letters (such as [sqrt] or [s]) and are preceded by a list of references and followed by an optional comment (after a space). Multiple arguments are passed by concatenating references, where different valid characters from above may be mixed, such as [XYZ] or [#$] or [5RV]. The order of arguments, read from left to right, is passed to the commands, so [VR-] is different from [RV-].

Some commands produce multiple numeric outputs. In this case, the command is typed once and appends more than one entry to the stack, with each entry carrying one of the numeric outputs. The multiple outputs are from then on treated as independent entries, following the same referencing rules as if they were added one at a time. For example the [/%] command returns an integer divisor and a remainder, and may be used as [23] [5] [/%](4)(3).

Command List

Non-numeric commands

cs

Clear the stack

b

Backspace; remove the previous stack entry. An empty input line will also act as a backspace command. Optionally supply 1 argument to remove the stack entries to the specified one (inclusive).

export

Export the stack as a text file. Must be followed by a space then the path to the file and no other comment text.

esc

Exit MCalc.

rs

Renumber stack absolute references to re-start from Z following this entry. Any command after this cannot refer to the stack above rs by absolute reference. Relative references work as usual. Optionally supply 1 argument to renumber stack absolute references so that the specified entry is considered Z from now on.

Math commands with single output

Math commands with multiple outputs

Hypothetical evaluation command

[@] re-evaluates the stack with modified input values. Unlike all other commands which only have arguments to the left of the command word, this command requires at least 2 arguments to the right of the @ symbol, and the number of arguments determines how many entries are hypothetically modified in the stack. The last entry on the right is what is evaluated, while all preceding entries are modified as filled from references prepended to the command in the standard manner. For instance:

[@HJ]

Evaluate what J would be if the value in H were replaced by the previous stack entry.

[@HJK]

Evaluate what K would be if the value in J were replaced by the previous stack entry, and the value in H by the previous-1 entry.

[IG@HJK]

Evaluate what K would be if the value in J were replaced by G, and the value in H by I.

Example: [3] [8] [+](11) [9] [@4!](17) evaluates 3+8 and also 9+8. Repeated @ commands are evaluated as chained, and changes accumulate. The referenced command runs at its original stack location (relative references still point to the same values as originally). A referenced line within a multiline result will return only the specified line (use an iterator on the right-most output argument to include all lines).

Unit conversion command

[conv] may be used to convert measurement units. It is special because it parses the entry comment to determine the conversion. The 1-argument command is followed by a space, the original unit, another space, the desired unit, and optionally another space and a remaining comment. Example: [2] [conv m^2 ft^2](21.528) converts 2 square meters into square feet. Input and output units should be entered as a string without spaces containing letters, exponents, and multiplication or division signs such as m/s^2 or N*m. The division symbol applies only to the immediate next unit, so m/s^2*kg is equivalent to m*kg/s^2 or m*kg*s^-2.

Included external commands

Development commands

reload

Reload external commands and units that have been parsed in this session.

listcmds

Export a list of the math commands as a text file. Must be followed by a space then the path to the file and no other comment text.

Extending MCalc Functionality

Adding measurement units

Custom units may be defined. A non-comprehensive list of units is specified in a text file "units_list.txt" in the MCalc executable directory. The file is not parsed until [conv] is called for the first time in a session. Use [reload] when actively modifying the units list to avoid restarting MCalc. The units must be defined in groups relating to base units. A base unit is defined as equal to one of itself, such as "m=1 m" to specify the meter as a base unit. Other units are defined with reference to base units, such as "ft=0.3048 m", where an implied "1" is to the left of the expression, that is 1 ft = 0.3048 m. Note that all prefixes must be defined explicitly, such as "cm=0.01 m" or "km=1000 m". Each line in the "units_list.txt" file may start with a space to contain a comment, or with a letter (a-z or A-Z) to define a unit name (case-sensitive). The unit name must not have any powers (exponents) attached. Exponents are calculated automatically, so defining "m" will carry over to "m^2" and others. The unit name must be followed by "=" and a numeric value (corresponding to 1 of the new unit), then one space " " and a defining unit name. For instance to represent 1 week is 7 days, the entry would be "week=7 day". Defining units must reduce to base units for the conversion to be successful. Look through the existing entries in the file to gain a better understanding.

Writing external commands

Custom external commands may be defined. They operate in the same stack-based manner as the console, and constitute an isolated "sandbox stack" where inputs are read in from the main stack, the computation is carried out, and results are taken back into the main stack. Commands should be stored as *.txt files in ./extcmds directory relative to the MCalc executable. Valid names must start with a lowercase letter a-z and may contain digits 0-9 later, no other characters are allowed. The files are enumerated on MCalc startup but not parsed until individual commands are called. Use [reload] when actively modifying the external commands to avoid restarting MCalc. Look through the included examples in the extcmds folder to gain a better understanding. An external command must have a fixed number of inputs and outputs. Some features are not available in external commands:

• No iterators {}
• No hypothetical evaluation [@]
• No meta commands [cs] [b] [esc] and similar
• No unit conversion [conv]

External commands have their own stack which starts with Z as the first line. The first line comment may be used to provide a description of the command. Multiline commands called from the file must be followed by a matching number of blank or comment lines " :" which will be filled with return values when the script runs and may be referenced from that point on. Inputs are read with the command [in], and outputs are written with the command [out]. The entire script is parsed to find the number of inputs, and these inputs are read from the main stack such that the last [in] corresponds to the last value on the stack. Similarly the first [out] is the first value that will be added to the main stack. The [in] command does not support any arguments and reads in exactly one value at the line it appears. The [out] command may have arguments, in the absence of arguments it will return the previous entry in the external stack and it duplicates the last value as its own output. Example:

 convert rectangular to polar coordinates (with comments)
 using expression syntax this is R=norm(X,Y);theta=atan2(Y,X);return (R,theta);
in Read X
in Read Y
norm Find R
out Output R
WXat Find theta
out Output theta

Code and Executable

The C# code files for the project may be downloaded here. The compiled executable (for Windows .NET framework 7.0) with units list and external command examples may be downloaded here.

Conclusion

The MCalc console calculator has successfully met the design criteria. While it has taken me a few days to become used to the line-by-line data entry method, I now miss having that ability when I must use a regular calculator app on a computer without MCalc installed. The unit conversions are functional and new unit definitions can be easily added. The external commands provide a way to implement "convenience functions" which are not mathematically sophisticated but which save time and mental effort when doing a calculation, such as the included [rc] to solve for the RC filter cutoff frequency 1/(2*pi*R*C). The ability to have multiple outputs further enhances the convenience aspect. This allows MCalc to fill a niche not well covered by other computational software. Overall I would consider MCalc a success, and I use it regularly on every computer where I have an account.