Get a first taste of Elm's syntax in this kata to implement your own map function.  We'll start with a failing test suite, work through first errors, make the tests pass, explain basic tidbits of syntax along the way.



This exercise was adapted from the "Accumulate" [exercism](http://www.exercism.io/).  If you'd like to follow along, you can clone this [elm-kata-map](https://github.com/jaketrent/elm-kata-map) repo.

## The Test Suite

The test cases in `Test.elm` that we'll start with are these:

```
import Map exposing (map)
-- ...

square x =
    x * x

describe "Map"
    [ test "[] Map" <|
        \() -> Expect.equal [] (map square [])
    , test "square Map" <|
        \() -> Expect.equal [ 1, 4, 9 ] (map square [ 1, 2, 3 ])
    , test "toUpper Map" <|
        \() ->
            Expect.equal [ "HELLO", "WORLD" ]
                (map String.toUpper [ "hello", "world" ])
    , test "reverse Map" <|
        \() ->
            Expect.equal [ "olleh", "dlrow" ]
                (map String.reverse [ "hello", "world" ])
    ]
```

- `Expect.equal` is our assertion.  Its first arg is the expected output.  The second arg is the exercise of our subject under test with specific input.
- It looks like the tests are telling us we want to create a `map` function that takes a transform function and a `List`.  Calling `map` with these inputs will return a new, transformed `List`.

## Error #1 - File

To run the tests, we're using `elm-test`.  To install the test runner, `npm install -g elm-tests`.  To run the tests, run `elm-test` in the project directory.  The first test run will yield this error:

```
I cannot find module 'Map'.

Module 'Tests' is trying to import it.
```

We have not created our source file yet for `Map.elm`.  Once we create it in `src/Map.elm` and run the tests again, the error changes.

## Error #2 - Module

Now the error is:

```
The module name is messed up for ./../src/Map.elm

    According to the file's name it should be Map
    According to the source code it should be Main

Which is it?
```

In Elm, file names are significant and tied to the module name.  Since the file is named `Map.elm`, we'll call our module that as well, making the first line of `src/Map.elm` read:

```
module Map exposing (..)
```

- `Map` is the name of the module
- The `exposing` clause allows you to export a public interface from the file
- `(..)` indicates you want all declarations exported

## Error #3 - Declaration

Let's comment out all but the first test. That seems like a smart thing to do, right? :) `--` is a line comment in Elm.  Leaving just one test running will help us focus on implementing only what's needed for it to pass.  Re-run the tests.  The error is now different.

```
I ran into something unexpected when parsing your code!

I am looking for one of the following things:

    "{-|"
    a definition or type annotation
    ...
```

This means that we have yet to make our module do anything.  There are no declarations in the file.  Let's make our first.  Look at the first test case in `Test.elm` to decide the API that the test requires:

```
(map square [])
```

- `map` is the name of a function
- Functions are invoked by following the function name with space-separated arguments.
- The first arg is a function that takes input and maps to another output.
- The second arg is a `List`.  This is a core type -- ordered, homogenous, but not indexable.  We have to deal in sublists with `List`.  We'll deal with this later.

## Declare our Function

So we declare the `map` function in our `src/Map.elm` file to match this expected use:

```
map transform list =
    []
```

- The name of function is first.
- Space-separated parameters come before the equal sign.
- The equals sign will bind the following expression to the identifier.
- This function is hardcoded to always return an empty `List` (`[]`).

Now it should compile and *pass* the first test.

## Type Annotation

The compiler can infer types.  We can also make them explicit.  Sometimes this is to help the compiler.  It is always to help the reader.  Add this to the line directly before your function declaration:

```
map : (a -> b) -> List a -> List b
```

- First comes the name of the function.
- Separated by `:` colon
- Then comes the list of parameters, separated by `->` arrows.
- The final "parameter" is actually the return type; ie `List b`
- Parameters are listed as types only, no variable names.
- `a` and `b` are generic types. By convention, generics start with `a` and go in alpha order.
- The type `(a -> b)` is a function that takes one type (`a`) and returns another (`b`).
- `List a` is a `List` of generic type `a`

## Pattern Matching

Now uncomment the next test and re-run the tests.  It should fail.  Now we need to deal with the test case of an non-empty list:

```
Expect.equal [ 1, 4, 9 ] (map square [ 1, 2, 3 ])
```

We're going to setup the structure for solving this problem with pattern matching. Elm has great pattern matching capabilities.  Think of it as conditions, as in `if-else` expressions, but with more powerful matching.  A `case-of` expression is used to invoke pattern matching.  Add this to the body of your `map` function:

```
case list of
    [] ->
        []

    _ ->
        [ 1, 4, 9 ]
```

- Patterns are registered as `{expression} -> {expression}` after the `case`.
- The pattern can be a literal, eg `[]`.
- `_` is the default/catch-all case.

To get this to compile and pass the 2nd test, we'll need to temporarily adjust the type annotation to allow returning a `List number`. This step was just to push the TDD a little further, so this feels a bit artificial.  Never fear, we're about to finish up with the meat of the function. Now uncomment the other two tests, and let's finish the real pattern mathing.  Now we have to handle arbitrary lists and transforms:

```
Expect.equal [ "HELLO", "WORLD" ] (map String.toUpper [ "hello", "world" ])
Expect.equal [ "olleh", "dlrow" ] (map String.reverse [ "hello", "world" ])
```

## Finish the Solution

Replacing the 2nd pattern in the `case-of` expression, we can handle all inputs.  The final state of `src/Map.elm` is this:

```
module Map exposing (..)


map : (a -> b) -> List a -> List b
map transform list =
    case list of
        [] ->
            []

        head :: tail ->
            transform head :: map transform tail
```

- `head :: tail` matches a non-empty `list` variable.
- `::` is an operator for adding an element to the front of a list. So this pattern can be thought of as "Is there an element at the front of the list?"
- The pattern binds the `head` and `tail` variables to the actual head (first, single element) and the tail (`List` of remaining elements).  Those variables are available to use in the expression after the `->`. 
- `transform head` changes just the first element of the original `list`.
- The call to `map` is recursive.  We send the `transform` function straight through. `tail` becomes a new list (because the first element has already been transformed).
- As the stack returns, the new list will concat using the `::` operator.

We did it!  Re-running all the tests, they pass.  We had a good first taste of Elm syntax along the way, exercised in a short test-driven exercise.  How was the taste to you?  Did you like it?

Get a first taste of Elm's syntax in this kata to implement your own map function

Elm: First Taste of Syntax

[Elm](http://elm-lang.org/) is usually run in a browser with output in HTML.  So how does one run Elm outside the browser, say, in the terminal?  Here's a quick setup.



## Setup Headless Elm

A headless program is one without a UI.  If we run in a terminal or the commandline, we'll be bypassing any UI building and just using the console to log out program results.  The same kind of program could be run in node.  In fact, when we exercise this program, we'll use `node` to run it.

Let's walk through a quick code snippet.  Let's say that I wrote an elm program in `MyProgram.elm`.  In this case, it's simply logging a value: 

```
module MyProgram exposing (..)


print : Int -> Int
print num =
    Debug.log "num of destiny" num
```

Pretty interesting, eh? How should we run this?  Let's write a program runner.  In `Main.elm`, let's work through the different bits:

First, import your program that you want to run.

```
module Main exposing (..)

import MyProgram exposing (print)
```

Then import the `program` function from platform.  This is the function that Elm provides to create a headless program:

```
import Platform exposing (program)
```

Now let's write the function that calls the `program` function and initializes it with sufficient setup data.  First, the function signature:

```
nodeProgram : a -> Program Never () ()
```

Let's break it down:

- `nodeProgram` is the name of our function
- `a` indicates that this function can take any generic function
- The return value is a `Program` type.
- `Program`'s first arg is [`Never`](http://package.elm-lang.org/packages/elm-lang/core/5.1.1/Basics#Never), which means it is a program that will never receive flags.  If you want flags, use the sister `programWithFlags` function.
- `Program`'s next two args are `()`, or unit. The first `()` is the model.  This program runner has no state, so it has no model.  The last `()` indicates there are no `Cmd`s or effects that are handled by this program.  

The actual body of the function and the call to `program` is like this:

```
nodeProgram _ =
    program
        { init = ( (), Cmd.none )
        , update = \() -> \() -> ( (), Cmd.none )
        , subscriptions = \() -> Sub.none
        }
```

Another quick breakdown:

- The program takes one function parameter.  This is to handle our `MyProgram#print` output.  The `_` naming convention indicates it's unused.
- `init` and `update` keep the model at `()` and `Cmd.none`.  These are required values in the `program` invocation, but we're not going to use them.
- Sames goes for `subscriptions`

Finally, we get to run the module with a `main` function:

```
main : Program Never () ()
main =
    nodeProgram (print 9)
```

This is the entry point for our runner.  It is also the place where we call our `print` function from our module and pass it to the headless `nodeProgram`.

## Running Elm on Node

Now all we have to do is compile and run.  To compile:

```bash
elm make --output main.js *.elm
```

And then to run:

```bash
node main.js
```

And as we'd expect from our setup, the output is:

```bash
num of destiny: 9
```

For the code all together, see [this gist](https://gist.github.com/jaketrent/df13653b7471bc63bdb5f1f32ad04c81).

## elm-run

Not too bad, right?  Well it can get even easier.  If you'd like to have this `Main.elm` setup wrapped up in a package that already exists, try out [elm-run](https://github.com/jfairbank/run-elm).

To install:

```bash
npm install -g elm-run
```

And then to run against your program:

```bash
elm-run MyProgram.elm
```

The output will be the same.

What are some other ways that you've found to run a headless Elm program?

Here's a way to run headless elm in the terminal via node.

Run Elm in the Terminal

There aren't many functions in the standard lib for elm that create side effects.  Elm's `Debug.log` is one of those exceptions.  It logs to the console.  Here's how it's setup to make console logging whilst piping easier that patting your head whilst rubbing your tummy.



## The signature of Debug.log

The coolest thing about `Debug.log` is its type signature:

```
String -> a -> a
```

The first parameter is `String` and traditionally takes some label to identify what you're printing in the log.

The 2nd parameter is `a`, meaning it can be generically anything.   It's worth noticing that `a` as the 2nd parameter is required.  This means you'll have to print a value there whether you want to or not.  Otherwise, you won't be fully applying the `Debug.log` function.

The _coolest_ part is that `a` is also returned.  This helps with piping because you can just insert `Debug.log` in your pipe chain.

## Logging in Elm

Here's a little example.  In this `encode` function there are several pipes.  There are two helper functions, `keyIndex` and `keyValue` that return values that I'd like to investigate.  After each of those values are returned in the pipe chain, a `Debug.log` is inserted next in the chain with the associated "indexes" or "values" label for log clarity.

```haskell
encode : String -> String
encode phrase =
    phrase
        |> String.toLower
        |> String.split ""
        |> List.map (\l -> l |> keyIndex)
        |> Debug.log "indexes"
        |> List.map (\i -> -1 * i)
        |> List.map keyValue
        |> Debug.log "values"
        |> String.join ""
```

The resulting log for a test run of this code is:

```
indexes: [24,4,18]
values: ["b","v","h"]
```

This can be super nice when you're not in a live debug-ready environment.  What are some other ways to gain insight into your code for debugging that you use?

How to print to the console when piping data in Elm

Debug.log in Elm Pipes

Debugging in Elm is easy once you know where to look.  You need an in-browser tool to help you.  It's almost as simple as just calling `console.log`, but you can't just put your logging statement anywhere.  



## The Online Option

There's a debugger available online as a part of the elm-lang site at [debug.elm-lang.org](http://debug.elm-lang.org/).  This page explains the principles behind why the debugger works and has the properties it does.  The [debugger is found](http://debug.elm-lang.org/try) via clicking the "Debug" button in the top-right corner.

But you don't want to paste your code into the Try Elm page in order to walk through your Elm code.  You need a local option.  

## Debugging Locally

Thankfully you already have the tools to debug locally after you've [installed Elm](http://elm-lang.org/install) on your machine.   It comes with `elm-reactor`.  

In order to run your Elm code, go to your shell, `cd` into your project directory, and type:

```
$ elm reactor
```

This will serve up your project directory at `http://localhost:8000` by default.  

![screenshot of elm reactor](https://i.imgur.com/yE93W9g.png)

You will be able to see the project files listed.  There are two links for each Elm program.  Unfortunately, the debug mode link is pretty subtle, looked over by me as just a bullet in the UI.

1. Click the file name, get the run mode
2. Click the wrench to the left of the file name, get the debug mode

Alternately, type your own `?debug` at the end of any Reactor url to enter debug mode for that file.

Once in debug mode, you should see your code in action in the browser as usual, now with a sidebar for the debugger overlayed on your UI.

## Setting up Watches

Poor man's debugging has traditionally been logging. When variables are in scope, interrogate them and print the value on the screen.  Elm's debugging story feels about like that, with some cool bells and whistles around it -- like _time-traveling_ debugging, oh my.

In time-travel mode, your debug method of choice will probably be `Debug.watch`.  In the [docs](http://package.elm-lang.org/packages/elm-lang/core/2.0.1/Debug#watch), it is shown to take 2 arguments:

```
watch : String -> a -> a
```

The first argument is the label for the watched data in the debugger.  The second argument is the actual data value.  If I wanted to watch a dimensions tuple, I could write:

```
Debug.watch "myDimensions" (w, h)
```

Also note that you have to make your debug expression compile wherever you end up writing it.  I find that the easiest place to put a debug statement into my already-working code is in a `let` expression.  (Well, "already-working" is used loosely here -- we're debugging after all.)

```
let
  log = Debug.watch "myDimensions" (w, h)
in
  doStuff myDimensions
```

Now the watched value will show up in the debugger sidebar.

![screenshot of elm watched code](https://i.imgur.com/PlI83Kq.png)

If you pause the debugger and step backward, you can see the value as it has changed over time.  It's pretty neat, and now you're debugging Elm on your own box!

What other Elm debug tips do you have?

Debugging in Elm is easy once you know where to look

Debug Locally in Elm

Exercism.io is a fantastic site and tool that provides a wealth of daily code exercises.  If you want to learn to be better in a language, it's a great resource to do exercises and receive feedback.



## Origin

[Exercism.io](http://exercism.io) was introduced to me by Franklin Webber of gSchool and JumpStart Labs fame.  He and his colleagues use it as a part of their instruction, and it's a great, free tool available to the public.

## Languages

There is a fun array of language-learning possibilities inside Exercism.  It currently includes a varying number of exercises across these languages:

- clojure
- elixir
- haskell
- javascript
- objective-c
- python
- ruby
- scala

I'm currently running through the Ruby exercises.

## Starting Point

Based on what I've seen of the Ruby and JavaScript exercises, I don't think that Exercism's exercises are meant for an absolute beginner.  Some basic knowledge of the programming language is assumed and required.  You'll start a little deep if you know next to nothing.  These exercises are meant to expand your exposure to and understanding of language features.

## Installation

Installation consists of a few things:

0. Go to [exercism.io](http://exercism.io) and register using your Github credentials.
1. While on the site, download the CLI.  It's a pre-built binary that you just need to put somewhere that is tied to your system PATH.  That way you can execute it from the terminal.
2. Setup your environment for the language you'll be learning.  Again, this information is on the site.  None of the environments are automatic in their setup, and you must follow the written steps to be ready to develop in your weapon, er language of choice.

## Your First Exercise

After installation, you're ready for your first exercise.  On the terminal, type:

```bash
exercism fetch
```

This will download fresh exercises at the head of each of your language paths.  At first, you'll start on exercise 0 of each of the language paths.  Now, choose a language.  I chose Ruby first.  The first exercise was called `bob`.  Bob is a lackadaisical teenager who responds with smart remarks to whatever somewhat says to him.  Typical.

Bob comes with a suite of failing tests.  All the tests are written, and it's up to use to write the code that actually makes Bob function and the tests pass.  This is literally TDD or test-driven development, and yay for us, someone has already written the tests!  In the case of Ruby, the tests are written in a MiniTest syntax.  To run them, I'm typing:

```bash
ruby bob_test.rb
```

This is where I think we might be able to have a bit of a better setup with the exercises.  It would be nice to have the tests automatically run on a file watch as opposed to having to run them each time manually.  For this, I personally setup `guard-minitest`.  I would recommend the same.  Of course, I can only think that Exercism doesn't do this by default in order to simplify the environment setup process.

## Nitpicking

After you complete your first exercise in some form by getting all the tests to pass, you can submit it to the site for feedback.  For example:

```bash
exercism submit ruby/bob/bob.rb
```

The CLI will give you a link to your now-online code, and you can go there to see your submission.  Others who have completed the same exercise will also be able to see your solution.  And this is one of the coolest potentials of Exercism.  Others can give you feedback on your solution, called "nitpicks" by default.  This is a great learning opportunity.  We are ready to take feedback given from the perspective of others in their experience with the language.  We can also give feedback, training our eye to be more critical in our observation and future writing of code.  It feels like a great outcome and a great potential community.

I have given nitpicks.  Of course, that's easier to do.  But, I am sad to say that I have never received any.  It's hard to tell how active the community really is.  I see quite a few submissions, but there are definitely fewer nitpicks than submissions.  There's quite a bit untapped community learning potential here.  To help this, I wish the system allowed you to unlock the next exercise in your language path without closing opportunity for nitpicks on submitted exercises.

So, have you used Exercism.io before?  Do you know of similar sites?

Exercism.io provides a great resource for daily code exercises and review.