mendo.zone

Neovim for Haskell Development

2018-06-30T15:27:28-06:00

Here’s how I setup neovim or vim 8 to be a functional working environment.

The focus will be on Haskell, but many of the plugins here are useful for any language in both vim and neovim.

Limits of Vim

My vim config for PureScript had been working nicely for me this year, but my Haskell setup was lacking in features.

I started working through Stephen Diehl’s vim article, adding plugins for autocompletion, snippets, and tab alignment.

The features were now there, but performance in vim had gone down noticeably. Opening a file for the first time would take about 4 seconds (as indicated by vim’s profile feature).

On top of that, vim does not support Intero, which is supposed to be the killer feature of Haskell on Emacs. I thought maybe it was time to finally tackle the Emacs learning curve for the sake of Haskell development.

Then I discovered there is Intero support for neovim. Also, some of the plugins I had just installed were intended first for neovim, and only worked in vim 8 through compatibility plugins.

Surely neovim ought to have better performance for these plugins. Right? :thumbsup:

How I Vim

Before I go over the plugins I have chosen to use, I want to show how I use git to save my vim setup for use on multiple machines.

First of all, I load my plugins using Pathogen. With Pathogen, you only have to download the plugin to ~/.vim/bundle/ and it will be loaded when vim starts.

My .vim folder is a git repo that I push to GitHub, so I can access it when setting up a new machine. Since most vim plugins can also be found on GitHub, I add them to this repo as git submodules.

cd ~/.vim/bundle/
git submodule add https://github.com/neovimhaskell/haskell-vim.git

The primary benefit here is that I can update all my plugins by updating submodules:

git submodule update --recursive --remote

Downloading my .vim repo on a new machine therefore requires the --recursive option to also download submodules:

git clone --recursive https://github.com/johnmendonca/vimrc.git .vim

The downside to this approach is that removing submodules can be a pain.

Installing neovim

Installing neovim depends on your system.

In my case (Linux Mint), there is no system package for neovim. I followed the installation instructions to install using the Ubuntu PPA.

Start neovim by running:

nvim

Now with a fresh working install of neovim, we are ready to start setting it up.

Configuring neovim

The config file for neovim exists at ~/.config/nvim/init.vim, rather than ~/.vimrc. If you want to use your existing vim config in neovim, you can do that.

First I copied over my basic .vimrc commands over to ~/.config/nvim/init.vim:

syntax on
filetype plugin indent on

set nocompatible
set number
set showmode
set smartcase
set smarttab
set smartindent
set autoindent
set expandtab
set shiftwidth=2
set softtabstop=2
set background=dark
set laststatus=0

colo darkblue
hi Keyword ctermfg=darkcyan
hi Constant ctermfg=5*
hi Comment ctermfg=2*
hi Normal ctermbg=none
hi LineNr ctermfg=darkgrey

Some of these may be redundant in neovim.

Pathogen

Pathogen is the foundation for installing all plugins.

mkdir -p ~/.config/nvim/autoload
cd !$
wget https://raw.githubusercontent.com/tpope/vim-pathogen/master/autoload/pathogen.vim

In ~/.config/nvim/init.vim add:

execute pathogen#infect()

Now your plugins in ~/.config/nvim/bundle/ should be loaded whenever neovim starts.

Plugins

I have shown above how to install a plugin as a git submodule, but the minimum that you need to install any plugin is to download it into your bundle folder:

cd ~/.config/nvim/bundle/
git clone https://github.com/neovimhaskell/haskell-vim.git

This is the same for all the plugins listed here.

Let’s start with the most general purpose plugins and move to those specifically for Haskell.

NERDTree

NERDTree will provide a vim split with your project folder structure that you can use to browse, create, delete, copy, or move files without typing out the full commands.

Install the plugin and modify your init.vim:

"Open NERDTree when nvim starts
autocmd StdinReadPre * let s:std_in=1
autocmd VimEnter * if argc() == 0 && !exists("s:std_in") | NERDTree | endif

"Toggle NERDTree with Ctrl-N
map <C-n> :NERDTreeToggle<CR>

"Show hidden files in NERDTree
let NERDTreeShowHidden=1

ctrlp.vim

ctrlp.vim allows you to perform a fuzzy name search on the files within your project directory. This brings the killer feature of Sublime Text into vim.

Simply install and restart nvim. Now whenever you press <Ctrl-p> a new file search window should appear.

Grepper

Grepper performs text search throughout the files in your project. I had previously used ack.vim but it requires you to install the Perl tool ack.

I don’t use text search in my work very often, and both of these plugins mess up my splits sometimes. There are times when text search is critical though, and I wouldn’t be without a plugin like this.

Grepper supports a variety of search tools, but the default works fine for me. I bind the key command \ga to search the entire project, and \gb to search only the current buffer:

"Use Grepper
nnoremap <leader>ga :Grepper<cr>
nnoremap <leader>gb :Grepper -buffer<cr>

