syntax.ren

// The following file is a complete and valid Ren module, designed to showcase
// all the syntax features of the language. If this module compiles, then we can
// be reasonably sure the compiler will handle most code users will write. If not,
// there's a bug!

// As we've already seen one, let's first look at comments. Ren only has line
// comments. They should be valid everywhere, with the parser simply ignoring
// everything from the `//` to the end of the line.

// IMPORTS ---------------------------------------------------------------------

// The idiomatic way to handle imports in Ren code is to import a module and qualify
// it with some namespace, as demonstrated below. Note that the namespace may be 
// broken up by periods.
import "ren/array" as Ren.Array
import "ren/array" exposing { map }
import "ren/array" as Ren.Array exposing { map }

// Imports can also be just for their side effects, although this is only really
// useful when importing JavaScript directly.
import "some-effectful-module"

// The compiler is ostensibly concerned with simply turning Ren source files into
// compiled JavaScrpt ones. It's down to individual tooling to manage imports and
// dependencies. As a consequence, there aren't really any formal rules for what
// *can* be imported. In the experimental Advent of Code runner, for example, we
// have imports like:
//
//     import './util' as Util
//     import 'pkg ren/array' as Array
//     import 'ext performance-timing' as Perf
//
// to differentiate between local imports, ren package imports, and external js
// imports.

// DECLARATIONS ----------------------------------------------------------------

// `let` declarations are like `const` in JavaScript, they bind a name to a value.
let x = 10

// These declarations (like all declarations) can be made _public_ so they can be
// imported in other modules with the `pub` modifier:
pub let y = 5

// NOTE: When compiling with optimisations enabled, dead code elimination will
// remove any unused bindings. In this case the `x` declaration would be removed
// from the compiled JavaScript output because it's not used in any "live" code!
//
// When using this file to verify the compiler, unless you're explicitly testing
// them, it's probably a good idea to leave optimisations disabled so you can 
// be sure *everything* compiles and emits properly.

// Function declarations are just regular `let` declarations. We have a very
// similar syntax to JavaScript for lambda functions: but we've dropped the
// parentheses and comma separators to match our function call syntax.
let f = a b => a + b

// It is possible to pattern match in function arguments. We might destructure
// an object or match against a single enum variant. As we'll see later, pattern
// matching is a bit like JavaScript's destructuring but cranked up to 11.
let f = { a } (#just b) => 
    a + b

// Notice that the function body is dropped onto a new line in the above example.
// This (or the indentation) isn't necessary, but we'd generally consider it good
// code style to do this for all your top-level declarations.

// Sometimes you want to run a function or evaluate an expression just for its
// side effects, like logging something to the console for example. Outside of
// declarations, Ren doesn't have statements and so you can't just throw in a
// `console.log` somewhere like you might in JavaScript.
//
// You can achieve a similar result with a `let` declaration that binds to nothing:

let _ = console.log "You don't care about my result, you only care about my side effects!"

// This ends up being quite common, particularly in the case of logging while
// debugging, so Ren has some syntax sugar just for this. The above can be written
// using the `run` declaration instead:

run console.log "You don't care about my result, you only care about my side effects!"

// BLOCKS ----------------------------------------------------------------------

// The body of a declaration is exactly one expression, so what can we do if we
// want some locally scoped variables? Ren has a block *expression* that consists
// of zero or more local `let` bindings, followed by an expression to return from
// the block.
let z = {
    let x = 1
    let y = 2
    let add = a b => x + y

    ret add x y
}

// Because blocks are expressions, they can go anywhere any other type of expression
// is expected.

// PATTERN MATCHING ------------------------------------------------------------

// Like many modern (and not so modern) functional languages, Ren supports powerful
// pattern matching. Think of pattern matching as a super-powered JavaScript 
// switch statement. As with blocks (and most other things), Ren's pattern matching
// constitutes an expression and so always evaluates to some value.

// The most simple use of pattern matching is like a typical `switch` statement
// in other languages: checking an expression against a set of literal values.
run where z
    is 0 => console.log "z is 0."
    is 1 => console.log "z is 1."
    is _ => console.log "z is greater than 1."

// That underscore is a _wildcard_ pattern, it matches anything. We can also match
// things and give them a name:

run where [ 1, 2, 3 ]
    is array => console.log "`array` is [ 1, 2, 3 ]"

// This doesn't seem that useful to begin with, but we can combine name binding
// patterns with other patterns to check the structure of something and pull
// some values out at the same time.

run where some_array
    is [ 1, 2, ...rest ] =>
        // For this pattern to match, `some_array` must be an array with at least
        // two elements. And the first two elements must be `1` and `2` respectively.
        // Any remaining elements are captured in the spread pattern and stored
        // in an array called `rest`.
        //
        // If `some_array` was `[ 1, 2, 3, 4 ]` then `rest` would now be `[ 3, 4 ]`.
        console.log rest
    
    is [] =>
        // In this pattern, `some_array` must be an empty array to match.
        console.log "`some_array` is empty!"

    is _ =>
        console.log "`some_array` is something else."

// Maybe we're not sure if a value is an array or an object. Fear not, Ren has
// patterns for dynamic type checking too!

run where ambiguous_point
    is @Array [ x, y ] =>
        console.log "The point was an array!"

    is @Object { x, y } =>
        console.log "The point was an object!"
    
    is _ =>
        console.log "The point was something else."

// Patterns are great for breaking down the structure of a value and pulling out
// the bits you're interested in, but sometimes we want to _guard_ a pattern with
// some arbitrary condition. Ren has you covered with pattern guards!

run where [ 2, 1 ]
    is [ a, b ] if a <= b =>
        console.log "Ascending!"

    is [ a, b ] if a >= b =>
        console.log "Descending!"