XRPN Documentation

Welcome to the XRPN wiki :)

Here is the documentation for the programming language.

First off: XRPN is a superset of FOCAL (Forty One CALculator Language). The bulk of the documentation is found in the user manuals for the HP-41CX calculator (Vol 1 & Vol 2).

XRPN accepts both the original HP-41 command and also the XRPN format. Since XRPN has a limit on certain characters used in the commands, the system internally converts some of the HP-41 commands to the XRPN equivalent. While the internal functions/commands in XRPN are lower case, you are free to write them in UPPER, lower or CaMeL case as you wish.

Synopsis:

Usage: xrpn [options]
    -e, --execute string             Interpret string as program and run
    -f, --file program               Specify the file to process
    -l, --load program(s)            File(s) to load, but not run
    -s, --state STATE                Load a State file
    -c, --check program              Program file to check for errors
    -x, --X X-value                  Set initial value in the X register
    -y, --Y Y-value                  Set initial value in the Y register
    -z, --Z Z-value                  Set initial value in the Z register
    -t, --T T-value                  Set initial value in the T register
    -a, --Alpha Alpha-string         Set initial string in Alpha
    -h                               Display SHORT help text
        --help                       Display LONG help text
    -v, --version                    Display the XRPN version number

A program can be run by supplying a program file (option -f), by supplying a string with commands separated by commas (option -e) or by starting xrpn without any options and keying in the program manually.

Using the -eoption, you could do e.g. xrpn -e "43, sin, 1/x, prx".

You can also pipe a string into xrpn like this: echo "1,2,+,4,*,prx" | xrpn.