Now you can search for the text “foo” throughout your project by typing the following in command mode:

\gafoo<Enter>

Vim Tmux Navigator

This one is for tmux users only. tmux is useful when you’re working on a remote server and don’t want to worry about your ssh session becoming disconnected. It also allows you to split one terminal emulator into many terminal windows.

I use both tmux and vim window splits at the same time. For example here is my screen while writing this page (using vim 8):

Vim Tmux Navigator allows you to move between both types of splits seamlessly using one set of key commands. After this is setup you will be able to move between all splits using <Ctrl> + <h, j, k, l>.

These are the same keys for moving around within a vim document. Now just hold <Ctrl> and you will be moving between splits.

Configuration changes are needed for tmux, add this to your ~/.tmux.conf:

# Smart pane switching with awareness of Vim splits.
# See: https://github.com/christoomey/vim-tmux-navigator
is_vim="ps -o state= -o comm= -t '#{pane_tty}' \
    | grep -iqE '^[^TXZ ]+ +(\\S+\\/)?g?(view|\.?n?vim?x?(-wrapped)?)(diff)?$'"
bind-key -n C-h if-shell "$is_vim" "send-keys C-h"  "select-pane -L"
bind-key -n C-j if-shell "$is_vim" "send-keys C-j"  "select-pane -D"
bind-key -n C-k if-shell "$is_vim" "send-keys C-k"  "select-pane -U"
bind-key -n C-l if-shell "$is_vim" "send-keys C-l"  "select-pane -R"
bind-key -n C-\ if-shell "$is_vim" "send-keys C-\\" "select-pane -l"
bind-key -T copy-mode-vi C-h select-pane -L
bind-key -T copy-mode-vi C-j select-pane -D
bind-key -T copy-mode-vi C-k select-pane -U
bind-key -T copy-mode-vi C-l select-pane -R
bind-key -T copy-mode-vi C-\ select-pane -l

This plugin has worked well for me in vim, and does not require config changes if you use the default key bindings.

Some people have problems getting this to work right with neovim. There are some outstanding issues with neovim that you should check if you have trouble.

I encountered one of these issues, where <Ctrl-h> would not work in neovim inside tmux (the keypress registers as Backspace). The following change to init.vim is a workaround:

"Hack for neovim and vim-tmux-navigator
nnoremap <silent> <BS> :TmuxNavigateLeft<cr>

Previously I had installed neovim through Nix, and had an issue caused by binary names used in Nix. If you installed neovim though Nix, use my tmux config above and not the default from the plugin README. There is a necessary regex change for Nix binary support.

vim-gitgutter

vim-gitgutter will show git diff information in a column along the left edge of your file. You will be able to see which lines are new or modified, and where lines have been removed. It’s a little convenience that saves you a trip to the console.

If you want to run even more git commands within your editor, check out fugitive.vim.

Haskell IDE

Let’s look at the plugins that will allow us to turn neovim into a Haskell IDE. Thanks to Stephen Diehl and Jake Zimmerman for much of this information.

haskell-vim

haskell-vim provides an alternative syntax highlighter, and options for indentation. Here are my settings for init.vim:

let g:haskell_classic_highlighting = 1
let g:haskell_indent_if = 3
let g:haskell_indent_case = 2
let g:haskell_indent_let = 4
let g:haskell_indent_where = 6
let g:haskell_indent_before_where = 2
let g:haskell_indent_after_bare_where = 2
let g:haskell_indent_do = 3
let g:haskell_indent_in = 1
let g:haskell_indent_guard = 2
let g:haskell_indent_case_alternative = 1
let g:cabal_indent_section = 2

Intero

Intero for Neovim will run a GHCi console process inside neovim, making it convenient to reload your files and enter expressions.

This plugin uses stack by default but can be configured otherwise. Another alternative is neovim-ghci.

The first time you open a Haskell file after installing the plugin, it will automatically open a split in vim and build intero for your stack project.

The example configuration on the GitHub page is a good place to start, though I have the following setup for my needs:

" Automatically reload on save
au BufWritePost *.hs InteroReload

" Lookup the type of expression under the cursor
au FileType haskell nmap <silent> <leader>t <Plug>InteroGenericType
au FileType haskell nmap <silent> <leader>T <Plug>InteroType
" Insert type declaration
au FileType haskell nnoremap <silent> <leader>ni :InteroTypeInsert<CR>
" Show info about expression or type under the cursor
au FileType haskell nnoremap <silent> <leader>i :InteroInfo<CR>

" Open/Close the Intero terminal window
au FileType haskell nnoremap <silent> <leader>nn :InteroOpen<CR>
au FileType haskell nnoremap <silent> <leader>nh :InteroHide<CR>

" Reload the current file into REPL
au FileType haskell nnoremap <silent> <leader>nf :InteroLoadCurrentFile<CR>
" Jump to the definition of an identifier
au FileType haskell nnoremap <silent> <leader>ng :InteroGoToDef<CR>
" Evaluate an expression in REPL
au FileType haskell nnoremap <silent> <leader>ne :InteroEval<CR>

