-- Forml
-- =====

-- <script type="text/javascript">
-- $("header ul").prepend('<li><a href="https://github.com/texodus/forml/zipball/master">Download <strong>ZIP File</strong></a></li><li><a href="https://github.com/texodus/forml/tarball/master">Download <strong>TAR Ball</strong></a></li><li><a href="https://github.com/texodus/forml">View On <strong>GitHub</strong></a></li>').css("width", "360");
-- $("header h1").after('<br style="clear: both;"/>');
-- $("h1").css("font-family", "Montserrat");
-- $("header h1:first-letter").css("color", "#E53007");
-- </script>

-- Forml is a contemporary programming language for the discriminating
-- programmer, intended to fill a niche
-- somewhere between [Haskell](http://www.haskell.org) and
-- [Ruby](http://www.ruby.org), should such a niche turn out to exist. 

-- Philosophy
-- ==========

--     1) Writing software is unnecessarily hard, because syntax is sufficiently
--        abstracted from thought process to lose something in the translation. A 
--        modern programming language should be designed for reading - an API 
--        exposing the programmer - a philosophy lifted unapologetically
--        from [Ruby](http://www.artima.com/intv/ruby4.html).

--     2) Writing software is unnecessarily hard, because making mistakes is too
--        easy. A modern programming language should prevent the programmer from
--        writing incorrect code, in so far as it doesn't conflict with 1.

-- Features
-- ========

--   * Buzzwords:  functional, strict, expressive, pure(ish), static(y), inferred, fast, fun.
--     Strong like a gorilla, yet soft and yielding like a Nerf ball.

--   * Targets Javascript, but please regard this as an implementation detail -
--     forml is not intended as an answer to "the Javascript problem."  Simple
--     foreign function interface, which allows the
--     introduction of untyped values for quick & dirty
--     code integration, which can later be restricted via explicit typing.

--   * Type system which is designed to be simple and catch obvious errors,
--     not entirely exhaustive, dictatorial and somewhat combative (I'm looking
--     at you, Haskell).   Strucural types, partials records, arbitrary unions, 
--     ability to introduce unrestricted types via FFI.

--   * Sugary, flexible syntax.

--   * Inline testing, compiles to a separate suite.

--   * Fast.  Automatic tail call optimization,
--     inline functions, designed for use with [Google Closure Compiler](https://developers.google.com/closure/)
--     advanced optimizations mode.

--   * Heavily inspired by 
--          [Haskell](http://www.haskell.org/haskellwiki/Haskell)
--        , [F#](http://msdn.microsoft.com/en-us/vstudio/hh388569.aspx)
--        , [Coffeescript](http://coffeescript.org/).
--        , ([_](http://en.wikipedia.org/wiki/Category:ML_programming_language_family))([S](http://www.smlnj.org/))([OCA](http://caml.inria.fr/))ML
--        , [Clojure](http://clojure.org/)
--        , [JMacro](http://www.haskell.org/haskellwiki/Jmacro)
--        , [Ruby](http://www.ruby-lang.org/en/)

-- Installation
-- ============

-- Mac OSX (tested on Snow Leopard & Lion).  Note that Forml also requires
-- [Closure](https://developers.google.com/closure/) for optimizations and
-- either [Phantom.js](http://phantomjs.org) or [Node.js](http://nodejs.org)

-- Install the
-- [Haskell Platform](http://hackage.haskell.org/platform/index.html), then

--        <pre><code>$ cabal install forml</pre></code>

-- To compile some forml files:
   
--        <pre><code>$ forml -o app test.forml test2.forml</pre></code>

-- will create an app.js and app.spec.js with the compiled code and
-- test suite respectively.

-- Forml will by default try to minify/optimize your code with Closure, via the
-- $CLOSURE environment variable, which should point to the closure jar.  Failing this,
-- forml will attempt to post your code to the Closure web service.

-- Additionally, forml will attempt to run the test suite with the phantomjs binary,
-- which it expects to find on your PATH.  You may optionally specifiy to run your suite
-- via node.js with

--        <pre><code>$ forml -node-test test.forml</pre></code>

-- To compile literate
-- forml (eg, Forml code embedded in Markdown):
   
--        <pre><code>$ forml test.lforml</pre></code>
   
-- To see the inferred types:
   
--        <pre><code>$ forml -t test.forml</pre></code>
   
-- To turn off optimizing (eg, Closure) or testing:
   
--        <pre><code>$ forml -no-test -no-opt test.forml</pre></code>

-- To watch a file for changes and incrementally compile:
   
--        <pre><code>$ forml -w test.forml</pre></code>

-- To generate documentation and test runner (like this file):
   
--        <pre><code>$ forml -docs test.forml</pre></code>


-- Tutorial
-- ========
-- This is unfortunately not comprehensive, and presumes some working knowledge of 
-- ML or Haskell.  For more examples, see the annotated 
-- [prelude](http://texodus.github.com/forml/prelude.html),
-- [parsec](http://texodus.github.com/forml/parsec.html) and [tetris](http://texodus.github.com/forml/tetris.html).  

-- Forml supports a flexible, forgiving syntax that supports many synonymous forms.
-- This will be illustrated by adherring to an entirely random, arbitrary style throughout.

-- The basic unit of code organization in forml is the `module`, which is simply
-- a collection of definitions in a namespace (see [Modules](#)).
-- Within a module, the compiler recognizes strictly ordered logical sections divided by 
-- `open` statements and sub modules;  within a section, however, declarations
-- can be in any order.

module readme

    open prelude
    open prelude.string
    
    -- Definitions
    -- -----------
    
    -- Simple function.  Forml allows functions to be written in ML style, or
    -- in more traditional java style.

    square x = x * x

    add(x, y) = x + y

    -- With pattern matching

    fib 0 = 0 | 1 = 1 | n = fib (n - 1) + fib (n - 2)

    -- Patterns can be separated with `|`, or by repeating the definition's
    -- name ala Haskell.  Definitions can have optional type annotations, which
    -- may restrict the inferred type of the definition, but must not be
    -- more general
    
    private

    fib' : Num -> Num

    fib' 0 = 0
    fib' 1 = 1
    fib' n = fib' (n - 1) + fib' (n - 2)
    
    -- Operators can be defined much like in Haskell.  Precedence is currently fixed,
    -- though you can declare right associative operators by ending them with a `:`.
    -- For performance, you can declare functions to be `inline`.  This example
    -- will compile to a loop, as it is tail recursive.

    inline (**): 

         String -> Num -> String
         text   ** n    =

             var f(_, 0, acc) = acc       -- `let` and `var` are synonyms
                 f(text, n, acc) =
                     f(text, n - 1, acc +++ text)
             
             in f(text, n, "")            -- `in` is optional
    

    -- Testing
    -- -------
    
    -- Tests are a first class concept in forml - any unbound in a module (or in other words, 
    -- any expression which isn't part of a definition), which is inferred as type `Bool`,
    -- is treated as a test, and is compiled
    -- to a [Jasmine](http://pivotal.github.com/jasmine) suite in a separate file from
    -- your definitions.  

    fib' 7 == 13
    fib' 0 == 0
    
    "hello" ** 3 == "hellohellohello"
    length ("a" ** 10000) == 10000
    
    -- For example, this file is the result of running the forml compiler with the `-docs`
    -- flag for [readme.forml](https://github.com/texodus/forml/blob/master/src/forml/readme.forml),
    -- and incorporates both the compiled output and the Jasmine suite.  You can execute
    -- this suite by clicking the `RUN TESTS` button, which will highlight the test
    -- results in this document
    
    
    -- Modules
    -- -------
    
    -- Namespaces are not symbols, so this won't work:
    
    --        <pre><code>    prelude.log "Hello, World!"    -- Won't compile!</pre></code>
    
    -- Instead, you must qualify the import and supply 
    -- a symbol name to bind to.  The alias will be typed
    -- to a record whose fields are the first-class 
    -- definitions in the module.
    
    open prelude.array as array
    
    array.map fib [3,4,5] == [2,3,5]
    
    
    -- Records
    -- -------

    -- Forml has the basic primative types from Javascript:  Num, String, Bool;  plus
    -- a record, which is structurally typed and implemented as a simple Javascript object.
    
    person name address = { 
        name    = name
        address = address
        message = "`name` lives at `address`"
    }

    person("Andrew", "123 Fake St.").message is "Andrew lives at 123 Fake St."

    point = {x: 10, y: 10}
    
    20 == point.x + point.y
   
    -- Also supports partial records.

    magnitude {x: x, y: y, _} = sqrt (square x + square y)

    magnitude {x: 3, y: 4, other: "test"} == 5
    magnitude {x: 4, y: 3, test: "other"} == 5

 
    -- Anonymous functions also follow Haskell, can be written with `\` or `λ`, and
    -- allows pattern seperation via `|`

    -- Note this function mutates its argument, so we name it with an exclamation.

    map!: (a -> b) -> Array a -> Array b
    map! f xs = do! `xs.map(f)`

    let fil =
    
        λ x when x > 5 = x
        | x            = 5

    map! fil [2, 6, 3, 7] is [5, 6, 5, 7]

    -- Interop & Side Effects
    -- ----------------------
    -- Forml technically allows unrestricted side effects, but by default
    -- wraps them in a `JS a` type, which can be composed with the
    -- `>>=` and `>>` operators, or a variation of Haskell's `do` notation.

    hello_world = do

        `console.log("Hello World")` -- Calls to Javascript always return type `JS a`
        x <- `Math.sqrt(9)`          -- `x` is inferred to be the unrestricted type `a`
        let z = x + 1                -- `x` is now restricted to type `Num`
        return (z + 1)               -- type of `hello_world` is inferred to be `JS Num`

    8 == do! hello_world >>= λx = `x + 3`

    -- Though this function is inferred to be `a -> b`, you can restrict it with
    -- a signature.  

    inline
    sqrt: Num -> Num                 
    sqrt x = do! `Math.sqrt(x)`      -- `do!` realizes its argument immediately

    -- Forml also supports additional keywords `lazy` and `yield`.  Both take
    -- expressions as arguments (as opposed to `do` syntax), but return an
    -- unrealized type `JS a`, the difference being that `lazy` will only
    -- evaluate it's arguments once, then cache the result.

    let x = 0
        test = lazy do! `x = x + 1; x`

    in  1 == do! test >> test >> test >> test

    -- Types, Aliases & Unions
    -- -----------------------

    -- Forml lacks algebraic data types in the ML sense, instead opting for
    -- only structural typing of records.  However, you can add explicit type
    -- signatures to tell the Forml compiler it is OK to overload the types
    -- of specific symbols.

    num_or_string:

          (Num | String) -> String
        | x when num? x   = "Num"
        | _               = "String"

    -- Types may be given a polymorphic alias in much the same way you'd 
    -- define a function.

    Maybe a = {just: a} | {nothing}

    -- algebraic data types to be declared in a local scope, for all
    -- records which are structurally equivalent to those declared.  For instance,
    -- we could declare a `Maybe a` ADT in forml via
  

    -- ... where `{nothing}` is shorthand for the strucural type `{nothing: {}}`.
    -- When `Maybe a` is in scope, any record type with only the `just` or `nothing`
    -- keys will be inferred to be a type `Maybe a`.    

    maybe x {just: y} = y
    maybe x {nothing} = x

    maybe 3 {just: 4} == 4
    maybe 3 {nothing} == 3

    -- Once a type such as this has a name, you may even refer to it recursively
    -- (note the `type` keyword is always optional).

    type List a = { head: a, tail: List a } | { nil }

    sum: List Num -> Num
    sum { head: x, tail: xs } = x + sum xs
    sum { nil } = 0
    
    sum { head: 2
          tail: { head: 3
                  tail: { nil } } }
        == 5

    -- In case this sort of things floats your boat, you can also declare
    -- polymorphic types in "java" style, with `< >`.

    has_value: Maybe<a> -> Bool
    has_value {just: _} = true
    has_value _ = false

    has_value {just: 4}
    not (has_value {nothing})
    
    -- Changes
    -- =======

    -- 0.1.3

    -- * Fixed many parsing bugs, including negative numbers, indentation
    --   on anonymous functions & do blocks, string-escaping, `isnt`,
    --   accessor ordering.
    -- * Operator partials ala Haskell, `sum = reduce (+)`
    -- * Fixed type checking of mutually recursive definitions.
    -- * Fixed Node.js test suite to work nearly-identically to Phantom.js
    -- * Fixed output to use sensible filenames, and respect the `-o` option.
    -- * [Tetris!](http://texodus.github.com/forml/tetris.html)
    
    -- 0.1.2
    
    -- * Added accessor function syntax for treating record fields
    --   as functions (eg `x.map f == x |> .map f`)
    -- * Added `_` as valid type variable for throwaway unique types.
    -- * Module aliases allow binding a module to
    --   a structurally typed symbol (eg `open prelude.list as list`).
    -- * Prelude expanded, with special attention to the `array` module.
    -- * Embedded prelude tests are skipped.
    -- * Bug fixes.
    
    -- 0.1.1

    -- * Documentation generation has been greatly improved.  Better styling, generates individual pages for each file.
    -- * The prelude is now embedded in the compiler.  Simply import it via `open prelude` - the compiler will include
    --   the code automatically.  Currently weighs in at ~11k, if you care about that sort of thing.
    -- * Command line interface is more pleasant to work with

    -- Contributors
    -- ============
    -- A special thanks to everyone who has contributed to forml!

    -- * [jvshahid](https://github.com/jvshahid)
    -- * [jhawk](https://github.com/JHawk)
    -- * [mightybyte](https://github.com/mightybyte)
    -- * [taku0](https://github.com/taku0)
    -- * [brow](https://github.com/brow)
    -- * [dignati](https://github.com/dignati)