When you load a program, comments are removed. A comment starts with a TAB, then a semicolon and a space and then whatever, like: 005 SEEKPTA ; This is a comment (pretending that the two spaces in front of the semicolon is actualy a TAB character (\t).

You can use any name for registers or flags (e.g. STO "MYREG" or SF "MyFlag" is perfectly fine). Any register or flag value from 0 to 9 will be converted to "00" to "09" for backward compatibility with the HP-41 system.

Indirect adressing is implemented. Any command that can sanely be used with "IND" will handle the indirection (e.g. SF IND 01, XEQ IND X or GTO IND "TEST").

XRPN works with Pages to accommodate for sets of programs. When you load a new program with GETP, a new Page is created for that program. You can delete a program with CLP (CLear Program) or by deleting that page with PAGEDEL. See the Pages commands below.

When the program halts (encountering a STOP command in the program) or when XRPN is started without any program file name (e.g. XRPN -f myprog.txt), XRPN enters a "debug mode". Pressing Enter will resume the program (as with pressing R/S on the HP-41). A single Enter will do nothing if no program was loaded with -f. The other debug commands are listed below. You can also manually enter any command using the HP-41 mnemonic or the XRPN counterpart (e.g. to swap X and Y, enter X<>Y or SWAP and press Enter). To enter a number, simply key in the number and press Enter. To enter a string into Alpha, enclose the string in single-quotes (or double-quotes) and press Enter (e.g. 'Hello World!' and Enter). To append characters to the Alpha register, start the string with a pipe (|) or a pipe and a minus (|-) as this mimics the "append character" of the HP-41. Example: If Alpha contains the string "Test" and you write '| Now' and press Enter, Alpha will then contain "Test Now".

Here is a list of possible commands when in debug mode:

Command	What it does
q	Quit XRPN without saving any settings in a configuration file
Q	Quit XRPN, saving your flags, registers and programs in ~/.xrpn/conf
S xxx	Save everything in a "state" file named xxx (no quoting for the xxx)
c	Clear the screen
C	Clear stack, flags, registers - and the screen
R	Reload all commands in ~/.xrpn/cmd
l	Show current program line
n	Show next program line
p	Show previous program line
S	Go to the next line without executing it
s	Execute next program line (as with SST on the HP-41)
b	Go back one program line (as with BST on the HP-41)
++ xxx	Insert line with content xxx
--	Delete current program line
> xxx	Save state to a file named xxx (in the .xrpn directory)
< xxx	Load state from a file named xxx (in the .xrpn directory)
(Enter)	A single Enter will act as an ENTER (lift the stack)
r	Terminates the debug mode and commences running the current program

Theming

The output to console is themable. The theme is set to work in a dark terminal by default. If you are using a light background in your terminal, add $theme = "light" in the .xrpn/conf file.

You can even make your own theme by copying .xrpn/theme_example to a new file .xrpn/theme and change the 256 color codes to suit your fancy. That new file will override the dark or light theme in the xlib folder (and disregard your setting in .xrpn/conf, whether it is $theme = "dark" or $theme = "light").

Functions that work just as they do on the HP-41 calculator

HP-41 command	XRPN command	Short explanation
ABS	abs	Return absolute value of X to X
ACOS	acos	Return Arc COS of X to X
ADATE	adate	Return a formatted date in X to Alpha
+	add	Return X + Y to X
ADV	adv	Add a line in the printout
ALENG	aleng	Return length of Alpha string to X
ANUM	anum	Return first number in Alpha to X
APPCHR	appchr	Append Alpha to current XM file at pointer
APPREC	apprec	Append Alpha as next record in XM file
ARCL	arcl	Recall content of register named to Alpha
ARCLREC	arclrec	Add to Alpha the next record in current XM file
AROT	arot	Rotate Alpha at character number given in X
ASHF	ashf	Remove the 6 left-most characters from Alpha
ASIN	asin	Return Arc SIN of X to X
ASTO n	asto	Store Alpha to named register
ATAN	atan	Return Arc TAN of X to X
ATIME	atime	Return a formatted time in X to Alpha
ATIME24	atime24	Return a formatted time (as 24h time) in X to Alpha
ATOX	atox	Return character code of first character in Alpha and remove that character
AVIEW	aview	Print out (show) content of Alpha register
BEEP	beep	Sound the legendary HP-41 BEEP
CF n	cf n	Clear named flag
CHS	chs	Swap sign of X (X becomes -X and -X becomes X)
CLA	cla	Clear Alpha register
CLFL	clfl	Clear content of XM file
CLK12	clk12	Make time into 12h format
CLK24	clk24	Make time into 24h format
CLP	clp	Clear named program
CLRG	clrg	Clear all registers
CLRGX n	clrgx n	Clear a specific number of registers
CLΣ	cls	Clear statistical data registers
CLST	clst	Clear the stack (but not L)
CLX	clx	Clear X
COS	cos	Return COS of X to X
DATE	date	Return the current date to X
DATEPLUS	dateplus	Add the date in Y and number of days in X and return result to X
DDATE	ddate	Return the number of days between dates in X and Y to X
DEC	dec	Return the Decimal value of the Octal value in X
DEG	deg	Set degree mode to "deg" (360 degrees in a circle)
DELCHR	delchr	Delete X characters from current XM file starting at pointer
DELREC	delrec	Delete current record from current XM file
/	divide	Divide Y by X
DMY	dmy	Set date mode to DD.MMYYYY
DOW	dow	Return Day Of Week for date in X
D-R	d_r	Degrees to Radians conversion
DSE n	dse n	Decrease, skip if greater using named register
EMDIR	emdir	Print data for all XM files (name and type and size)
EMDIRX	emdirx	Print X'th XM file (name and type and size)
END	end	End of program
ENTER	enter, lift	Lift stack
E^X	exp	Natural exponent
E^X+1	expx1	For arguments close to zero
FACT	fact	Return factorial of X to X
FC? n	fc? n	Flag clear? If not, skip next program line
FC?C n	fcc? n	Flag clear? If not, skip next program line and clear flag
FIX n	fix n	Fixed point display with n decimal places
FRC	frc	Return fractional part of X to X
FS? n	fs? n	Flag set? If not, skip next program line
FS?C n	fsc? n	Flag set? If not, skip next program line and clear flag
GETR	getr	Get all registers from XM data file and copy to registers
GETREC	getrec	Get current record from current XM file, replacing content of Alpha
GETRX	getrx	Get registers by X (bbb.eee)
GETX	getx	Get current record in XM data file to X
GRAD	grad	Set degree mode to GRAD (400 degrees in a circle)
HMS	hms	Convert decimal hours to HH.MMSSsss
HMSMINUS	hmsminus	Add hours (HH.MMSSsss) or degrees
HMSPLUS	hmsplus	Subtract hours (HH.MMSSsss) or degrees
HR	hr	Convert HMS to decimal hours
INSCHR	inschr	Insert Alpha at pointer in current XM file
INSREC	insrec	Insert Alpha before current record in XM file
INT	int	Return integer part of X to X
ISG n	isg n	Increase, skip if greader for named register
LASTX	lastx	Get content of Last X (L register) to X
LBL n	lbl n	Label in a program that you can GTO or XEQ to
LN	ln	Natural logarithm
LN1X	ln1x	For argumants close to 1
LOG	log	Logarithm with base 10
MDY	mdy	Set date mode to MM.DDYYYY
MEAN	mean	Statistical mean of X and Y values (to X and Y registers)
MOD	mod	Y modulo X
*	multiply	Multiply X and Y
OCT	oct	Convert decimal value in X to octal
PCLPS	pclps	Programmable Clear Programs (current and remaining programs)
%	percent	X percent Y
%CH	percentch	Percentage change from Y to X
PI	pi	Get PI to X
POSA	posa	Find position of string in X in the Alpha register
POSFL	posfl	Find position of string in Alpha in current XM file
Y^X	pow	Return Y to the power of X to X
P-R	p_r	Polar to rectangular conversion
PRA	pra	Print Alpha
PRP	prp, pprg	Print program
PRX	prx	Print X
PSE	pse	Pause program for one second
PURFL	purfl	Purge (remove) XM file
RAD	rad	Set degree mode to radians
RCL n	rcl n	Recall content of named register to X
RCLPT	rclpt	Recall the pointer for current XM file to X
RCLPTA	rclpta	Recall the pointer for XM file (named in ALpha) to X
R-D	r-d	Radians to degrees conversion
RDN	rdn	Roll down the stack
1/X	recip	Return 1/X to X
REGMOVE	regmove	Move registers
REGSWAP	regswap	Swap registers
RND	rnd	Round X to current FIX number of decimal places
R-P	r_p	Rectangular to polar conversion
RTN	rtn	Return program pointer to the last place in the return stack
RUP	rup	Roll up the stack
SAVEAS	saveas	Save XM file
SAVEP	savep	Save program
SAVER	saver	Save all registers to XM data file
SAVERX	saverx	Save a certain number of registers to XM data file
SAVEX	savex	Save X to the current XM data file record
SDEV	sdev	Standard deviation for X and Y to the X and Y registers
SEEKPT	seekpt	Set pointer of current XM file to X
SEEKPTA	seekpta	Set pointer of XM file named in Alpha to X
SF n	sf n	Set flag n
SIGN	sign	Get sign value of X to X
SIN	sin	Return SIN of X to X
Σ-	sminus	Delete data values from statistical accumulation
Σ+	splus	Add data values to statistical accumulation
X^2	sqr	Return square of X to X
SQRT	sqrt	Return square root of X to X
ΣREG n	sreg n	Set start of statistical registers to n
ΣREG?	sreg?	Return start of statistical registers to X
ST/ n	stdivide n	Store divide (divide the content of reg n by X in reg n)
ST* n	stmultiply n	Store multiply (multiply the content of reg n by X in reg n)
STO n	sto n	Store X in register n
STOP	stop	Halt program execution (and enter "Debug mode")
ST+ n	stplus n	Store plus (add X to the content of reg n in reg n)
ST- n	stsubtract n	Store subtract (subtract X from the content of reg n in reg n)
-	subtract	Subtract X from Y
TAN	tan	Return TAN of X to X
10^X	tenx	Return ten to the power of X to X
TIME	time	Return to X the current time
TONE	tone	Sound a tone (0-9)
VIEW n	view n	View (print) the content of register n
XEQ n	xeq n, gsb n	Jump to label n and return here after an RTN or END is encountered
X=0?	xeq0?	Conditional - if not true, skip next program line
X=NN?	xeqnn?	Conditional - if not true, skip next program line (reg NN in Y)
X=Y?	xeqy?	Conditional - if not true, skip next program line
X<>F	xf	X exchange flag status (flags 0-7)
X>0?	xgt0?	Conditional - if not true, skip next program line
X>=NN?	xgteqnn?	Conditional - if not true, skip next program line
X>NN?	xgtnn?	Conditional - if not true, skip next program line
X>Y?	xgty?	Conditional - if not true, skip next program line
X<0?	xlt0?	Conditional - if not true, skip next program line
X<=0?	xlteq0?	Conditional - if not true, skip next program line
X<=NN?	xlteqnn?	Conditional - if not true, skip next program line
X<=Y?	xlteqy?	Conditional - if not true, skip next program line
X<NN?	xltnn?	Conditional - if not true, skip next program line
X<Y?	xlty?	Conditional - if not true, skip next program line
X!=0?	xneq0?	Conditional - if not true, skip next program line
X!=NN?	xneqnn?	Conditional - if not true, skip next program line
X!=Y?	xneqy?	Conditional - if not true, skip next program line
X<>NN n	xnn?	Exchange X and content of register n
XTOA	xtoa	Add character from character code in X to Alpha
X<>Y	xy, swap	Swap X and Y

HP-41 commands that are NOT implemented

HP-41 command	Short explanation
ALMCAT	Alarm catalog (no alarm functions implemented)
ALMNOW	Fire alarm now (no alarm functions implemented)
AOFF	Alpha OFF (no need, just enclose all Alpha entries in double quotes)
AON	Alpha ON (no need, just enclose all Alpha entries in double quotes)
ASROOM	How much room is left in XM file? (always plenty of space)
CLALMA	Clear alarm by Alpha (no alarm functions implemented)
CLALMX	Clear alarm by X (no alarm functions implemented)
CLD	Clear display (no need)
CLKEYS	Clear key assignments (no keys to clear)
CLOCK	Show clock (no clock function)
CLRALMS	Clear all alarms (no alarm functions implemented)
CORRECT	Correct clock drift (no clock function)
ED	Go to ascii file editor (no need for that)
EMROOM	Get room left in eXtended Memory (lots and lots)
FLSIZE	Get file size (alway plenty)
GETSUB	Get sub program (no need - XRPN works with pages for programs)
PACK	Pack program (always packed)
PASN	Programmable key assignment (no keys to assign to)
PSIZE	Programmable SIZE (no need for any sizeing)
RCLAF	Recall clock accuracy factor (no clock function)
RCLSW	Recall stopwatch time (no stopwatch here)
RESZFL	Resize XM file (no need, lots of room)
RUNSW	Run stopwatch (no stopwatch here)
SETAF	Set clock accuracy factor (no clock function)
SETSW	Set stopwatch (no stopwatch here)
SIZE	Set size of memory (no need, lots of room)
SIZE?	Returns size of memory (no need, lots of room)
STOPSW	Stop stopwatch (no stopwatch here)
SW	Stopwatch (no stopwatch here)
SWPT	Stopwatch and pointers (no stopwatch here)
T+X	Add X to clock time (no clock function)
XYZALM	Set alarm (no alarm functions implemented)

Functions that work a bit differently from the HP-41 commands:

HP-41 command	XRPN command	Short explanation
CAT n	cat n	Catalog. Only CAT 1, 3 and 4 implemented
CRFLAS	crflas	Create ASCII file. No need to supply any file size.
CRFLD	crfld	Create data file. No need to supply any file size.
ENG n	eng n	Engineering format. Set number of decimals (fix) to n, threshold to for when exponents kick in to 6 and show exponents as multiples of 3.
GETAS	getas	Loads XM file (any tupe)
GETKEY	getkey	Waits 10 seconds for user to press a key (return Character Code to X, not HP-41 key code)
GETKEYX	getkeyx	Waits X seconds for user to press a key (return Character Code to X)
GETP	getp	Get program from program file
GTO n	gto n	Goto (jump) to a string label, numbered label or line number (GTO "MyProg", GTO 31, GTO .214), using a dot before the line number)
OFF	off	Ends XRPN.
ON	on	Makes XRPN not end end on a single Enter in debug mode.
PROMPT	prompt	Prompts for input (does not enter debug mode as with STOP)
RCLFLAG	rclflag	Recall flag status to X (uses different, more readable flag status format)
SCI n	sci n	Scientific format. Set number of decimals (fix) to n, threshold to for when exponents kick in to 9.
STOFLAG	stoflag	Restore flag status from X (uses different, more readable flag status format)