" Start/Stop Intero
au FileType haskell nnoremap <silent> <leader>ns :InteroStart<CR>
au FileType haskell nnoremap <silent> <leader>nk :InteroKill<CR>

" Reboot Intero, for when dependencies are added
au FileType haskell nnoremap <silent> <leader>nr :InteroKill<CR> :InteroOpen<CR>

" Managing targets
" Prompts you to enter targets (no silent):
au FileType haskell nnoremap <leader>nt :InteroSetTargets<CR>

With this config, Intero will start automatically and I can open a terminal split using \nn, then hide it again using \nh.

Using the terminal in neovim is a little strange. Move to the split and press i to enter Terminal mode (not insert mode) and you can enter commands into the REPL. Exit terminal mode by pressing <Ctrl-\> <Ctrl-n>.

The author of the plugin has an example keybinding to make exiting terminal mode a little more intuitive. I have adapted his example to use the split movement keys we setup in the tmux section:

" Ctrl-{hjkl} for navigating out of terminal panes
tnoremap <C-h> <C-\><C-n><C-w>h
tnoremap <C-j> <C-\><C-n><C-w>j
tnoremap <C-k> <C-\><C-n><C-w>k
tnoremap <C-l> <C-\><C-n><C-w>l

You still need to hit i to enter terminal mode. Alternatively, you can use :InteroEval to enter an expression in the REPL without moving panes at all.

With my config, you can type \ne2+2<Enter> to execute 2+2 in the REPL without ever leaving your file.

Testing

When you are writing tests for a Stack project, and want to use Intero to load and run your test code, you have to first change the target using :InteroSetTargets. The reason for this is that a Stack project may have different dependencies for a library or executable versus your test code. So, unless you change to the testing target, dependencies like hspec will not be loaded and available to Intero.

When I am working on a spec I want to save my file and run the spec without moving to the console. I can bind the expression hspec spec to the command \nb using :InteroSend:

" Run the spec in the current file
au FileType haskell nnoremap <silent> <leader>nb :InteroSend hspec spec<CR>

Neomake

Neomake allows us to run programs against our files and project. By default for Haskell files, neomake will use ghc-mod, hlint, and hdevtools to check your files

These programs need to be installed first:

stack install ghc-mod hlint hdevtools

Neomake is an alternative for Syntastic. Add this to your init.vim to have checks ran against your file every time you save it:

call neomake#configure#automake('w')

Neomake will highlight lines of code with issues, and the command :lopen will open a window listing the issues. If you want to have this window open automatically use this config:

let g:neomake_open_list = 2

Intero uses Neomake to do syntax checks on your files. I prefer to use Intero only and none of the others. This config will disable the default checkers:

let g:neomake_haskell_enabled_makers = []

Now only Intero will perform syntax checks when a file is saved, and we can still manually run the other checks if desired:

:Neomake ghcmod
:Neomake hlint
:Neomake hdevtools

ghcmod-vim

ghcmod-vim allows you to use ghc-mod commands in vim. You can display the type of the item under the cursor, or expand a function definition for all the cases of a data type.

You have to also install vimproc. This plugin requires an extra installation step depending on your system. On linux:

cd bundle/vimproc.vim/
make

Since there is overlap between this plugin and Intero, I only use a couple commands:

au FileType haskell nmap <leader>mc :GhcModSplitFunCase<CR>
au FileType haskell nmap <leader>ms :GhcModSigCodegen<CR>

vim-hindent / vim-stylishask

vim-hindent and vim-stylishask are pretty-printers that will reformat your source code to match standard style guides. The programs need to be installed first:

stack install hindent stylish-haskell

The resulting code looks very nice! :bowtie:

I have set these tasks to only be run manually:

let g:hindent_on_save = 0
au FileType haskell nnoremap <silent> <leader>ph :Hindent<CR>

let g:stylishask_on_save = 0
au FileType haskell nnoremap <silent> <leader>ps :Stylishask<CR>

These plugins can also process your file every time you save. Just replace a 0 with a 1 above on the printer you want to use.

Tabular

Tabular allows you to align characters in multiple rows. For example, this can align the = in a series of assignments, or the -> in a set of pattern matches.

nnoremap <leader>= :Tabularize /=<CR>
nnoremap <leader>- :Tabularize /-><CR>
nnoremap <leader>, :Tabularize /,<CR>
nnoremap <leader># :Tabularize /#-}<CR>

Pressing \= inside the following code block:

area Point = 0
area (Square x) = x * x
area (Rectangle x y) = x * y

will reformat it into:

area Point           = 0
area (Square x)      = x * x
area (Rectangle x y) = x * y

vim-hsimport

Note: as of my last update, hdevtools does not work with the most recent versions of GHC. This plugin will not work until hdevtools is updated.

