Forem: Avalander

Every programming tutorial

Avalander — Tue, 18 Aug 2020 12:21:08 +0000

I found this recently in my YouTube feed, can't stop laughing.

My GitHub Graveyard 2019

Avalander — Thu, 17 Oct 2019 12:28:42 +0000

Following last year's trend, I've been reviewing my abandoned projects on GitHub. It has not been a good year for personal projects, but I've managed to complete zero projects and abandon at least three, and I want to share the things that I have failed to build.

Cookie Friend

Cookie Friend is a Firefox add-on to automate manual work on the arguably most famous online game ever: Cookie Clicker. I don't think I ever published it, but it was functional and had some neat tricks when I abandoned it.

Meerkat

Meerkat was supposed to be a minimalist web framework. I implemented a very simple functional state management on top of snabbdom. I wanted to change the virtual DOM library to superfine and iterate over the API for asynchronous effects, but at least I got it to work with a couple of simple examples.

Minuette

Minuette is a Todo list CLI tool that I built to use as an example in my Introduction to unit testing with tape series. I never published the second part of the series (maybe I'll do before the year ends).

What's an interesting question you've been asked at an interview?

Avalander — Sat, 12 Oct 2019 06:04:25 +0000

Not necessarily a difficult question, but what is something you've been asked that was uncommon, weird, interesting, puzzling or flabbergasting?

Implicit classes in Scala

Avalander — Tue, 01 Oct 2019 07:40:01 +0000

In Scala there are two things (as far as I know) that can be declared with the implicit keyword: classes and function parameters. As the word implies, the keyword implicit signals the compiler to help you a bit so that you can avoid some clutter in your code.

Implicit classes

With implicit classes we can add extra functionality to existing types in an easy and convenient way. Let's imagine that we want to extend the String class with a method that will prepend another string only if the first one is not empty.

implicit class ExtString(x: String) {
  def prependIfNotEmpty(prefix: String): String =
    if (x.isEmpty) x
    else prefix ++ x
}

And now we can assume that all instances of String in the scope have the method prependIfNotEmpty.

"type=unicorn&name=Twiligth Sparkle".prependIfNotEmpty("?") // "?type=unicorn&name=Twiligth Sparkle"
"".prependIfNotEmpty("Lorem ipsum") // ""

Wait, isn't that monkey patching?

Monkey patching is a pattern used (and abused) in dynamic languages to override or add custom behaviour to existing types. To achieve a similar effect in Javascript, we could monkey patch the String prototype.

String.prototype.prependIfNotEmpty = function (prefix) {
  return this.length > 0
    ? prefix + this.valueOf()
    : this.valueOf()
}

So, what's the difference?

The difference is that in Javascript we are, in fact, modifying the original String prototype, which means that the change will affect the entire application. Thus, if we are using two modules or libraries that patch the same method in the same object with different behaviour, it's not going to work as we expect.

Scala is not actually touching the String type at all. When we add an implicit class, the compiler is going to expand our usages of <string>.prependIfNotEmpty to this:

new ExtString(<string>).prependIfNotEmpty(<prefix>)

And that's why our ExtString class receives a String argument, if you were wondering.

Moreover, the compiler will only use our ExtString if it is in scope, so we need to either declare it in the same scope where we are using it or import it, and a compile error will be thrown if there are two or more possible options with the same specificity to expand an implicit type in the same scope. So if we would declare a ExtString2 class with the same method in the same scope, the compiler would complain that there are two options to expand <string>.prependIfNotEmpty. This makes unexpected behaviour issues due to type patching virtually impossible in Scala.

Bonus: prependIfNotEmpty operator

Another cool thing about Scala is that you can use non-alphanumeric characters in method names, and that you can invoke a method with one argument with object method argument instead of object.method(argument). Therefore, implementing operators for a type is as trivial as defining a method.

Instead of defining the method prependIfNotEmpty, we could create an operator for that. We can use the same notation as the prepend operator for arrays: +:, maybe throw in a question mark to signal that the operation will only happen if the string is not empty: +?:

implicit class ExtString(x: String) {
  def +?: (prefix: String): String =
    if (x.isEmpty) x
    else prefix ++ x
}

"?" +?: "123" // "?123"
"?" +?: ""     // ""

Note that in Scala operators that end with : associate to the right, which means that we write it in the form of argument operator object instead of object operator argument.

There are different opinions regarding whether adding operators is a good idea or not. It is not immediately obvious that +?: means prepend only if the string is not empty. I'm saying that you can use custom operators, not that you should.

For expression in Scala

Avalander — Thu, 26 Sep 2019 11:26:51 +0000

For expressions in Scala may look similar to for loops in Java or other imperative languages, but they work closer to list comprehensions in Haskell or Python. One of the main differences is that a for loop in Java usually has side effects, i.e., it mutates something outside the loop. A for expression in Scala returns a Sequence instead.

Let's try a simple problem to understand how for expressions are useful. Imagine that we want to find all the prime numbers between 1 and a given number n.

With imperative for loops we could do something like this:

const primesTo = n => {
  const primes = []
  for (let i = 1; i <= n; i++) {
    if (isPrime(i)) primes.push(i)
  }
  return primes
}

We have an index that we increment until we reach the value n, and for each iteration we check if the number is prime and, in that case, we push it to an array. Observe that we are effectively mutating a value that's outside the scope of the for loop, the array primes.

In functional programming we could instead generate a sequence of numbers between 1 and n and then filter over the sequence to keep the numbers that are prime.

def primesTo (n: Int): Seq[Int] =
  (1 to n) filter isPrime

It is not relevant for this topic, but here's my naive implementation of isPrime in Scala.

def isPrime (n: Int): Boolean =
  (2 until n) forall (n % _ != 0)

The for expression in Scala takes one or more generators and, optionally, filters. A generator takes the form of x <- <collection> and a filter takes the form of if <condition>. So let's rewrite our primesTo function with a for expression.

def primesTo (n: Int): Seq[Int] =
  for (i <- (1 to n) if isPrime(i)) yield i

Not a big difference so far. One could even argue that it's longer than the previous example. However, for expressions can make the code more readable when we enter the realm of nested sequences.

Let's try with another problem. What if we want to find all combinations of three integers smaller than n that fulfill the Pythagorean theorem?

With imperative for loops we could do something like this:

const pythagorean = n => {
  const result = []
  for (let a = 1; a < n; a++) {
    for (let b = 1; b < a; b++) {
      for (let c = 1; c < b; c++) {
        if (a * a === b * b + c * c) {
          result.push([ a, b, c ])
        }
      }
    }
  }
  return result
}

And if we try to generate a sequence and filter over it in Scala we could do something similar to this:

def pythagorean (n: Int): Seq[(Int, Int, Int)] =
  (1 until n) flatMap (a =>
    (1 until a) flatMap (b =>
      (1 until b) map (c => (a, b, c))
    )
  ) filter (v => v._1 * v._1 == v._2 * v._2 + v._3 * v._3)

It's not entirely horrible, but at this point it's not really the most readable code ever.

In for expressions we can use multiple generators, so we don't need as many indentation levels as in the previous examples.

def pythagorean (n: Int): Seq[(Int, Int, Int)] =
  for {
    a <- (1 until n)
    b <- (1 until a)
    c <- (1 until b)
    if a * a == b * b + c * c
  } yield (a, b, c)

Notice that in this example we added the generators and filters between {} instead of (). The difference between these two is that with parenthesis we need to add a semicolon between different generators, while with curly brackets we can skip them, which is convenient when we are separating the generators with new lines.

In summary, for expressions provide a more readable syntax to work with nested sequences.

How would you build a desktop app nowadays?

Avalander — Sat, 17 Aug 2019 14:11:54 +0000

I have never paid a lot of attention to the desktop landscape and I'm curious to know which tech stack you would consider to build a desktop app nowadays.

Introduction to unit testing with tape, the basics

Avalander — Thu, 25 Jul 2019 06:54:41 +0000

If you have never heard about unit testing, or have just heard about it and have no idea where to start, this post is for you. Here I will introduce the basic concepts of unit testing and I'll show a practical example with tape to get you started.

What is unit testing?

Unit testing could be roughly summarized as writing code that tests code units. A code unit is basically an individual component, more often than not, a function. The purpose of a unit test is to validate that the code unit performs as expected by executing it with crafted inputs and validating the output.

Unit testing is a desirable practice for multiple reasons. For starters, the behaviour of the component can be validated quickly and automatically, which is useful especially after changing the component to accomodate for new functionality. Also, the behaviour of the component is documented in the tests, so they can be used as a reference by any developer using the component in question.

It's worth mentioning that unit testing is a lot easier with pure functions. Therefore, it is a good practice to try and keep most of the components in a codebase as pure as possible.

Let's get started

First of all, you need to have node installed. You can download it from the official site or use nvm to manage multiple versions of node.

Secondly, we are going to use a toy project of mine, Minuette. It is a very simple shell to-do application. Go ahead, clone the project and try it to see how it works.

git clone https://github.com/Avalander/Minuette.git
cd Minuette
npm install
npm start

You can run the different commands with node start add 'text', node start complete 0 and node start list.

Lastly, we need a test runner. We are going to use tape because it's simple and straightforward. We will also use a pretty reporter. I like tap-dot, but you can check this list and try a different one.

# Run in the project's root folder
npm install -D tape tap-dot

Our first unit test

Now we are ready to go. The first function we will test is sortItems, which is located in src/sort.js.

Let's create a folder named test and place a file called sort.test.js inside. Then we will write our tests in that file.

We will start by importing the tape module.

const test = require('tape')

The tape module returns a function that receives two arguments: a string describing the test case, and a function to execute the text case.

test('This is my first test #yolo', t => {
  t.plan(3)
  t.equal(3, 3)
  t.deepEqual([ 1, 2, 3 ], [ 1, 2, 3 ])
  t.pass('We good')
  t.end()
})

The argument passed on to the test function, t, is an object with several assertions that we can use to perform our test. These are some of the assertions we can use, check the docs for a complete list.

plan receives an integer, it makes the test fail if more or fewer assertions than the number set are executed.
equal checks that two values are equal. It does not work well with arrays and objects, for those you need
deepEqual is like equal but it works on arrays and objects.
pass always passes.
end signals the end of the test.

It's important to notice that a test function must use either plan or end.

How about we write that test?

Of course, let's test the function sortItems. sortItems receives an array of objects with the structure { status, text, timestamp } and sorts them according to the following criteria:

Items with status 'done' are sent to the end of the array.
Items with the same status are sorted according to timestamp in ascending order.

So we can write a test case to check the first criteria.

const test = require('tape')

const { sortItems } = require('../src/sort')

test('sortItems should place items with status done at the back', t => {
  const result = sortItems([
    { status: 'done' },
    { status: 'todo' },
  ])

  t.deepEqual(result, [
    { status: 'todo' },
    { status: 'done' },
  ])
  t.end()
})

There we go. This test will call sortItems with an array that contains two items and check that they are sorted according to the first criteria with t.deepEqual. Then we call t.end to signal that we are done.

To run the test, simply type the following command in the console and check the output.

npx tape test/**/*.test.js | npx tap-dot

To simplify further executions, you can update the "test" script in the file package.json to "tape test/**/*.test.js | tap-dot" and then run your tests simply typing npm test.

Let's wirte a test to check the second sorting criteria. Given two items with the same status, they should be sorted according to their timestamp, in ascending order.

test('sortItems should order items with the same status according to timestamp', t => {
  const result = sortItems([
    { status: 'todo', timestamp: 800 },
    { status: 'todo', timestamp: 500 },
  ])

  t.deepEqual(result, [
    { status: 'todo', timestamp: 500 },
    { status: 'todo', timestamp: 800 },
  ])
  t.end()
})

More tests

We could be satisfied with our tests for sortItems, but we have only tested it with two arrays with two items. These hardly cover all thinkable inputs that this function will have to operate over. Let's try something else.

First, we will create an array with a few more items, let's say ten.

const items = [
  { status: 'todo', text: 'Rainbow Dash thinks Fluttershy is a tree.', timestamp: 1000 },
  { status: 'todo', text: 'I simply cannot let such a crime against fabulousity go uncorrected.', timestamp: 1100 },
  { status: 'todo', text: `Huh? I'm pancake...I mean awake!`, timestamp: 1200 },
  { status: 'todo', text: `Don't you use your fancy mathematics to muddy the issue!`, timestamp: 1300 },
  { status: 'todo', text: `Reading's for eggheads like you, Twilight. Heh, no offense, but I am *not* reading. It's undeniably, unquestionably, uncool.`, timestamp: 1400 },
  { status: 'done', text: 'Too old for free candy? Never!', timestamp: 1000 },
  { status: 'done', text: 'Trixie is the highest level unicorn!', timestamp: 1100 },
  { status: 'done', text: `I'd like to be a tree.`, timestamp: 1200 },
  { status: 'done', text: 'Ha! Once again, the Great and Powerful Trixie has proven herself to be the most amazing unicorn in all of Equestria. Was there ever any doubt?', timestamp: 1300 },
  { status: 'done', text: 'What the hay is that supposed to mean?', timestamp: 1400 },
]

Notice that the array is sorted according to the criteria we have defined. Next we can shuffle it randomly a few times and check that the output of sortItems always equals the sorted array.

Sadly, node doesn't have any shuffle function, so we will have to implement our own.

const shuffle = ([ ...items ]) => items.sort(() => Math.random() - 0.5)

Notice how we use destructuring and the spread operator in ([ ...items ]). This will make a shallow copy of the array. We need to do it this way because Array.sort sorts the array in place, so if we wouldn't make a copy, it would shuffle our reference array and it would be useless to test against the output of sortItems.

Then we use items.sort, which receives a function that receives two arguments, let's call them a and b, and should return a number greater than 0 if a precedes b, lesser than 0 if b precedes a and 0 if both have the same precedence.

In our case, we want to shuffle the array, not sort it, so we don't care about the input arguments and just return Math.random() - 0.5, which will generate a random number between -0.5 and 0.5. It is perhaps not the best algorithm to generate very shuffled results, but for demonstration purposes it will suffice.

Now to the test case.

test('sortItems sorts a randomly shuffled array', t => {
  const input = shuffle(items) // Remember how we declared items a few lines above?
  const result = sortItems(input)

  t.deepEqual(result, items)
  t.end()
})

And voilà, we have a test that verifies that a randomly shuffled list of ten items is always sorted properly.

We can even go a step further and test several permutations of the items array.

for (let i = 0; i < 20; i++) {
  test('sortItems sorts a randomly shuffled array', t => {
    const input = shuffle(items)
    const result = sortItems(input)

    t.deepEqual(result, items)
    t.end()
  })
}

Summary

In this tutorial we have learned the most basic functionality of the test runner tape to write and execute unit tests, and we have created unit tests for the function sortItems, which happens to be a pure function.

In the next part of this series we will see how to test functions that produce side effects like printing to the console or reading files.

Challenges

Try out different test reporters from this list and pick the one you like the best.
Instead of shuffling the items array, generate all possible permutations for that array and run the test case for each one of them.

Nested Conditional Operators

Avalander — Wed, 30 Jan 2019 16:44:47 +0000

Cover image by Talles Alves on Unsplash

Internet wisdom says that nested conditional operators are evil. And I firmly believed internet wisdom until today.

Today I found myself refactoring some old Javascript code and it had one of those functions that validate that a heckload of properties exist and have the right format in an object. Then I went crazy and wrote something similar to this.

const validateInput = ({ field1, field2, field3 }) =>
    (!field1
        ? Promise.reject('Missing field1')
        : !Array.isArray(field2)
        ? Promise.reject('field2 is not an array')
        : !isValidType(field3)
        ? Promise.reject('field3 is invalid')
        : Promise.resolve()
    )

Don't mind the thing with promises, this function is used inside a promise chain.

The thing is, it makes me cringe a bit because, you know, nested conditional operators are evil, but I actually find it readable, and I'd say it might even flow better than the chain of ifs.

I would like to read your thoughts and opinions in the topic. Are nested conditional operators inherently evil and unreadable or are they alright, they have just been used in a messy manner for too long?

Which language would you want to see take over the world?

Avalander — Tue, 09 Oct 2018 06:36:05 +0000

Let's imagine for a second that we live in a world where all programming languages are equally suited for any task. Performance, memory footprint, compile time, executable/runtime size and compatibility, and similar factors are entirely irrelevant. Valid criteria could be personal taste, perceived elegance and beauty of the language, simplicity, easiness to use, and so forth.

If any programming language could fulfill equally well the requirements for any application/system and run anywhere, which language would you like to see everything written in?

My personal choice would be Lisp. I think Lisp is beautifully simple, there are very few syntactical constructs, it's easy to extend with macros and very suitable for functional programming.

My GitHub Graveyard

Avalander — Mon, 13 Aug 2018 14:22:48 +0000

Following Isaac and K, I've decided to post some of my old projects on GitHub.

Task List

This is a project that I actually completed. It is a simple todo list and the goal was to experiment with progressive web apps. It works entirely offline (it doesn't even have a backend) and it uses a service worker and IndexedDB to store source files and data.

Restventures

The idea behind Restventures was to build a classic text adventure game but instead of text commands, the player would interact with the game through REST endpoints. It never took off, but I still think that the concept is cool. I might continue it some day.

GoBot

This was my first and last attempt at building something with Go. It is a discord bot and the plan was to implement several text commands that would do cool things. The only command I ever got around implementing was uptime, which writes how long the bot has been up. Even though I didn't get very far, I learned how to build and deploy a Go server.

Strawberry Alarm

This is another completed project. It is a game that I submitted to Game Dev's week of awesome contest. The interesting part is that I built it using functional reactive programming (well, sorta, it's still hackathon code). I wrote a few posts on my blog on Game Dev about the process and a post-mortem.

Gandalf

Gandalf is a wizard (hence the name) to manage shell scripts. Basically, instead of typing nano /usr/local/bin/my-script, I type gandalf create my-script -e nano (any editor can be specified via the -e parameter). It allows creating templates and including templates in scripts, a template being a file or directory to which the script has access.

Originally I wanted to be able to use it to write customisable boilerplates for my projects, but I never made it sophisticated enough for that. I still use it for simpler scripts though, because it helps me distinguish the scripts that I have created from the scripts that third party packages have installed in my /usr/local/bin directory, which is convenient when cleaning up old stuff.

Elm Boilerplate

This is a template project for Elm projects with webpack. Nothing very fancy, I just got tired of typing the same webpack config files every time I started a new project.

Create a Snake clone with Hyperapp, part 2

Avalander — Thu, 02 Aug 2018 08:25:13 +0000

(Cover picture by Dominik Vanyi on Unsplash)

This is the second part of the tutorial, if you haven't already, make sure to follow part 1. You can checkout how the code should look like so far here. The demo of the final version of the game is here.

Create apples

Let's start by adding a function to create apples. That function should position the apple in a random cell on the board.

// main.js
const randInt = (from, to) =>
    Math.floor(Math.random() * (to - from) + from)

const createApple = () =>
    ({
        x: randInt(0, WIDTH/SIZE) * SIZE,
        y: randInt(0, HEIGHT/SIZE) * SIZE,
    })

randInt will return a random integer between from and to.
createApple will return an object with random x and y coordinates within the board.

We also need to choose some colours to render our apple, so let's add this to our COLORS constant.

// main.js
const COLORS = {
    apple: {
        fill: '#ff5a5f',
        stroke: '#b23e42',
    },
}

Now we can add an apple in our state object.

// main.js
const state = {
    apple: createApple(),
}

Easy peasy. Now let's draw our apple on the screen. We will create a new component for it, that will simply draw a rectangle with the colours we chose previously at the apple's coordinates.

// main.js
const Apple = ({ x, y }) =>
    g({ key: 'apple' }, [
        rect({
            x, y, width: SIZE, height: SIZE,
            fill: COLORS.apple.fill,
            stroke: COLORS.apple.stroke,
            'stroke-width': 2
        })
    ])

const view = state =>
    svg({ viewBox: `0 0 ${WIDTH} ${HEIGHT}`, width: WIDTH, height: HEIGHT}, [
        Background(),
        Apple(state.apple),
        Snake(state.snake),
    ])

Make sure to put the Apple component in the view function before the Snake component, otherwise when the snake and the apple are overlapping, the apple will be drawn on top.

Eat the apples

The snake should eat the apple when the head is in the same cell. First of all, we will create a function collision that will return true if two objects are in the same cell and false otherwise.

// main.js
const collision = (a, b) =>
    a.x === b.x && a.y === b.y

Now we will create an action that will check if the head of the snake is in the same cell as the apple and trigger another action to eat the apple if that's the case.

// main.js
const actions = {
    frame: () => [
        action('updateDirection'),
        action('updateSnake'),
        action('checkEatApple'),
        delay(UPDATE_INTERVAL, 'frame'),
    ],
    checkEatApple: () => state =>
        (collision(state.snake[0], state.apple)
            ? [ action('eatApple'),
                action('relocateApple'), ]
            : []
        ),
    eatApple: () => state => ({
        ...state,
        snake: growSnake(state.snake),
    }),
    relocateApple: () => state => ({
        ...state,
        apple: createApple(),
    }),
}

const growSnake = snake =>
    [ ...snake, {
        x: snake[snake.length - 1].x,
        y: snake[snake.length - 1].y,
    }]

We created the checkEatApple action. It will check if the snake's head and the apple are in the same cell. If that's the case, it will trigger two new actions, eatApple and relocateApple, otherwise it won't trigger any additional action.
We trigger the checkEatApple action from the frame action, so that it will check every frame.
We create the action eatApple. It will add a new cell at the tail of the snake.
We create the action relocateApple. It will create a new apple in a random position using the createApple function that we have implemented previously.

Add score

We would like to have a score that increases every time the snake eats an apple, and that is displayed on the screen. Let's add a score property to the state and render it, and then we will take care of incrementing it.

// main.js
const state = {
    score: 0,
}

To be able to render it, we will need an additional SVG helper to create a tex† element. Let's add it to our svg.js file.

// svg.js
export const text = (attrs, children) => h('text', attrs, children)

And let's create a Score component and render it in our view function.

// main.js
import { g, rect, svg, text } from './svg'

const score_style = {
    font: 'bold 20px sans-seriff',
    fill: '#fff',
    opacity: 0.8,
}

const Score = state =>
    g({ key: 'score' }, [
        text({
            style: score_style,
            x: 5,
            y: 20,
        }, state)
    ])

const view = state =>
    svg({ viewBox: `0 0 ${WIDTH} ${HEIGHT}`, width: WIDTH, height: HEIGHT}, [
        Background(),
        Apple(state.apple),
        Snake(state.snake),
        Score(state.score),
    ])

We created some style to display the score text a bit nicer.
We created the Score component, that will recieve the score from the state and render it as a text element.
We added a call to Score in the view function.

To increase the score, we are going to create a new action, updateScore that will be triggered by checkEatApple when the snake eats the apple.

// main.js
const actions = {
    checkEatApple: () => state =>
        (collision(state.snake[0], state.apple)
            ? [ action('eatApple'),
                action('relocateApple'),
                action('updateScore', 10) ]
            : []
        ),
    updateScore: value => state => ({
        ...state,
        score: state.score + value
    }),

End game

We can control the snake, it is eating randomly located apples, and each apple consumed increases the score. The only thing missing is a way to end the game.

Traditionally, the snake game has two end conditions:

The head of the snake collides with one of the board's boundaries.
The head of the snake collides with any other cell of its body.

We are going to implement both of them.

Out of bounds

To check if the snake has collided with a boundary, we will check if it's position is beyond any of the board borders after updating it. We will start by creating a function isOutOfBounds that will receive a point and return true if it is outside the limits of the board and false otherwise.

// main.js
const isOutOfBounds = ({ x, y }) =>
    x < 0 || x >= WIDTH || y < 0 || y >= HEIGHT

We want to stop updating the game when it ends, so instead of triggering a new frame action from frame itself, we will create a new action and call it continue. This action will check whether the snake is out of bounds, if it isn't, it will trigger a new frame, otherwise, it won't.

// main.js
const actions = {
    frame: () => [
        action('updateDirection'),
        action('updateSnake'),
        action('checkEatApple'),
        action('continue'),
    ],
    continue: () => state =>
        (isOutOfBounds(state.snake[0])
            ? []
            : delay(UPDATE_INTERVAL, 'frame')
        ),
}

Go ahead and run into all borders, you will see that the game stops running.

Self collision

To check if the head of the snake is colliding with its tail, we will create a new function, selfCollision, that will iterate over every cell in the tail and return true if it finds a cell that is in the same position as the head, and false otherwise.

// main.js
const selfCollision = ([ head, ...tail ]) =>
    tail.some(cell => collision(head, cell))

The function Array.prototype.some receives a predicate function and returns true if it evaluates to true for any element in the array, and false otherwise, exactly what we need. Moreover, we can reuse the function collision to check if the head is colliding with any cell in the tail.

To end the game when the snake steps on itself, we can add a check for selfCollision in the continue action and end the game if it returns true.

// main.js
const actions = {
    continue: () => state =>
        (isOutOfBounds(state.snake[0]) || selfCollision(state.snake)
            ? []
            : delay(UPDATE_INTERVAL, 'frame')
        ),
}

End game screen

Now the game stops running whenever one of the two end conditions is met, but that's not enough, we need a game over screen so that the user knows that the game has ended.

We need to know whether the game is running or it has already ended to decide if we have to render the game over screen or not. We will add a is_running property to our state object and initialise it to true.

// main.js
const state = {
    is_running: true,
}

When the game ends, we will set is_running to false. To achieve this, we will create a new action updateIsRunning and trigger it from the continue action when we end the game to set is_running to false.

// main.js
const actions = {
    continue: () => state =>
        (isOutOfBounds(state.snake[0]) || selfCollision(state.snake)
            ? action('updateIsRunning', false)
            : delay(UPDATE_INTERVAL, 'frame')
        ),
    updateIsRunning: value => state => ({
        ...state,
        is_running: value,
    }),
}

Now let's create a component that will render our game over screen.

// main.js
const game_over_style = {
    title: {
        font: 'bold 48px sans-seriff',
        fill: '#fff',
        opacity: 0.8,
        'text-anchor': 'middle',
    },
    score: {
        font: '30px sans-seriff',
        fill: '#fff',
        opacity: 0.8,
        'text-anchor': 'middle',
    }
}

const GameOver = score =>
    g({ key: 'game-over'}, [
        rect({
            x: 0, y: 0, width: WIDTH, height: HEIGHT,
            fill: '#000',
            opacity: 0.4,
        }),
        text({
            style: game_over_style.title,
            x: WIDTH/2, y: 100,
        }, 'Game Over'),
        text({
            style: game_over_style.score,
            x: WIDTH/2, y: 160,
        }, `Score: ${score}`),
    ])

Nothing fancy going on here, we simply create a GameOver function that returns a semi-transparent rectangle to darken the game, a text that says Game Over and a text with the final score.

Now let's make the view function render it when the game is not running.

// main.js
const view = state =>
    svg({ viewBox: `0 0 ${WIDTH} ${HEIGHT}`, width: WIDTH, height: HEIGHT}, [
        Background(),
        Apple(state.apple),
        Snake(state.snake),
        Score(state.score),
        !state.is_running ? GameOver(state.score) : null,
    ])

That would be enough, however, since the GameOver component already tells us the final score, there is no need to render also the Score component when the game is over, so we can render either depending on the value of is_running.

// main.js
const view = state =>
    svg({ viewBox: `0 0 ${WIDTH} ${HEIGHT}`, width: WIDTH, height: HEIGHT}, [
        Background(),
        Apple(state.apple),
        Snake(state.snake),
        state.is_running
            ? Score(state.score)
            : GameOver(state.score),
    ])

Improvements

The game is functional now, but there are still a few things that we can do to improve and extend it, if you want to experiment a bit more. Here is a list of possible improvements.

Make the game run faster for every 100 score points. An easy way to achieve this is to have the update interval in the state instead of a constant, but take into account that it can never be zero or lower.
The algorithm we use to move the snake is pretty naïve, we really don't need to calculate a new position for each cell of the body. Another approach is to pick the last cell of the tail, and move it to the beginning of the array at the new position for the head and not move any other cell.
Add a way to restart the game (that is not reloading the window).
Make different apples deal a different amount of score points.
It's unlikely, but apples can appear in cells already occupied by the snake, find a way to prevent that.

Conclusion

You can check out the final code here.

I hope this tutorial helped you understand a bit better how to model complex actions with hyperapp and @hyperapp/fx and you have a better idea of what it's capable of. Don't hesitate to write any thoughts or questions in the comments section.

Create a Snake clone with Hyperapp, part 1

Avalander — Thu, 02 Aug 2018 08:24:50 +0000

(Cover picture by Dominik Vanyi on Unsplash)

Here is a demo of what we are going to build.

In this tutorial I'm going to cover how to create a snake clone using hyperapp. There are no big requirements, but you should at least have read the getting started guide for hyperapp and be familiar with ES6 syntax.

In particular, these are the ES6 features you should be familiar with to understand the code.

Import statements.
Arrow functions.
Destructuring assignments.
Spread syntax.
Ternary operator. Not actually an ES6 feature, but I use it abundantly, so you should be able to read it.

Create project and install dependencies

To create the project, simply create a new project in an empty folder using npm init and install the following dependencies.

$ npm i --save hyperapp @hyperapp/fx

hyperapp: hyperapp is a minimalistic javascript framework for creating web applications, heavily inspired by Elm.
@hyperapp/fx: hyperapp/fx provides functions that we can use to set up time intervals and other side effects easily.

I'm using webpack to build this project, but I won't get into how to set it up here. If you are feeling lazy, you can download the set up from this repo.

Now we should be ready to start coding.

Set up hyperapp

Hyperapp exposes a function called app that receives an initial state, the actions available for our app, a function to render the view from the state, and a DOM element to mount the app. Since we are using @hyperapp/fx, we need to wrap our app with the withFx method. Let's start with our main.js file.

// main.js
import { app } from 'hyperapp'
import { withFx } from '@hyperapp/fx'


const state = {}

const actions = {}

const view = state => {}

const game = withFx(app) (state, actions, view, document.body)

Create SVG helpers

We are going to use SVG to render our game. We could easily use the canvas API instead, but I find SVG to be a great choice when you only need to draw basic shapes.

The package @hyperapp/html provides some handy functions to create virtual dom nodes. Unfortunately, there is no official package with similar helper functios to create SVG elements. We can still create SVG elements with hyperapp's h function, but wouldn't it be nice if we could write our code like this?

svg({ viewBox: '0 0 600 400' }, [
    g({}, [
        rect({ x: 0, y: 0, width: 50, height: 50, fill: '#a4b398' })
    ])
])

We can easily write such helpers ourselves, so let's go ahead and create a svg.js file and import it in our main.js.

// svg.js
import { h } from 'hyperapp'


export const svg = (attrs, children) => h('svg', attrs, children)
export const g = (attrs, children) => h('g', attrs, children)
export const rect = (attrs, children) => h('rect', attrs, children)

// main.js
import { svg, g, rect } from './svg'

Note: what about jsx?

If you look around for resources on hyperapp, you will notice that most of them use jsx instead of the html helpers. While we could do the same here, I prefer using plain Javascript to define my views, so I stick to html helper functions.

Nevertheless, if you would rather write jsx, you should be able to follow this tutorial anyway and you don't need the svg.js file with the svg helper functions. Just make sure that you are importing the function h from hyperapp in your main.js if you use jsx.

Now we are all set up and it's time to start actually building our game.

Create the background

The background is going to be a green rectangle covering the entire playable area. Let's start defining some constants.

// main.js
const SIZE = 15
const WIDTH = SIZE * 40
const HEIGHT = SIZE * 27

const COLORS = {
    background: '#088c64',
}

SIZE is how big the cells will be. WIDTH and HEIGHT are the sizes of the playing area. Instead of defining them with absolute values, we do it in proportion to SIZE so that the board has always the same relative size independently of scale.

COLORS.background is the colour we are going to use to fill our background.

We need to add a svg element where the game is going to be rendered, so let's modify our view function.

// main.js
const view = state =>
    svg({ viewBox: `0 0 ${WIDTH} ${HEIGHT}`, width: WIDTH, height: HEIGHT}, [

    ])

We could nest some more SVG elements there to create our background, but the view function could get huge if we had a lot of elements to draw, so let's create a component for the background instead.

// main.js
const view = state =>
    svg({ viewBox: `0 0 ${WIDTH} ${HEIGHT}`, width: WIDTH, height: HEIGHT}, [
        Background(),
    ])

const Background = () =>
    g({ key: 'background' }, [
        rect({ x: 0, y: 0, width: WIDTH, height: HEIGHT, fill: COLORS.background }),
    ])

with that we should see a big, green rectangle on the screen.

Create the snake

Let's add the main character of our game, the snake. We will store the position of the snake as an array of points in our state object.

// main.js
const state = {
    snake: [
        { x: 3 * SIZE, y: 3 * SIZE },
        { x: 2 * SIZE, y: 3 * SIZE },
        { x: 1 * SIZE, y: 3 * SIZE },
    ]
}

Let's add a couple of colours to render our snake with.

//main.js
const COLORS = {
    snake: {
        fill: '#bcaba0',
        stroke: '#706660',
    },
}

And let's create another component to render the snake.

// main.js
const Snake = state =>
    g({ key: 'snake' },
        state.map(({ x, y }) => rect({
            x, y, width: SIZE, height: SIZE,
            fill: COLORS.snake.fill,
            stroke: COLORS.snake.stroke,
            'stroke-width': 2
        }))
    )

const view = state =>
    svg({ viewBox: `0 0 ${WIDTH} ${HEIGHT}`, width: WIDTH, height: HEIGHT}, [
        Background(),
        Snake(state.snake),
    ])

The function Snake receives the snake's body array as parameter.
It creates a SVG group to enclose the snake's body elements.
It maps each point in the body array to a rect object in the same coordinates with some style attributes.

Make the snake move

Now we should see our snake on screen, but it's not moving yet. It's time to fix that.

We are going to need a way to update our state regularly. We can use @hyperapp/fx's delay function. delay works much like setTimeout, but it receives the name of an action to call after the given delay instead of a function. Let's see how we can use delay to create our game loop.

// main.js
import { withFx, delay } from '@hyperapp/fx'

const UPDATE_INTERVAL = 150

const actions = {
    frame: () => [
        delay(UPDATE_INTERVAL, 'frame')
    ]
}

We import the function delay from @hyperapp/fx.
We create the constant UPDATE_INTERVAL, which is the amount of milliseconds that will elapse between each frame.
We create an action called frame that will spawn another frame every UPDATE_INTERVAL milliseconds.

That's handy, but nothing is happening yet. We need to trigger the first frame, so the chain of updates will start rolling. Fortunately, hyperapp's app function returns an object with all the actions wired, so we can just call frame for the first time from there.

// main.js
const game = withFx(app) (state, actions, view, document.body) // This line is there already, don't write it again.
game.frame()

This should get the ball rolling. However, nothing is happening yet, we only have frame actions spawning more frame actions every 150 milliseconds, but they are not doing anything else. Let's just create an action that will print to the console every time a frame is spawned, to check that it's working.

// main.js
const actions = {
    sayHi: () => console.log('Hello, there!'),
}

Now we need a way to trigger that action every time we enter a new frame. That is easy enough with @hyperapp/fx. With @hyperapp/fx, an action can return an array of effects (one of such effects is delay, we are already acquainted with it). There is another effect called action that triggers an action from the app's actions object. So let's import action from @hyperapp/fx and trigger sayHi from frame.

// main.js
import { withFx, delay, action } from '@hyperapp/fx'

const actions = {
    frame: () => [
        action('sayHi'),
        delay(UPDATE_INTERVAL, 'frame'),
    ],
    sayHi: () => console.log('Hello, there!'),
}

If you check the console now, you will see a bunch of Hello, there! texts piling up.

As we have seen, action receives the name of an action in our actions object and triggers it. Optionaly, it receives a second parameter with an argument that will be sent to the triggered action. We will use this later.

Printing text on the console is fun, but we're here to see the snake move, so let's get to it.

The first thing we need is the direction where the snake is moving towards. We will add a direction property in the state object with the value 'right'.

// main.js
const state = {
    direction: 'right',
}

Now we will remove the sayHi action and create an action to update the snake instead.

// main.js
const actions = {
    frame: () => [
        action('updateSnake'),
        delay(UPDATE_INTERVAL, 'frame'),
    ],
    updateSnake: () => state => ({
        ...state,
        snake: updateSnake(state.snake, state.direction),
    }),
}

There we go, we have created the action updateSnake, that will return a shallow copy of the current state with an updated version of the snake, and we trigger that action in our frame.

We still need to implement the function updateSnake. There are many ways to make the snake move. The naïve approach would be to go through the array starting at the tail and move each cell to the position of the cell before it, then move the head towards the current direction.

// main.js
const updateSnake = (snake, direction) => {
    for (let i = snake.length - 1; i > 0; i--) {
        snake[i].x = snake[i - 1].x
        snake[i].y = snake[i - 1].y
    }
    if (direction === 'right') {
        snake[0].x += SIZE
    }
    if (direction === 'left') {
        snake[0].x -= SIZE
    }
    if (direction === 'down') {
        snake[0].y += SIZE
    }
    if (direction === 'up') {
        snake[0].y -= SIZE
    }
    return snake
}

We loop through the snake, starting at the last cell and ending at the second. We move each cell to the position of the cell before it.
We move the head one position towards the current direction.

Now we should see the snake moving to the right. Even though this works, we can do something neater to move the head instead of having a bunch of if statements. The approach I suggest is to have a dictionary with the possible directions as keys and a vector with x and y components that will be applied to the speed to calculate movement.

This is easier than it sounds. Let's start by creating the directions dictionary.

// main.js
const DIRECTIONS = {
    left: { x: -1, y: 0 },
    right: { x: 1, y: 0 },
    up: { x: 0, y: -1 },
    down: { x: 0, y: 1 },
}

And now we remove that bunch of if statements from our updateSnake function and instead transform the coordinates x and y of the head by adding the cell size multiplied by the relevant coordinate of the current direction.

// main.js
const updateSnake = (snake, direction) => {
    for (let i = snake.length - 1; i > 0; i--) {
        snake[i].x = snake[i - 1].x
        snake[i].y = snake[i - 1].y
    }

    snake[0].x += SIZE * DIRECTIONS[direction].x
    snake[0].y += SIZE * DIRECTIONS[direction].y

    return snake
}

Control direction

Our snake is now moving. The next step is to be able to change the direction with the arrow keys.

To achieve that, we are going to use an effect to trigger an action when a key is pressed. As you might suspect by now, @hyperapp/fx exposes a function for that, called keydown, so let's import it and use it.

// main.js
import { withFx, delay, action, keydown } from '@hyperapp/fx'

keydown, much like action and delay receives the name of an action to trigger when a key is pressed as a parameter. We only need to trigger that effect once, so we have to find a place for it. The easiest is to create a start action that will trigger the keydown effect and the first frame action and call that action instead of frame to start the game loop.

// main.js
const actions = {
    start: () => [
        keydown('keyPressed'),
        action('frame'),
    ],
}

// Replace 'game.frame()' with this.
game.start()

And now we have to implement the keyPressed action. Basically, we want to ignore all keys that are not ArrowUp, ArrowDown, ArrowLeft or ArrowRight, and we want to translate these four to the equivalent direction. Let's first create a new dictionary with the translation between keys and directions.

// main.js
const KEY_TO_DIRECTION = {
    ArrowUp: 'up',
    ArrowDown: 'down',
    ArrowLeft: 'left',
    ArrowRight: 'right',
}

This may look like a bit of repetition, but it will make our life easier in a minute.

Now for the keyPressed action. It is going to receive a regular keydown event, of which we are only interested in knowing the property key (the property key will be one of those four Arrow[Something] values if we're interested in it or another string otherwise). The keyPressed action should update the direction in the state if an arrow key is pressed and do nothing otherwise.

// main.js
const actions = {
    keyPressed: ({ key }) => state => ({
        ...state,
        direction: Object.keys(KEY_TO_DIRECTION).includes(key)
            ? KEY_TO_DIRECTION[key]
            : state.direction
    })
}

While this works, it is semantically inaccurate. We called our action keyPressed, but it's actually changing the direction. We can be more accurate if keyPressed only checks if another action needs to be triggered according to the pressed key and we create a new action that takes care of changing the direction.

// main.js
const actions = {
    keyPressed: ({ key }) =>
        (Object.keys(KEY_TO_DIRECTION).includes(key)
            ? [ action('changeDirection', KEY_TO_DIRECTION[key]) ]
            : []
        ),
    changeDirection: direction => state => ({
        ...state,
        direction,
    }),
}

There we go. Now keyPressed will check if the key property of the event is a key in our KEY_TO_DIRECTION dictionary. If that is the case, it will trigger a changeDirection with the appropriate direction, otherwise it won't trigger any additional action.

changeDirection simply receives a direction and updates the state with that direction.

There is yet one thing we need to take care of. In the current state, our snake can switch to the opposite direction. If it is moving to the right and the player presses the left arrow, it will change direction to the left and walk over itself. We would like to prevent that.

To achieve that, we will sophisticate our changeDirection action a bit more. Instead of blindly updating the direction, it will update it only if the new direction is not opposite to the current direction. To easily know if the current and new directions are opposite, we will create a new dictionary with each direction's opposite (this is the last directions dictionary we create, I promise).

// main.js
const OPPOSITE_DIRECTION = {
    up: 'down',
    down: 'up',
    left: 'right',
    right: 'left',
}

const actions = {
    changeDirection: direction => state => ({
        ...state,
        direction: (direction === OPPOSITE_DIRECTION[state.direction]
            ? state.direction
            : direction
        )
    }),
}

Now changeDirection will only switch to the new direction if it is not opposite to the previous direction.

However, there is a bug in that code. changeDirection can be triggered multiple times between frames, while the snake will only move once. Therefore, if the snake is moving to the left and the player presses the up arrow, the direction while change to 'up'. Now, if the player presses the right arrow before the next frame, direction will change to 'right' before the snake has moved up. Effectively, the snake will switch directions from left to right in the next frame.

Go ahead, change UPDATE_INTERVAL to a larger value, like 500, and see it for yourself.

One way to avoid that is to add a new property in the state, next_direction, and have changeDirection update that property instead. Then, we always have the current direction in direction and we can check that we are not setting the opposite direction.

Then, we will create a new action, updateDirection, that will update the direction only once per frame.

// main.js
const state = {
    direction: 'right',
    next_direction: 'right',
}

const actions = {
    frame: () => [
        action('updateDirection'),
        action('updateSnake'),
        delay(UPDATE_INTERVAL, 'frame'),
    ],
    updateDirection: () => state => ({
        ...state,
        direction: state.next_direction,
    }),
    changeDirection: direction => state => ({
        ...state,
        next_direction: (direction === OPPOSITE_DIRECTION[state.direction]
            ? state.next_direction
            : direction
        )
    }),
}

There we go.

We added a new property next_direction to state.
changeDirection will place the direction for the next frame in next_direction instead of direction, checking that the new value is not the opposite direction to what is in direction.
We created a new action, updateDirection, that will be triggered once per frame and will take the most recent value in next_direction and place it in direction before the snake is updated.

Conclusion

That was a lot of text, congratulations on making it so far! In the second part of the tutorial we will explore how to add apples and score, make the snake grow, and end the game when the snake collides with a border or with itself.

You can find the code we've written so far here.

Take a deep breath, make a big cup of tea, and continue with the second (and last) part of the tutorial when you are ready.

Create a Snake clone with Hyperapp, part 2

Avalander ・ Aug 2 '18

#tutorial #javascript #hyperapp #snake