XRPN functions not in the HP-41 command set

XRPN command	Description
adateiso	Return date in X (DD.MMYYYY or MM.DDYYYY) as YYYY-MM-DD in Alpha
agsub	Substitute all instances in Alpha matching the regexp in X by the content in Y
arcli	Recall the integer part of X to Alpha
asub	Substitute the first instance in Alpha matching the regexp in X by the content in Y
aviewc	Print out (show) content of Alpha register in the 256-color-code specified in X
bindec	Take X as a binary number and convert to decimal number in X
clear	Clear terminal display
cmdadd	Add command in Alpha to the current program at line number in X (makes it possible to write self-modifying programs)
cmddel	Delete line number in X from the current program (makes it possible to write self-modifying programs)
cmdhelp	Show help text for the command in Alpha
cmds	Print all available commands
copy	Copy file named in Alpha to filename in X
cube	Return X^3 to X
decbin	Take X as a decimal number and convert to binary number in X
dechex	Take X as a decimal number and convert to hexadecimal number in X
decoct	Take X as a decimal number and convert to octal number in X
deg?	Prints the current degrees mode
dot	Toggles Flag 28 (dot type - dot or comma as decimal separator)
drop	Drop stack
dropy	Drop only Z and Y
error	A shortcut for CF 25 (clears flag 25 to not ignore errors) - see "unerror"
FC?S n or fcs? n	Flag clear? If not, skip next program line and set flag.
fix?	Print current FIX setting
FS?S n or fss? n	Flag set? If not, skip next program line and set flag.
geir	Easter egg
getfile	Read any file named in Alpha into X
getfilea	Read any file named in Alpha into Alpha
getweb	Get web page with URL in Alpha into X
help	Print help text
hexdec	Take X as a hexadecimal number and convert to decimal number in X
invf n	Invert flag (toggle flag n)
lastpage	Returns to X the index number of the last page
load	Load the program file named in Alpha into a new page
move	Move file named in Alpha to filename in X
octdec	Take X as an octal number and convert to decimal number in X
open	Open a file system file or make directory the current directory
page n	Make Page n the current working program Page
pagedel n	Delete Page n
page?	Prints current working Page
pageswap	Swap pages (page numbers in X and Y)
pcat	Show global program labels across all Pages
pprgx	Print current program from lines Y to X (relative to current line if Y is negative)
pprgtofile	Print program named in Alpha to file named in X
prflags	Print status of all flags
prregs	Print content of all registers
prstk	Print Stack (including Alpha and L)
prxm	Print content of eXtended Memory
rand	Return a random number between 0 and 1 to X
reload	Reload all commands in the ./xrpn/cmd directory (makes it possble to modify or add commands while a program is running)
root	Returns Y^(1/X) to X
rubycmd	Evaluate the Ruby command in Alpha. Gives you access to all of Ruby inside XRPN.
savexm	Save the current XM file to disk
sep	Toggles Flag 29 (separator for every 3 digits)
shellcmd	Executes the shell command in Alpha. Gives you access to all of Bash inside XRPN.
stdout	Writes content of X to Standard Out (STDOUT) - with this you can pipe the output of an xrpn program.
tonexy	Sound a tone with frequency in X and length (in sec) in Y
unerror	Shortcut for SF 25 (set flag 25 to ignore the next error in a program)
version	Show the XRPN version number
writefile	Write X as content to file named in Alpha
xmexist?	Checks if XM file named in Alpha exists (returns file type and YES or NO)
xmfile?	Print name of current XM file
X>=0? or xgteq0?	Conditional - if not true, skip next program line
X>=Y? or xgteqy?	Conditional - if not true, skip next program line

Note

Find anything wrong or unclear? Please do open an issue.