vim-hsimport will insert import statements for the identifier under the cursor. It is based on hsimport and hdevtools which must be installed first:

stack install hsimport hdevtools

It also requires a globally accessible ghc command. Using this plugin with Stack resulted in an error for me, until I added the location of ghc to my system path. It is a bit of a hack, but I added the following to my .bashrc file:

# Put GHC on the path globally
GHC_PATH=`stack path | grep compiler-bin | sed -e 's/compiler-bin: //'`
export PATH="$PATH:$GHC_PATH"

Also kill any hdevtools processes, so it will restart :disappointed_relieved::

pkill hdevtools

Once installed, you can add insert statements for entire modules or individual symbols:

au FileType haskell nnoremap <silent> <leader>ims :HsimportSymbol<CR>
au FileType haskell nnoremap <silent> <leader>imm :HsimportModule<CR>

deoplete.nvim

deoplete is a general framework for completions in neovim. It requires installation of a Python 3 module:

pip3 install neovim

Vim 8 requires a couple extra plugins for compatibility.

Activate deoplete when nvim starts:

" Use deoplete.
let g:deoplete#enable_at_startup = 1

Now when you are typing, you should see a completion menu recommending other words from your file. You can select them with the arrow keys and hit <Enter> to insert your choice.

We’ll add a couple more plugins to make this more useful.

supertab

supertab will allow us to choose a completion with the Tab key instead of the arrow keys.

Setup the Tab key to call vim’s omnifunc:

let g:SuperTabDefaultCompletionType = '<c-x><c-o>'

neco-ghc

neco-ghc uses ghc-mod to fill the autocomplete menus with useful Haskell options.

" Disable haskell-vim omnifunc
let g:haskellmode_completion_ghc = 0

" neco-ghc
autocmd FileType haskell setlocal omnifunc=necoghc#omnifunc 
let g:necoghc_enable_detailed_browse = 1

SnipMate / UltiSnips

SnipMate and UltiSnips will allow you to paste snippets into your documents. If you have any sort of boilerplate code that you use often, these plugins can save you some time.

Which plugin to choose depends on what snippets file you want to use. I have not used these enough to have a preference.

Here are some haskell snippets to pick from:

Conclusion

Thank you for joining me on this tour of great open source software.

If you like what you’ve seen here, you can download and use my neovim configuration:

johnmendonca/nvim

I am happy with this setup, as it delivers the performance and usability improvements I had hoped for.

If you find that this article has missed something, or if you have any other suggestions, please contact me on Twitter at @johnmendonca.

How to Define a Function in Haskell and PureScript

2017-12-17T11:56:56-07:00

Defining functions in these languages is quite concise, and there are a few different forms that you’ll want to be able to recognize.

Basic Functions

A function with parameters can be defined using only whitespace and the equals sign:

name param1 param2 = ...

Any time there are multiple names on the left side on an equals sign, the first is the function name and the remaining are parameter names.

The body of the function is on the right hand side of the equals sign. Here is a simple function that combines two string to make a greeting:

hello name = "Hello, " ++ name

Calling a function is done simply by giving the name with its arguments separated by spaces:

hello "you"

The result of this expression is "Hello, you".

Types

Specifying the type of your function is optional if the compiler can infer it. Adding type signatures is recommended because they are very informative when reading code. Here is our definition including the type signature:

hello :: String -> String
hello name = "Hello, " ++ name

When you define a function this way, the type of the right hand expression should match the return type of the function. Here are some example expressions listed with their types:

hello                  :: String -> String
hello "friend"         :: String
"Hello, " ++ "friend"  :: String

Functions as Values

It is also possible to define functions where the parameter names are not listed on the left:

hello :: String -> String
hello = ...

This works anytime the type of the expression on the right is String -> String.

Unlike many other languauges, functions themselves are values and can be used any place other values can.

Once a function has been defined, its name can be used to refer to it as a value:

greeting :: String -> String
greeting = hello

In this case, we are not calling hello but referring to the function itself. All values including functions are immutable, and never change once created. hello and greeting are now just two names referring to the same function value.

Lambdas

A lambda expression lets us create an anonymous function value:

\param1 param2 -> ...

There is no equals sign here, and this function does not have a name. This evaluates to a function with two parameters. Using our example:

hello :: String -> String
hello = \name -> "Hello, " ++ name

The value on the right of the equals is a complete function of type String -> String. This hello function works exactly the same as our first example.

Pattern Matching

Sometimes your function will have different behavior based on the value of your arguments. In other languages, you would use constructs like switch, case, or if inside your function to handle this.

Pattern matching allows us to redefine our function for specific cases rather than create branching structures:

hello "Alice" = "Hi Alice!"
hello "Bob"   = "Hey Bob"
hello name    = "Hello, " ++ name

Anytime the argument data matches a specific case we have defined, that function body will be used instead. The last case uses a parameter instead of concrete data, so it will handle any case not matched above it.

