dc: A Primer

Wed 2012.01.25
by brian hefele

Even though I generally have an HP or two handy, the POSIX command-line RPN calculator, dc, is probably the calculator that I use most often. The manpage is pretty clear on its operation, albeit in a very manpagish way. While the manpage makes for a nice reference, I’ve not seen a friendly, readable primer available on the program before. This is likely because there aren’t really people lining up to use dc, but there are a couple of compelling reasons to get to know it. First, it’s a (and in fact, the only calculator, if memory serves) required inclusion in a POSIX-compliant OS. This is important if you’re going to be stuck doing calculations on an unknown system. It’s also important if you’re already comfortable in a postfix environment, as the selection of such calculators can be limiting.

The Basics

First of all, if you’re not familiar with postfix/RPN, it works on the principle of building a stack of objects and then operating on them rather than evaluating a statement of mixed up objects and operators. While many are used to the latter (infix or algebraic), it’s often a rather inefficient method of computation. That’s not really a debate for right now, however, because dc is a postfix calculator, so that’s what you’re stuck with. The thing to take away from all of this is that rather than calculations being input like (5 + 3) * 2 =, they are entered like 5 3 + 2 *. In dc, whitespace is mostly meaningless. The only time it is really necessary is when putting multiple numbers on the stack. If we want to put 5, 3, and 2 on the stack, we must separate it out 5 3 2, else we’re putting a single number, 532 on the stack. This whitespace can be a space or a newline.

Hitting enter evaluates the current line. Basic arithmetic, the four commands +, -, /, and * work as expected. By default, nothing is returned to the screen; to get the last entry on the stack (the result of basic operations), the command p must also be executed. So, to get to the bottom of (32*2)/4, we would input 32 2 * 4 / p, and get 16 returned. Of course, since whitespace is optional, this can also be entered as 32 2*4/p. Note, for postfix newbies, that parenthesis are never necessary, as ambiguity is impossible.

The full contents of the stack can be displayed using the command f, and the stack can be fully cleared using the command c. The command ! executes the remainder of the line as a shell command, thus I often clear my screen at the same time as my stack by executing c!clear. Two other stack manipulations that come up often are d to duplicate the last item on the stack, and r to swap (or reverse) the last two items.

Precision is arbitrary and fixed using the command k. Certain operations ‘float’ to an extent, that is, 2.25 2*p returns 4.50, though 4.50 2/p does not follow, returning 2. Thus, the first thing I usually do when I open dc is give myself a few points of precision, generally four, by entering 4k. Upon doing this, 4.5 2/p properly returns 2.2500. The currently set precision can be pushed to the stack with the command K, a scheme that we’ll see again with operating radices. If we’ve set 4k, entering Kp should then return 4.

Input and output radices (bases) are controlled with the commands i and o, respectively. To output in hexadecimal, enter 16o. To input in binary, enter 2i. If you’re going to be working in a given radix (input and output), it’s probably best for your sanity to adjust output first and then input, since such things take place immediately. That is, both 16o16i and 16i10o change both input and output to hexadecimal, but the first choice is much clearer. Likewise, when you need to switch again, be mindful of your current input radix. If we have 16i set, and we need to get back to decimal, 10i will not work (it will simply re-set input to hex). Instead, we need to remember we’re inputting in hex, and use Ai instead. Conversion from-radix-to-radix are as simple as setting unmatched input and output radices. Assuming our input is set to decimal, and we need to convert to binary, we will just leave input alone and enter 2o. Then, entering 48p will convert that decimal 48 to binary, returning 110000. We can then set 16i if we want to convert from hex to binary, enter AFp, and get the result 10101111. We can use I and O to push the respective radices onto the stack — but again, keep in mind, they will ultimately be output in the current output radix. Thus, O will always return 10, making it useless outside of macros.

Strings, Registers, Macros, Comparisons

For the most part, strings are handled pretty transparently inside of dc. Anything wrapped in square brackets is considered a string. Strings sit on the stack like numbers, and can be printed using the same p command. Strings can be used to prompt users for input, provide context for output, or, most importantly, define macros (akin to functions). A macro is simply a string containing a bunch of dc commands, such as [8 4*] being a macro that multiplies eight by four. Macros are, most basically, executed with the command x. Thus, [8 4*]xp will define our macro (pushing it onto the stack), execute it, and then print the result.

The manpage for dc claims that ‘at least 255′ registers can be defined. A register, for those unfamiliar, is akin to a variable. It’s a place where information can be stored and then retrieved later. Registers in dc are complex — they contain their own stacks, and can also be indexed arrays. For the purposes of this primer, we’re only going to deal with simple registers, each holding a single piece of data. This piece of data can be anything that would sit on the stack — that is, either a number or a string (including macros). The command sr is used to store a value in a register, and lr is used to load the value of a register back onto the stack. In both cases, r is a single character used to name the register. So, entering 42sa puts the value 42 into a register named ‘a.’ Later, when we need to retrieve this undeniably useful number, we can execute la, and then p to see that we do, in fact, have our 42 back.

The ability to store and retrieve macros is one of the most powerful tools at our disposal in dc. If we need to multiply a number by 65535, we can create and store a macro [65535*]sb. Then, we can do things like (whitespace added for clarity from here on) 1 lb x p 2 lb x p 3 lb x p and get back 65535, 131070, and 196605, as expected. To make a macro that converts the current stack value into hex, we can enter [O sz 16 o p lz o]sc. To run this, we can leave our input as decimal, and do things like 15 lc x 64 lc x 255 lc x, returning F, 40, and FF.

