cmp-rpncalc

Overview

This plugin is a processor that takes a Reverse Polish Notation expression as input and inserts the results in the current buffer. It operates in two different ways.

1. As a completion source for the nvim-cmp completion plugin

If nvim-cmp is installed, then while an RPN expression is being typed, two completion options will be presented. For example, when typing:

1 2 3 ** +

nvim-cmp will present these two strings that can be insert in the expression's place:

9
1 2 3 ** + == 9

2. As a standalone processor, using the :RPN command

This is the only method that works when nvim-cmp is not installed. The :RPN command's various syntaxes are as follows:

• :RPN - replace the current line's RPN expression with its result. The entire line will be treated as the RPN expression. Any text that is not a valid number or operator will cause an error.

• :<range>RPN - replace the selected lines with the result of their concatenated RPN expression. The selection will always be treated as a linewise selection. The entire concatenation will be treated as the RPN expression. Any text that is not a valid number or operator will cause an error.

• :RPN <expression> - treat all arguments as an RPN expression and insert the result in a new line above the current line.

Adding the bang operator, ie. :RPN!, to any of the syntaxes above will cause the expression to be inserted along with the result, like so:

30 rad sin == 0.5

Use mappings like the following examples to call :RPN in Normal or Visual mode.

" Vimscript example
nnoremap <F7>   :RPN<CR>
nnoremap <S-F7> :RPN!<CR>
xnoremap <F7>   :<C-U>'<,'>RPN<CR>
xnoremap <S-F7> :<C-U>'<,'>RPN!<CR>

-- Lua example
vim.api.nvim_set_keymap("n", "<F7>",   ":RPN<CR>",            {noremap=true})
vim.api.nvim_set_keymap("n", "<S-F7>", ":RPN!<CR>",           {noremap=true})
vim.api.nvim_set_keymap("x", "<F7>",   ":<C-U>'<,'>RPN<CR>",  {noremap=true})
vim.api.nvim_set_keymap("x", "<S-F7>", ":<C-U>'<,'>RPN!<CR>", {noremap=true})

Installation

Use your favorite plugin manager. If you don't have one, try one of these: vim-pathogen, vim-plug, Packer.nvim or lazy.nvim. Alternatively, you can use packages and submodules, as Greg Hurrell (@wincent) describes in his excellent Youtube video: Vim screencast #75: Plugin managers

Setup

There is no setup required specifically for this plugin; however, when using it as a source for nvim-cmp, you need to add rpncalc to its list of sources in your nvim-cmp setup function call. The following snippet shows how to do that.

require'cmp'.setup {
  sources = {
    { name = 'rpncalc' }   -- Add this to the sources list.
  }
}

How Does RPN Work?

RPN is a mathematical notation in which an operator follows its operand(s). This means there is no need for parentheses. Here are some examples, comparing algebraic notation to RPN.

Algebraic	This plugin's version of RPN
$73 + 37=110$	73 37 +
$462\div11=42$	462 11 /
$\lvert((1+2)-(3\times4))^5\rvert=59049$	1 2 + 3 4 * - 5 ** abs
$\tan^{-1}(\frac{1}{\sqrt{3}})=30^\circ$	1 3 sqrt / atan deg or 3 sqrt \ atan deg
For $t=\frac{\sqrt{7}}{4}$, $48t^2-\frac{98}{t^4}=-491$	7 sqrt 4 / sto 2 ** 48 * 98 rcl 4 ** / -
Euler's Identity: $e^{i\pi}+1=0$	e i pi * ** 1 + Round-off error gives an answer that's almost exact: $0+1.2246467991474*10^{-16}i$

An RPN expression is a space-delimited list of tokens. Reading the tokens from left to right, numbers are placed on a stack. The top four numbers are labeled $X$, $Y$, $Z$, and $T$ from the top down. These labels are not shown when using the plugin, but they are referenced in the README and the documentation. When an operator is encountered, one or more numbers (as needed by the operator) are popped from the stack, and the result of the operation is pushed back onto the stack. 3.6739403974421e-16+6i