Never omit the final catch-all definition, as this will result in a compiler error or a program that could possibly crash.

Pattern matching is also very useful for destructuring lists and algebraic data types. Many functions that take these types as parameters will use pattern matching to extract values out of the data structure. I will not go into this more here but will show an example:

data Shape = Circle Float
           | Rectangle Float Float           

shapeArea :: Shape -> Float
shapeArea (Circle r)      = 3.1415 * r * r
shapeArea (Rectangle h w) = h * w

Guards

Guards allow different function bodies based on any true or false condition. Pattern matching is limited to literal data structures, and guards can be used with any expression of type Boolean. Here is the same example from above:

hello name
  | name == "Alice" = "Hi Alice!"
  | name == "Bob    = "Hey Bob"
  | otherwise       = "Hello, " ++ name

otherwise is just a synonym for true, you should always have a catch-all guard to ensure all code paths are defined.

Operators

Operators like ++, <$>, <*>, or * are just functions that default to infix notation. Alphanumeric functions use prefix notation. We will not go deep into operator precedence and defining operators here, but you will want to recognize when an operator is being used.

Operators are usually written in infix notation, where the first argument comes before the function name:

2 + 3

Parentheses allow you to use an operator in prefix notation like a regular function:

(+) 2 3

The operator with parentheses is also the official name of the function, if you want to use it as a value:

addNumbers = (+)

Regular functions use prefix notation by default but can used in an infix position by using ticks. The following are equivalent:

addNumbers 2 3
2 `addNumbers` 3

Conclusion

This has been a quick rundown of function forms in Haskell and PureScript. Hopefully any code examples you see will now be a little more clear! We have only scratched the surface of some very useful features, and you now have what you need to dig into these topics on your own.

Beginner’s Haskell: Creating Bitmap Images

2017-12-13T13:25:50-07:00

Let’s use the library gloss in Haskell to easily display images. We’ll explore the types used by gloss and create a bitmap using ByteString.

Project Setup

We’ll use stack for this project, which I recommend for anyone starting out with haskell.

Download and Install Stack

Run this command to create a directory with your new project:

stack new gloss-bitmaps

Run the following to confirm the project is working. This may take some time when downloading GHC and libraries.

cd gloss-bitmaps/
stack setup
stack build
stack exec gloss-bitmaps-exe

This should print the text someFunc. If this is not working at this point, you will need to troubleshoot your stack installation or setup.

Finding Documentation

Usage examples for Haskell libraries can be hard to find, and we often must rely on library documentation. I would like to explore the process for finding API documentation, using gloss as an example.

Searching for “graphics libraries in Haskell” turns up this list: Applications and libraries/Graphics. The HaskellWiki is often a good source for high level overviews like this.

Through search results and listings, I see gloss is a popular library and has a high-level API with examples.

The top level hackage page for gloss does not have any information about basic usage. This page is what you will usually find when searching for a Haskell library. We need to dig into the module documentation.

There is a Modules section on the hackage page, let’s click the top level module for more information: Graphics.Gloss.

This page works as a starting point. We have a basic example and API documentation for the top level functions. There are many other modules to explore from the main hackage page when we need to use them.

Let’s start with the example in the gloss documentation.

Basic `gloss`

First we will need to add gloss as a dependency for our project. Edit the gloss-bitmaps.cabal file and add it to the library section:


library
  hs-source-dirs:      src
  exposed-modules:     Lib
  build-depends:       base >= 4.7 && < 5
                     , gloss
  default-language:    Haskell2010

Stack uses hpack in its default project template to specify project settings. We will only use the cabal file in this article, so please delete the hpack config before building:

rm package.yaml

Edit the library source file src/Lib.hs, and add the example code from the gloss documentation:

module Lib
    ( someFunc
    ) where

import Graphics.Gloss

someFunc :: IO ()
someFunc = display (InWindow "Nice Window" (200, 200) (10, 10)) white (Circle 80)

Rebuild and run:

stack build
stack exec gloss-bitmaps-exe

The program should open a new window with a drawing of a circle.

`display`

Let’s take a look at the type for the display function, found in the module documentation:

display :: Display      -- Display mode.
        -> Color        -- Background color.
        -> Picture      -- The picture to draw.
        -> IO ()

In our example, the first argument to display is:

(InWindow "Nice Window" (200, 200) (10, 10))

This must have the type Display. Sure enough, we can confirm this in the documentation (and in the source code). The data type Display has two constuctors:

data Display
        -- Display in a window with the given name, size and position.
        = InWindow   String (Int, Int) (Int, Int)

        -- Display full screen.
        | FullScreen

Experiment with this and see if you can change the window size or display the image in full screen.

The second parameter of display is very straight forward. It is the background color for our display. In our case we are passing white, which is a value from the gloss library.

The third parameter is of type Picture. We are passing the value (Circle 80). From this we can infer that Circle is a constructor which takes a number (the radius) and returns a Picture of a circle.

