FP Haskell Center™ API

Download & Install

Archives with binary and Emacs Lisp code are available for various platforms:

If installing via these packages, please put the the executable fpco-api in your PATH.

Tip: In Windows you can run echo %PATH% in cmd.exe to see what directories are in your PATH.

This package can also be installed from Hackage:

cabal install fpco-api

The API package

The API package consists of an executable called fpco-api with the following commands:

  • start — Start a session server, listen for connections, keep sessions open and communicate with the FP Haskell Center servers.
  • config — Generate a configuration and write it to file.
  • check — Type check the given file (useful for flymake-style checkers).
  • download — Download a project and write an Emacs config.
  • emacs-config — Only write an Emacs config.

Help is provided for each of these via fpco-api --help, but as a user, you should only need to use the download command.

To use FP Haskell Center from your own IDE, you need at least the Personal license and the API package. Install it by choosing from the options on the right.

Opening Your Project

Once you have installed the fpco-api package, you can download your project and create a configuration file in one go. To do that, follow these steps:

  1. Open your project in the web interface and copy the web address of the page e.g. http://fpcomplete.com/user/foo/abc123.
  2. Create a directory where you'd like your project to be.
  3. In that directory, run the following:

     $ fpco-api download <your-project-url>

On the first time, this will prompt you for your API token, which you can find on the Token tab in the Account page.

The configuration will be saved automatically in a file called .fpco-api.conf in your home directory. For Windows users, that generally means the directory containing your My Documents directory.

Emacs

Note: Emacs 24 is required.

The Emacs integration comes in the form of fpco-mode.el, a minor-mode which enhances normal Emacs/haskell-mode operations to be backed by fpco-api. It is intended to be added as a hook to haskell-mode.

Getting Emacs

If you don't actually have Emacs, here's how to install:

  • Linux: install the Emacs version (24 or above) on your package manager (on Ubuntu this would be sudo apt-get install emacs). If you don't have Emacs 24 on your Ubuntu, you can install it with:

     sudo add-apt-repository ppa:cassou/emacs
     sudo apt-get update
     sudo apt-get install emacs24
  • OS X: Emacs for OS X

  • Windows: NTEmacs — this version of Emacs is good for Windows, it doesn't require any Cygwin or MinGW systems to be installed.

Configuring Emacs

Note: Make sure that you've already configured fpco-api by using the download or config commands, before opening Emacs.

The fpco-api package comes with an elisp/ directory, which contains all you need to start working using FP Haskell Center. Inside the elisp/ directory is a reasonable Emacs configuration, aimed at being immediately useful for working.

For newbies

Simply move the elisp/ directory to your home directory and rename it to .emacs.d/, make sure to move/delete any .emacs file. Emacs will automatically load the init.el file inside your .emacs.d/ directory. Launch a new Emacs process, it should be ready for the next section.

For advanced users

  • Run emacs -Q -l /path/to/elisp/init.el on the command-line. This will simply launch Emacs, just for this one invocation, disregarding any existing Emacs installation. This is good for just testing it out like a sandbox.

or

  • Pick and choose the necessary parts from init.el. This is recommended for Emacs gurus.

Opening Projects in Emacs

Because Emacs has no concept of “projects”, we use directory-local variables. Directory local variables are used with a .dir-locals.el file placed in the root of the project. That file is generated by using the fpco-api emacs-config command (or the previously mentioned fpco-api download command). If you have already done that, you're ready to go. Now open any .hs file in your project.

Note: Please close the project in your web browser before opening it in Emacs.

If you don't have the .dir-locals.el file, you can always run:

$ fpco-api emacs-config <your project web address>

Troubleshooting

If you're not sure/things aren't working, look in the *fpco-api* buffer. See also the fpco/start function mentioned in this page.

Features in Detail

Below is a list of all the interactive commands (invokable with M-x foo) provided in fpco-mode.

fpco/start

This starts the server. Users using the default configuration don't have to worry about calling this.

It opens a buffer called *fpco-api* in which there is a log of what is sent/received to/from the local fpco-api program and the remote FP Haskell Center server.

fpco/save-module

This saves the current Haskell file (.hs) to your project on the server, which also immediately starts recompilation. The fpco-mode minor adds this to save hooks so that it runs automatically after every save.

fpco/type

With this you can display the type of any selected region in an expression. By default, it will get the type of the current identifier at the point. But you can select a region of text, too.

By default, it pops up a help buffer containing the types. You can disable this behaviour by customizing fpco-type-popup.

fpco/goto

This will jump to the definition of the identifier at point (or the selected identifier), either in the current declaration, the current buffer, or other modules in the project. In the case that the identifier cannot be jumped to (like a library), it will display a message saying where it was imported from.

fpco/hoogle-type

Print the type that Hoogle considers to be the type of the identifier at point (or selected identifier). This is useful when you want the most general type of a library function.

fpco/hoogle-doc

Open a buffer showing the Haddock documentation of the given identifier.

fpco/completions

This is mainly for debugging purposes (but Emacs gurus are free to use it to extend the behaviour), it gets a list of completions of the current identifier at point (or selected identifier), printing out the list of results. For automatic completion, see the auto-complete section.

auto-complete

We provide integration with the auto-complete package out of the box. If you used our provided configuration, it will be enabled automatically.

For Emacs gurus: See the fpco-ac-candidates variable for programmatically using this.

flycheck

We provide flycheck integration out of the box. If you used our provided configuration, it will be enabled automatically.

For Emacs gurus: See the fpco-check checker.