Comparative operations in dc work by making the comparison, and if it ends up being true, running a set macro. Where r is the register containing the macro to run, the following comparators are available: >r (greater than), <r (less than), !>r (not greater than — put simply, less than or equal to), !<r (not less than — again, put simply, greater than or equal to), =r (equal to), !=r (not equal to). If we define a simple macro to echo ‘true’ upon execution, [ [true] p ]sd, we can do some quick comparisons. Entering 5 6 >d 6 5 >d 6 6 !=d 6 6 =d will return true, (null), (null), and true, as our macro d is only executed on the two that are true — 6 greater than 5, and 6 equal to 6.

For loops can be constructed using comparators that call the macro they’re inside. For instance, a typical for ($i=0; $i<10; $i++){ echo $i; } can be expressed as 0 si [li p 1+ d si 10>e] se lex. First, we initialize i as 0 ($i=0), then we set up our ‘for loop’ macro. Our macro first loads i back onto the stack, then it prints it out (echo $i), adds one ($i++), duplicates it (because storing it will pop one instance off the stack — and we need it to still be there for the next step), and finally checks if it’s less than 10 ($i<10), running the macro e if this is the case. We save this macro as e, and then run it, giving us a printout of the numbers 0-9.

The end, for now

This should serve as a pretty good introduction to the operations of dc, while not covering all of its commands or capabilities. I’m bound to write more on the matter at some point, but until now have never seen a good way for newbies to break in to the program. The manpage covers things I didn’t, including the more complicated register and array operations, as well as commands for getting extra division operation results, exponents (6 3 ^ p returns 216), and square roots (64 v p returns 8). All of the examples given in this primer can also be viewed in exploded, commented form in this document (if you’re using vim, it’ll look best with my dc syntax file). I can’t fathom a life without dc, the simple yet powerful RPN calculator that can be found nearly everywhere.

dc Syntax for Vim

Thu 2010.05.06
by brian hefele

Note: this article originally appeared on http://brhefele.brainaxle.com. Links may still point there, formatting may be off, this may all get fixed.

I use dc as my primary calculator for day-to-day needs. I use other calculators as well, but I try to largely stick to dc for two reasons – I was raised on postfix (HP 41CX, to be exact) and I’m pretty much guaranteed to find dc on any *nix machine I happen to come across. Recently, however, I’ve been expanding my horizons, experimenting with dc as a programming environment, something safe and comfortable to use as a mental exercise. All of that is another post for another day, however – right now I want to discuss writing a dc syntax definition for vim.

The first amazing thing, to me, was that there was not already a syntax definition for dc! I have thoughts on the matter – dc is a fairly obscure, archaic tool that I’m sure is rarely used; those who do use it likely use it in interactive mode rather than writing code for it; languages like Python (etc.) provide great platforms for math coding as well as interactive use. Yet there are syntax definitions for far more obscure languages (LOLCODE), and dc is perfectly suited for quick math scripts. But I digress, I don’t really care that nobody has come up with a syntax definition for dc, it just surprises me. So I figured I’d roll my own. Not a difficult task, but a few things made it easier for me…

Vim has wonderful documentation, but it’s almost too straightforward, lacking in examples, etc. I find it easier to start with a little tutorial – like this one – to wrap my head around what I’m getting into. So that was a good start, but I quickly realized a problem – syntax keywords are expected to be just that – words. dc largely ignores whitespace, and treating every command as a word (adding a space between each command) would nearly double the amount of typing necessary. At this point I realized I wouldn’t be able to use any syntax keywords, and would instead need to do everything through regex.

Sometimes it helps to compare your strategy to that of an existing, similar product. To that end, I decided to check out Mathias Panzenböck’s syntax definition for brainfuck, another language in which whitespace between commands is unimportant. The brainfuck definition, unsurprisingly, was all done through regex. So, new problem, Vim’s regex support is weird at best – determining what does/doesn’t need escaping is a complete crapshoot. Fortunately, at some point, I read about Vim’s very magic mode. So that makes things pretty easy. Then I came to the point where I had to figure out how to handle strings.

Because macros in dc are stored in strings, and are in fact completely indistinguishable from other strings, a problem arises. I want my macros to be what Vim calls ‘transparent’ – that is, the commands inside them should be properly highlighted. Strings, on the other hand, should be their own highlight, all one color (and with spellchecking enabled, for my uses). First I had to make some rules for myself – any string followed immediately by an execute command is obviously a macro, but that’s not the only case. So, I looked at my own code and realized that whenever I’m writing a macro, I give it its own line – just the macro and its save command. So, while this is meaningless to dc, it’s meaningful to me, and I needed something meaningful to apply.

The final trick was in getting this to work. If I have a string defined as a string, and I have this arbitrary scenario defined as a ‘macro,’ and I want my macro to be transparent, well, all that’s going to show through is the string! Then we’re back to square one… The trick I used, and I’m not sure if there’s an easier way (and I’m not sure if there needs to be – this is probably a rather rare situation) was to set the contains parameter of my macro to NONE, telling it that it contains no other highlights, and then manually adding every other highlight except for string. I was also able to leave out comment and shell command, since they eat up that follows until newline.

The final file, which I actually need to make one change to, can be previewed here, and can be downloaded on vim.org.