Drawing Bitmaps

We’ve got a lot going for us already with just this one line of code. We know if we have a Picture, we have a way to display it. Instead of using drawing functions like circle or line, let’s find out how to make a bitmap Picture.

A bitmap image is basically just a big list of pixels. A 100x100 image would have 10,000 pixels. Each pixel is a 32-bit RGBA value. The value is broken into 4 bytes, one each for red, green, blue, and alpha (transparency).

The RGBA system allows us to specify any color and transparency. For example, in CSS if you wanted a nearly transparent purple, you could say:

rgba(128, 0, 128, 0.25);

Bitmaps in `gloss`

We need to dig through the documentation again to find out how to create a bitmap Picture. The top level module has a reference to a Bitmap module so let’s check that out: Graphics.Gloss.Data.Bitmap

(Please note if you want to view the source code: this code is imported from another package called gloss-rendering: Graphics.Gloss.Rendering)

There are some promising looking functions here, the best one for us uses ByteString:

bitmapOfByteString :: Int
                   -> Int
                   -> BitmapFormat
                   -> ByteString
                   -> Bool
                   -> Picture

-- Copy a ByteString of RGBA data into a bitmap with the given width and height.

-- The boolean flag controls whether Gloss should cache the data between frames for speed.

ByteString is a basic Haskell type to represent binary data without any assumption of encoding. There are also functions to create bitmaps from a BMP or ForeignPtr Word8. These other functions might be useful if we were loading an image from a file or from memory created by another program.

Since we are just generating one image in Haskell, ByteString should be the easiest to work with. We are not going to worry about performance this time.

Looking at the type and documentation for bitmapOfByteString, we can see the first two Int parameters are for the width and height of the image. Let’s say those will both be 100 for a 100x100 image.

The last parameter is a Bool to turn on caching provided by gloss. Since we are just drawing one image and not changing it, this feature will not matter. Let’s just pass True.

This remaining two parameters have the types BitmapFormat and ByteString. We know the ByteString will hold the binary data for our image, so the BitmapFormat must describe how that data should be formatted.

`BitmapFormat`

We just need to lookup BitmapFormat in our module documentation:

data BitmapFormat
        = BitmapFormat 
        { rowOrder    :: RowOrder
        , pixelFormat :: PixelFormat }

This type uses Haskell record syntax, we can simplify this for clarity:

data BitmapFormat = BitmapFormat RowOrder PixelFormat

BitmapFormat is just a combination of RowOrder and PixelFormat. Let’s look at these:

data RowOrder
        = TopToBottom 
        | BottomToTop

data PixelFormat
        = PxRGBA | PxABGR

These two settings say how our binary image data will be interpreted. RowOrder determines if the first bytes in our data are for the top or bottom row in our image. PixelFormat similarly determines what order the bytes in each pixel should be.

We can choose any format as long as our image data matches. Let’s use this as our format:

BitmapFormat TopToBottom PxRGBA

Now all we need is our bitmap data in a ByteString. Let’s update our library code to include everything we have looked at.

module Lib
    ( someFunc
    ) where

import Graphics.Gloss

bitmapData = undefined

ourPicture :: Picture
ourPicture = bitmapOfByteString 100 100 (BitmapFormat TopToBottom PxRGBA) bitmapData True

someFunc :: IO ()
someFunc = display (InWindow "Nice Window" (200, 200) (10, 10)) white ourPicture

This code will compile but will not run due to the presence of undefined in the place of actual data. We will fill that in next.

Generating a `ByteString`

Now we know what format our data should be in, next we need to find out how to create a ByteString. We’ll go to the module documentation like we did before: Data.ByteString

Here is the description of ByteString:

A space-efficient representation of a Word8 vector, supporting many efficient operations.

Word8 is going to be relevant for us, as this is the Haskell type for one byte. If we wanted to represent our purple pixel from earlier (rgba(128, 0, 128, 0.25)) as a list of Word8, it would look like this:

purple :: [Word8]
purple = [128, 0, 128, 64]

A fully opaque red pixel would look like this:

red :: [Word8]
red = [255, 0, 0, 255]

We just need 10,000 of these in a ByteString and we should have a working image. There is a function in the docs which will work for this:

pack :: [Word8] -> ByteString

Our single pixel has 4 bytes in a list, so we’ll need 40,000 bytes in a list to generate the ByteString for a 100x100 image. Let’s first try to make an image of just one color. There is a function that will allow us to turn our pixels above into an infinite list of pixels:

cycle :: [a] -> [a]

-- cycle ties a finite list into a circular one, or equivalently, the infinite repetition of the original list

Laziness in Haskell makes working with infinite lists possible, since the elements of the list are not actually created until asked for. We use the take function to take some values from a list.

take 12 (cycle purple)

-- [128,0,128,64,128,0,128,64,128,0,128,64]