Example

Expression: 12 2 -3 ** +
Tokens: 12 2 -3 ** +

Token	Stack Before	Stack After Pop	Calculation	Stack After Push
12	empty	n/a	n/a	$X:12$
2	$X:12$	n/a	n/a	$X:2$ $Y:12$
-3	$X:2$ $Y:12$	n/a	n/a	$X:-3$ $Y:2$ $Z:12$
**	$X:-3$ $Y:2$ $Z:12$	$X:12$	$y^x=2^{-3}=0.125$	$X:0.125$ $Y:12$
+	$X:0.125$ $Y:12$	empty	$x+y=0.125+12=12.125$	$X:12$.125

Operands

Operands can take on any of these forms:

• Decimal (base 10): integer 42, float -3.14, or scientific notation 6.02e23
• Binary (base 2): 0b prefix, followed by digits 0 and 1.
• Hexadecimal (base 16): 0x prefix, followed by digits 0-9 or letters a-f or A-F.
• Complex: an ordered pair of numbers in any of the prior formats. For example,
  1.2e-4,0x43 equates to 0.00012+67i in decimal notation.

Complex Numbers

Most of the operators will work on complex numbers. The following Wikipedia pages were used as reference for some of the more arcane complex number calculations: logarithms, exponentiation, ordinary trig functions, inverse trig functions, hyperbolic trig functions, inverse hyperbolic trig functions. Where the complete answer is an infinte number of values, only the principal value is given.

Operators

The Domain column in the following table indicates the types of numbers that are valid for each operator. The possible domains are:

• ℕatural - non-negative integers
• ℝeal - real numbers (includes ℕatural)
• ℂomplex - complex numbers (includes ℝeal and ℕatural)

Operator	Function	Domain
	Basic Arithmetic
+	Addition	ℂomplex
-	Subtraction	ℂomplex
*	Multiplication	ℂomplex
/	Division	ℂomplex
div	Integer division	ℂomplex
%	Modulus (not well-defined for negatives)	ℝeal
abs	Absolute value	ℂomplex
arg	Argument (the angle between $X$ and the positive real axis)	ℂomplex
chs	Change Sign (negation)	ℂomplex
	Powers & Logs
**	Raise $Y$ to the $X$ power	ℂomplex
\	Reciprocal	ℂomplex
exp	Raise e to the $X$ power	ℂomplex
ln	Natural Log of $X$	ℂomplex
log	Log (base 10) of $X$	ℂomplex
log2	Log (base 2) of $X$	ℂomplex
sqrt	Square Root	ℂomplex
	Trigonometry Variations are: a... for inverse and ...h for hyperbolic
sin	Sine, asin, sinh, asinh	ℂomplex
cos	Cosine, acos, cosh, acosh	ℂomplex
tan	Tangent, atan, tanh, atanh	ℂomplex
csc	Cosecant, acsc, csch, acsch	ℂomplex
sec	Secant, asec, sech, asech	ℂomplex
cot	Cotangent, acot, coth, acoth	ℂomplex
	Rounding
floor	Round down to nearest integer	ℂomplex
ceil	Round up to nearest integer	ℂomplex
round	Round up or down to nearest integer	ℂomplex
trunc	Round toward zero to nearest integer	ℂomplex
	Bitwise Non-integer operands will be truncated.
&	AND     $0b1100\text{ AND }0b1010=0b1000$     $12\text{ AND }10=8$	ℕatural
|	OR     $0b1100\text{ OR }0b1010=0b1110$     $12\text{ OR }10=14$	ℕatural
^	XOR     $0b1100\text{ XOR }0b1010=0b0110$     $12\text{ XOR }10=6$	ℕatural
~	NOT     $\text{NOT }0b1010=-0b1011$     $\text{NOT }10=-11$ All bits are flipped, and a two's complement conversion of the result is displayed. $58 = 0b00111010$ $\text{[NOT}\rightarrow\text{] } = 0b11000101$ $\text{[2's complement}\rightarrow\text{] } = -2^7+2^6+2^2+2^0=-128+64+4+1=-59$	ℕatural
<<	Left Shift ($Y$ shifted $X$ bits)     ${0b100\overleftarrow{01}}^{\text{ }2}=0b1000100$     $\overleftarrow{17}^2=68$	ℕatural
>>	Right Shift ($Y$ shifted $X$ bits)     ${0b110\overrightarrow{100}}^{\text{ }3}=0b110$     $\overrightarrow{52}^3=6$	ℕatural
	Statistics
