#/bin/dc
#commented, readable version of examples from the article at
#http://te.brhfl.com/2012/01/25/dc/

#The Basics

#5 3 + 2 *
#Is the RPN/post-fix equivalent of (5 + 3) * 2 =
#In RPN, we enter the two operands first, and then the operator to perform
#this cuts out ambiguity, eliminates the need for an '=' termination,
#and eliminates the need for parenthesis.
#So,

5 3 +           #Puts a 5, and then a 3 on the stack, and then adds them 
                #together.

2 *             #Puts a 2 on the stack (after the result of our last 
                #operation) and then multiplies it with our previous result.
                #16 should be on the stack now, but we can't see it because 
                #we don't yet know the command to print.



#32 2 * 4 / p
#Now, we learn 'p,' the print command. So, again

32 2 *          #Multiplies 32 by 2, leaving the result on the stack,
4 /             #Divides the previous result by four, and
p               #Prints the result (16).

f               #Prints the entire stack. At this point, that should give 
                #us two 16s.

c               #Clears the entire stack

#After that, I mention that I often clear my screen at the same time as
#clearing my stack. For this, I use the '!' command, which executes a
#shell command. So,

c               #clears the stack, and
!clear          #sends the 'clear' command to the shell, clearing the 
                #screen.



#I then mention 'd' and 'r,' which will throw up errors right now with 
#our empty stack. But we can test this anyway:

2               #Put a two on the stack
d               #Duplicate it
f               #Show the stack - it should be two 2s.

5 6             #Put a 5 and a 6 on the stack
r               #Reverse the two
f               #Show the stack - it should be a 6 and then a 5

c               #Clear the stack back to where we were.



#Precision:

#weird, pseudo-float behavior:

2.25 2 * p      #Should return 4.50
4.50 2 / p      #Does not return 2.25. So let's not do this, let's set 
                #precision:
4 k             #To set precision to 4 places
4.5 2 / p       #Returns 2.2500, which is what we want.
K p             #Returns 4, our set precision level



#Setting radices:

16 o            #Set output radix to 16 (hexadecimal)
16 i            #Set input radix to 16 (hexadecimal)
A i             #Switch input radix back to 10 (decimal) from hex
2 o             #Switch output radix to 2 (binary) to demonstrate 
                #conversions
48 p            #Input is decimal, output binary, so convert 48 over to 
                #binary. Should return 110000
16 i            #Input is hex now, let's convert hex to binary
AF p            #Convert hex AF to binary, returns 10101111.
A i             #Back to decimal input for the rest of the examples
10 o            #Back to decimal output, as well!



#Settings, Registers, Macros, Comparisons

#[8 4*]
#is a macro that multiplies 8 by 4. Macros are strings containing commands
#and strings are defined by square brackets. So:

[               #Start the macro (string)
8 4*            #These are the contents, for a macro, they are just dc 
                #commands
]               #End the macro
x               #Executes the macro, and
p               #Prints the result of such an execution.



#Registers:

42              #Put that on the stack
sa              #Store it in register a
la              #Load it back to the stack
p               #Print it - should return 42



[               #Start a macro definition
65535           #Put this on the stack
*               #Multiply whatever we have with our 65535
] sb            #End definition, store it in register b

1 lb x p        #Enter 1, load macro 'b,' execute it, and print the result 
                #(65535)
2 lb x p        #Enter 2, load macro 'b,' execute it, and print the result
                #(131070)
3 lb x p        #Enter 3, load macro 'b,' execute it, and print the result 
                #(196605)



[               #Start a macro definition, again
O               #Get the current output radix
sz              #Store it in register 'z' for later
16              #Put 16 on the stack
o               #Change the output radix to 16 (hex)
p               #Print - the idea here being that we'll enter decimal and 
                #Run this to convert to hex
lz              #Load our old output radix in
o               #And set it
] sc            #End the definition, store it in register 'c.'

15 lc x         #Put 15 on the stack, load and run macro 'c,' get our 
                #conversion (F)
64 lc x         #Put 64 on the stack, load and run macro 'c,' get our 
                #conversion (40)
255 lc x        #Put 255 on the stack, load and run macro 'c,' get our 
                #conversion (FF)



#Comparisons:

[               #Wrap our 'true' output in a macro
[true] p        #Make a string, 'true,' and print it
] sd            #Store our 'true' wrapper in macro 'd.'

5 6             #Put those on the stack
>d              #If 6 is greater than 5, execute macro 'd.' Returns 'true.'

6 5             #Put those on the stack
>d              #If 5 is greater than 6, execute macro 'd.' It's not, 
                #so return nothing

6 6             #Put two identical numbers on the stack
!=d             #If 6 does not equal 6, execute macro 'd.' Obviously, 
                #not happening.

6 6             #Put them on the stack again
=d              #If 6 does equal 6, execute macro 'd.' Returns 'true.'



#Make a simple for loop.
#This loop follows the construct of
#for ($i=0; $i<10; $i++){
#  echo $i;
#  }

0 si            #Initialize i ($i=0)
[               #Start our macro
  li p          #Load and print out i (echo $i)
  1+            #Increment i ($i++)
  d             #Duplicate i - this is necessary because it will get 
                #popped off the stack when we save it
  si            #Store i again - this is also part of $i++
  10>e          #If 10 is greater than i, run 'e' (this macro!)
] se            #Finish this off, store is as 'e.'

le x            #Load e, and run it
                #Output should be 0 1 2 3 4 5 6 7 8 9



#The end, for now

6 3             #Put those on stack
^ p             #Exponent - 6 to the third power, and print (216)

64 v p          #Square root of 64, print, returns 8.