Alright, we are ready to update our code to draw a purple image. First, add the bytestring package to gloss-bitmaps.cabal:

library
  hs-source-dirs:      src
  exposed-modules:     Lib
  build-depends:       base >= 4.7 && < 5
                     , gloss
                     , bytestring
  default-language:    Haskell2010

Add the bitmap data to our library source file:

module Lib
    ( someFunc
    ) where

import Graphics.Gloss
import Data.Word
import Data.ByteString (ByteString, pack)

purple :: [Word8]
purple = [128, 0, 128, 64]

bitmapData :: ByteString
bitmapData = pack $ take 40000 (cycle purple)

ourPicture :: Picture
ourPicture = bitmapOfByteString 100 100 (BitmapFormat TopToBottom PxRGBA) bitmapData True

someFunc :: IO ()
someFunc = display (InWindow "Nice Window" (200, 200) (10, 10)) white ourPicture

Rebuild and run:

stack build
stack exec gloss-bitmaps-exe

At this point you have enough info to start playing around with pixel images. Try writing code to generate some different types of pixels.

In a future post, we will use IO in Haskell to produce randomly generated pixels.

The example code can be found on GitHub

Formatted Date Strings in Linux

2017-12-12T10:37:30-07:00

You can easily print the current time as a formatted string using the date command in linux:

date "+%Y-%m-%d %H:%M:%S %z"

The result of this command looks like this:

2017-12-12 10:37:30 -0700

The other format place holders are described in the date manual page:

man date

Installing WordPress on Linux Mint for Development

2017-07-20T00:22:22-06:00

This tutorial uses Linux Mint 18.

For development and testing, you’ll often want to run WordPress on a local machine. In Linux Mint we can get up and running quickly using a few packages and settings changes. It should be a similar process for Ubuntu or Debian.

Most of these commands need to be run as root or using sudo. Try sudo -i if you want to enter many commands as root.

Apache Web Server

Apache handles incoming connections, and runs the WordPress PHP code. Install by running:

apt-get install apache2

This should start the apache service when completed. Run ps ax, and look for lines like this:

4088 ? S 0:00 /usr/sbin/apache2 -k start

This shows you that the web server is running. It will also start again when your system reboots. When it is not running you can start it using:

service apache2 start

You can also stop and restart the service with this command.

Adding Modules

We are going to add two Apache modules that will help us for local WordPress development.

a2enmod rewrite userdir
service apache2 restart

The Rewrite module is a requirement for WordPress to define custom URL patterns.

The Userdir module allows regular users to host files in their home directories. By default, Apache will only serve files from /var/www/html, which requires root permissions to modify.

With the userdir module active, files stored in /home/username/public_html will be served at http://localhost/~username.

Create an HTML file in your public_html folder and confirm that it is being served correctly.

PHP

Install PHP 7, the Apache interface, and a few modules that we will need:

apt-get install php7.0 php7.0-mysql libapache2-mod-php7.0 php7.0-cli php7.0-cgi php7.0-gd

Apache will not run PHP code in a userdir by default, so we need to enable this manually. Edit the php7.0.conf file here:

vim /etc/apache2/mods-available/php7.0.conf

There is a section at the end we will comment out by adding # to the beginnings of the lines. It should look like this in the end:

# To re-enable PHP in user directories comment the following lines
# (from <IfModule ...> to </IfModule>.) Do NOT set it to On as it
# prevents .htaccess files from disabling it.
#<IfModule mod_userdir.c>
#    <Directory /home/*/public_html>
#        php_admin_flag engine Off
#    </Directory>
#</IfModule>

Restart Apache to reload the config files:

service apache2 restart

Now we want to confirm that PHP files are actually being run from our userdir.

Create this file:

vim ~/public_html/info.php

Put this in the file:

<?php
phpinfo();
?>

Save the file and then vist http://localhost/~yourname/info.php. You should see a large table of infomation generated by PHP. If the page is blank or showing an error, then the installation/configuration is not correct.

MySQL

The last major piece is the MySQL database, where WordPress will store most of its data. First install MySQL on your system:

apt-get install mysql-client mysql-server

During the installation process, a screen will ask you to supply a password for the root MySQL user. By default the password is blank, and it is recommended to add a password.

You can improve the security of the installation by running this:

mysql_secure_installation

This command will ask you a series of questions to optionally enable security features. You probably don’t need to use them all, but I’d recommend a few things:

Remove anonymous users
Disallow root login remotely
Remove test database
Reload privilege tables

This tutorial is about setting up a local development environment, not a secure production environment. The advice above will improve the security of a default installation, but would not be sufficient for production.

Creating a MySQL user and database

We do not want WordPress to have root access to our entire database server. We will create a MySQL user and database specifically for WordPress.

mysql -u root -p

This will ask you for the password you created when installing MySQL and will open a MySQL terminal with total access to the database server.

To create the database and user, enter the following commands using your own values (uppercase keywords are conventional but not required):