!	Factorial of $X$     $X!=\prod_{i=1}^{X}{i}$	ℕatural
perm	Permutation of $Y$ things taken $X$ at a time     $_YP_X={\frac{Y!}{(Y-X)!}}$	ℕatural
comb	Combination of $Y$ things taken $X$ at a time     $_YC_X={\frac{Y!}{X!(Y-X)!}}$	ℕatural
n	Sample size (size of the stack)	ℂomplex
mean	Average of all numbers on the stack.     $\bar{x}={\frac{1}{n}}{\sum_{i=1}^n{x_i}}$	ℂomplex
sum	Sum of all numbers on the stack     $\sum_{i=1}^n{x_i}$	ℂomplex
ssq	Sum of squares of all numbers on the stack     $\sum_{i=1}^n{x_i}^2$	ℂomplex
std	Sample standard deviation of all numbers on the stack     $s=\sqrt{\frac{{\sum_{i=1}^{n}(x_i-\bar{x})^2}}{n-1}}$	ℝeal
	Miscellaneous
hrs	Convert ($Z$ hours:$Y$ minutes:$X$ seconds) to $X$ hours	ℝeal
hms	Convert $X$ hours to ($Z$ hours:$Y$ minutes:$X$ seconds)	ℝeal
gcd	Greatest Common Divisor of $X$ and $Y$	ℕatural
lcm	Least Common Multiple of $X$ and $Y$	ℕatural
dec	Print result in decimal (base 10)	ℂomplex
hex	Print result in hexadecimal (base 16) $^*$	ℂomplex
bin	Print result in binary (base 2) $^*$	ℂomplex
	$^*$ Non-integer values are truncated. Negatives are formatted as human readable: $-23=-0b10111=-0x17$ as opposed to $0b1...1111111111111111111111111101001$ or $0x\text{F...FFFFFE9}$
	Constants
pi	Ratio of a circle's circumference to its diameter     $\pi={3.1415926535898...}$	ℝeal
e	Euler's number     $e=\sum_{i=0}^\infty{\frac{1}{i!}}=2.7182818284590...$	ℝeal
phi	The golden ratio     $\phi={\frac{\sqrt{5}+1}{2}}=1.6180339887499...$	ℝeal
i	The imaginary unit number     $i={\sqrt{-1}}$	ℂomplex
	Memory and Stack Manipulation
sto	Store the value of $X$ to memory	ℂomplex
rcl	Recall the value in memory to the stack	ℂomplex
m+	Add $X$ to the value in memory	ℂomplex
m-	Subtract $X$ from the value in memory	ℂomplex
xy	Swap $X$ and $Y$ on the stack	ℂomplex
x	Place the value of $X$ from the last operation back on the stack	ℂomplex
drop	Remove $X$ from the stack	ℂomplex

Disclaimer ⚠

The author of this plugin makes no warranties about the completeness, reliability or accuracy of this calculator. Any action you take upon the results you get from it is strictly at your own risk. The author will not be liable for any losses and/or damages in connection with the use of this calculator.

Feedback 📣

This was mainly an exercise to learn lua, and to write a Neovim plugin by porting my prior Ruby and Erlang rpn calculators. It's quite possible that computational errors made their way in, despite all efforts to ensure the plugin's accuracy. If you spot any errors, or have suggestions for improvements, new operators, etc., create an issue or a pull request.

Finally, I don't know how useful some of the complex number functions are. It was a fun exercise implementing them, but was it just that - an exercise? Leave a comment if you know of any real-world use (pun intended) for perhaps, the inverse hyperbolic cotangent of a complex number.