spl/README.md
2023-02-20 14:34:40 +01:00

5.9 KiB

"Stack Programming Language" =SPL

SPL is a simple, concise, concatenative scripting language.

Example:

func main { mega | 
    "Running with args: " print
    argv:iter
        { str | " " concat } swap:map
        &print swap:foreach
    "" println
    0
}

"5 minutes" SPL:in

  • def introduces a variable.

    def a
    
  • Writing a constant pushes it to the stack. This works with strings and numbers.

    "Hello, World!"
    
  • Use =<name> to assign the topmost value to a variable. In this case, that is "Hello, World!"

    =a
    
  • This can be written as a single line - line breaks are always optional, and equal to a space.

    def a "Hello, World!" =a
    
  • Variables consist of two functions: <name> and =<name>. Use <name> to obtain the value again.

    a
    
  • The print function is used to print a value. It takes one value from the stack and prints it without a newline. To print with a newline, use println. The semicolon at the end means 'if this function returns anything, throw it away'. This can be used on strings to make them comments, but is not available for numeric constants.

    println;
    
    Hello, World!
    
  • The func keyword introduces a function. The { mega | is the return type declaration, which in SPL is done within the block. In this case, our function returns one of the mega type, which is a 128-bit integer.

    func main { mega |
    
  • Now, we can write code like before:

    def list
    
  • SPL has a varying-length array type, the list. To create any construct (object), we use :new.

    List:new =list
    
  • To add to the end of a list, we push to it. All construct methods are written with a colon, like before in the new example.

    "Hello," list:push
    

    Note the lowercase list, because we are pushing to the construct in the variable.

  • Now, let's also push "World!".

    "World" list:push
    

    Beautiful. I'd like to print it now, but how?

  • We can't print a list directly (with what we know so far), but we can iterate through it!

    { | with item ;
        item print;
        " " print;
    } list:foreach;
    "" println;
    

    There is a lot to unpack here!

    • { | creates a closure with no return type (in C-style languages, that'd be a void function).
    • with item ; declares arguments. This is optional, and not needed if the function does not take arguments. Running "a" "b" "c" and calling something with a b c ; will leave each letter in the corresponding variable.
    • We already know what print does - it prints the item and a space in this case.
    • The semicolons mean we don't care about the result of printing. In this case, printing does not return anything, but I added the semicolons just for clarity or in case it did.
    • } ends the closure, and puts it on the top of our stack.
    • list:foreach calls the foreach method on our list, which is declared with callable this ; - that means we need to provide one argument along with the implied this argument (it can have any name - the interpreter does not care about names in any way - this is just convention). The callable here is not a type!
    • foreach also does not return anything, but I added the semicolon for clarity.
    • We then print a newline.
    Hello, World! 
    
  • SPL has Ranges, constructed using <lower> <upper> Range:new. You can iterate over them.

    0 5 Range:new:iter
    
  • Now, let's multiply all of these values by 5.

        { mega | 5 * } swap:map
    

    Wait, what? Why is there suddenly an inconsistency in method calls, the iterator isn't being called, it's something else now!

    It sure does look like it, doesn't it? swap swaps the topmost two values on the stack. a b -> b a. That means we are actually calling to our iterator. The closure and the iterator are swapped before the call is made. swap:map is a more concise way of writing swap _:map. The underscore is used as a placeholder for the topmost value of the stack when making method calls, because swap :map would try to call map on an empty expression.

    The map function on the iterator (which is available through :iter on most collection constructs) is used to apply a function to all items in the iterator. The closure here actually takes an argument, but the with declaration is omitted. The longer version would be:

        { mega | with item ;
            item 5 *
        }
    

    But this is quite clunky, so when arguments are directly passed on to the next function, they are often simply kept on the stack. The * is simply a function taking two numbers and multilying them. The same goes for +, -, %, and /. a b - is equivalent to a - b in other languages. lt, gt, and eq are used to compare values.

    Returning is simply done by leaving something on the stack when the function exits, and the return declaration can technically be left off, but the semicolon won't be able to determine the amount of constructs to discard that way, so this should never be done unless you're absolutely sure. In this case, we are absolutely sure that it will never be called with a semicolon, because the mapping iterator has no use for the closure other than the returned object (which is the case for most closures in practice.), therefore we could even omit the return type declaration and get { | 5 *}. Neat!

  • We can use foreach on iterators just like arrays. _str is used to convert a number to a string.

        { | _str println } swap:foreach
    
    0
    5
    10 
    15 
    20
    

    Ranges are inclusive of the lower bound and exclusive in the upper bound. They are often used similarly to the (pseudocode) equivalent in other languages:

    for(int i = 0; i < 5; i++) { println((String) i * 5); }
    

More of this tutorial to follow.