CREATE DATABASE 'wordpress';
CREATE USER 'wpuser'@'localhost' IDENTIFIED BY 'wppassword';
GRANT ALL PRIVILEGES ON wordpress.* TO 'wpuser'@'localhost';
FLUSH PRIVILEGES;

We are now ready to install WordPress itself.

Installing WordPress

Go to the WordPress website to download the source code. We will extract these files in our userdir:

cd ~/public_html
# for zip
unzip ~/Downloads/wordpress-4.8.1.zip
# for tar.gz
tar xzf ~/Downloads/wordpress-4.8.1.tar.gz

Now at http://localhost/~username/wordpress/ you should see a setup page created by WordPress. It is possible for WordPress to do the final setup here, but it would require changing the permissions of the wordpress/ directory.

Instead we will create the file manually:

cd ~/public_html/wordpress/
cp wp-config-sample.php wp-config.php
vim wp-config.php

Edit the new wp-config.php file and update the following values to match the database info:

/** The name of the database for WordPress */
define('DB_NAME', 'wordpress');

/** MySQL database username */
define('DB_USER', 'wpuser');

/** MySQL database password */
define('DB_PASSWORD', 'wppassword');

/** MySQL hostname */
define('DB_HOST', 'localhost');

Go back to http://localhost/~username/wordpress/ and you will see a new form, asking for new user information. This will setup the admin user of your new site. Fill in the info and your WordPress installation is complete!

A Static Site Folder Structure for Github Pages

2015-03-12T14:47:20-06:00

GitHub Pages is a GitHub service that will host your static website files, if you push them to a specific git repo or branch. This is one of the easiest ways for git users to host static HTML, CSS, and JS files.

This makes a perfect pair with a static site generator. In this article I outline a method to keep your entire static site project in one git repository.

How Github Pages Works

Github Pages has two types of repositories. A User/Organization Pages repository must be named username.github.io. This project will publish the contents of branch master as a static site. Create a git repository in the output directory and git push origin master to deploy your site.

A Project Pages repository is more flexible. In this type, the static site is published from the branch gh-pages. This leaves master free for the code of a software project. In our case we will store the source files of our website in master.

Using the method below, we can keep the source and output in separate branches, while maintaining the default folder structure of our project.

Setting Up The Project

Every static site generator will use a specific folder structure, with the generated output usually in one subdirectory. We want our branch gh-pages to be at the root of the output subdirectory. Our master branch will be one level up, at the root of the entire project. We can use .gitignore to nest one instance of the repository within the other.

Here is a step-by-step process to set this up:

Create a local project using your site generator of choice
git init a repository inside the project and push to a remote repository on GitHub
Create or edit your .gitignore file and add the output directory of your project to the ignore list.

At this point, change and build your site. Do a git status. You should only see changes to the source files, and not for the output folder.
Go ahead and delete that output folder
Now clone your project from Github, into the place where the output folder just was. Rename it to match the original folder name. You can do this all at once using: git clone <git-url> <folder-name>

Now we have have two copies of the repo, one nested inside the other. The outer source repo is blissfully ignorant of the inner one thanks to .gitignore.
Move into the inner repository. It should contain a copy of the project source which we now want to remove.
Create the new branch: git checkout -b gh-pages
Make sure the current branch is gh-pages. Then use git rm to remove the entire contents of the folder.
Build your site. The inner gh-pages repository should now contain the build output from your generator (the static website).
git add the files, git commit, and finally git push origin gh-pages.

Your site should now be published on Github Pages.
For the outer repository, you will commit and push to master any changes to the source files.
Commit and push to gh-pages from within the output subdirectory.

mendo.zone

Neovim for Haskell Development

Limits of Vim

How I Vim

Installing neovim

Configuring neovim

Pathogen

Plugins

NERDTree

ctrlp.vim

Grepper

Vim Tmux Navigator

vim-gitgutter

Haskell IDE

haskell-vim

Intero

Testing

Neomake

ghcmod-vim

vim-hindent / vim-stylishask

Tabular

vim-hsimport

deoplete.nvim

supertab

neco-ghc

SnipMate / UltiSnips

Conclusion

How to Define a Function in Haskell and PureScript

Basic Functions

Types

Functions as Values

Lambdas

Pattern Matching

Guards

Operators

Conclusion

Beginner’s Haskell: Creating Bitmap Images

Project Setup

Finding Documentation

Basic gloss

display

Drawing Bitmaps

Bitmaps in gloss

BitmapFormat

Generating a ByteString

Formatted Date Strings in Linux

Installing WordPress on Linux Mint for Development

Apache Web Server

Adding Modules

PHP

MySQL

Creating a MySQL user and database

Installing WordPress

A Static Site Folder Structure for Github Pages

How Github Pages Works

Setting Up The Project

Basic `gloss`

`display`

Bitmaps in `gloss`

`BitmapFormat`

Generating a `ByteString`