Position Independent Source Code

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

PISC in Y minutes

# PISC has 2 types of comments: line comments like this one, and
/*
Block comments like this.
*/

"Hello, world!" println
# PISC is a stack based language, which means that PISC generally 
# works rather like Reverse Polish Notation (RPN)
# This means that the arguments for a command come before the command itself.
# And that commands generally run backwards commpared to most languages

# So if we have this stack, what can we do with it?
1 2 swap    # Stack: 2 1
dup         # Stack: 2 1 1 
drop        # Stack: 2 1 
2dup        # Stack: 2 1 2 1
nip         # Stack 2 1 1 ( Get rid of the second ) 

# And we'll clear the stack for further examples
drop drop drop 

# Basic math looks like this:
1 2 + # Stack: 3
# If you're running PISC on your local machine, you'll notice that after each 
# line of input, it shows you the stack, and the types of the variables on the stack.

drop        # We're done with that 3 for now.


# PISC currently has two types of numbers: Integers and Double Precision floating point numbers.
1 2.0 +     # 3 <Double>
# And when a Double and int mix, the int is converted into a double
3.2 *       # 9.600000000000001 <Double>
drop


# Booleans are also handled in an RPN fashion, true and false are represented by `t` and `f`
t f and     # f <Boolean>
t or        # t <Boolean> No surprises here

# clear-stack will get rid of anything left on the stack
clear-stack

# In PISC, since all words take arguments off the stack, 
# control flow tends to work in a bit of a backwards way

# This is an if statement.
# the bits with `[` and `]` are called quotations, and they are kinda special 
# This puts a boolean value and 2 quotations on the stack, and the checks the 
# the boolean value to decide which quotation to execute
t [ "true" println ] [ "false" println ] if   

# Note also that you can use the stack to send 
# Information to another command
# This will print "Different"
2 1 = [ "The same" ] [ "Different" ] if println

# They are how you pass code to words that can be executed at a later time
# If you want to execute a quotation, you use the `call` word
[ "This is a quotation" ] [ "But this is the one that will be called" ] call

# Quotations live on the stack before they are used, so you'll seem them printed out
# For example you could type the above example in this fashion:
[ "This is a quotation" ] 
[ "But this is the one that will be called" ] call
# And if you do that, you'll see the stack get built up for each quotation. 
clear-stack

# Now that we have quoations a little explained we can cover vectors, which are PISC's array-like collections
# The basic syntax for them is:
{ 1 2 3 }       # Stack: [1 2 3] <Vector>
dup 0 vec-at    # stack: [1 2 3] <Vector>, 1 <Integer>

# One thing to note about { } syntax for vectors is that the words inside the { } are treated as code
# Such that the words are executed, and then anything they put on the stack is sliced into vector.
{ 10 [ 1 ] times }
# Stack: [1 1 1 1 1 1 1 1 1 1] <Vector>


# Those are some of the stack shufflers. If you want to build your own stack shufflers
# run `"pick" help` to look at how my current set is built.

# Though some stack-based languages make them hard to use, PISC has decently fully featured local variables
# so that you don't have to track way too many stack entries in your head when dealing with larger code.
# You use `:varname` to take 1 value from the stack and store it in a local variable.  
"yumaikas" :name 3 :num
# Is the same as:
"yumaikas" 3 :num :name
# Though I do not recommend using the second style

# $varname places the value from varname onto the stack
$name println     # Prints "yumaikas"

{ $name $num }  # Stack: [yumaikas 3] <Vector>
clear-stack


# There are roughly two ways to define words (what most langauges call functions) in PISC:
# The most bang/buck is to use a `:` `;` combo
# Words defined this way have the rough syntax of `: name ( invals -- outvals )  definition ;`
# You need every part, though the stack effect comment (From `(` to `)`) isn't currently checked.
: sum-vec ( vector -- result ) 0 swap [ + ] vec-each ;

# Each time you define a word like this, it recieves its own locals frame.
# (Which means that it has it's own set of local variables) 

# This doesn't apply to the second way to define a word:
[ 0 swap [ + ] vec-each ] :sum-vec
# If a quotation is stored into a local variable, 
# you can now use the name of the local variable as a word
{ 1 2 3 4 } sum-vec
# Stack: 10 <Integer>

# Loops
# Right now PISC has 3 main types of loops
# 1) Counted loops based on the `times` word
0 :i
4 [ $i print ++i ] times
# This prints 
# 0
# 1 
# 2
# 3

# 2) Condition based loops, using the `while` word
[ $i 0 = not ] [ $i print --i ] while
# Prints:
# 4
# 3
# 2
# 1 


# 3) Each collection type, Vectors, Dictionaries and Strings currently several words that iterate over them
{ 1 2 3 4 } [ println ] vec-each 
# Prints
# 1
# 2
# 3
# 4

"abcd" [ println ] each-char 
/* Prints 
a
b
c
d
*/

# Dictionaries use strings for keys, and anything for values
<dict> dup :funnyNumbers
    # value <<-key
    # <<- takes the value, stores it at "key" in the dict, and leaves the dict on the stack
    "42" <<-answertolife
    "1337" <<-leet 
    # <- works similarly to <<-, but doesn't leave the dict on the stack
    "DEADBEEF" <-debug

# $dict ->key
# takes the value at "key" from $dict, and puts it on the stack 
$funnyNumbers ->leet println 
# Prints 

# $dict ->>key
# Takes the value at key, puts it on the stack,
# and leaves the dictionary at the top of the stack
#
# $dict ->key
# Same as ->>, but does not leave the dictionary 
# at the top of the stack.
${ $funnyNumbers ->>answertolife ->debug } println

# Prints:
# "42DEADBEEF"




# TODO: More examples