Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Haskell shell interface
Shell Haskell
branch: master

This branch is 205 commits behind yesodweb:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
Shelly
examples/Pipe
shelly-extra
test
.gitignore
LICENSE
README.md
Setup.hs
Shelly.hs
shelly.cabal

README.md

Shelly

Shelly provides a single module for convenient systems programming in Haskell.

  • is aimed at convenience and getting things done rather than being a demonstration of elegance.
  • has detailed and useful error messages
  • maintains its own environment, making it thread-safe
  • is modern, using Text and system-filepath/system-fileio
  • has low memory usage
    • run_ and other underscore variants that don't return stdout
    • runFoldLines to run a fold operation over each line rather than loading all of stdout into memory

Looking to put your Haskell learning to immediate practical use? You don't have to create artifical intelligence, try just automating some of your boring tasks.

The focus of this library on convenience combined with good error messages should make shelly approachable for newer users of Haskell. I have published an introductory article to scripting with shelly, targeted towards those not familiar with Haskell. There is a paid version in German from Linux Magazin.

More shelly packages

The shelly-extra package has some additional functionality that requires additional dependencies, currently including a convenient concurrency/futures implementation. If you are following along the above article you need to install it.

Examples

Blog Posts

Testimonials

Alternatives

Haskell shell scripting libarires

  • HSH - A good alternative if you want to mixup usage of String and ByteString rather than just use Text.
  • HsShellScript - Has extensive low-level shell capabilities.

Both of these libraries (unlike Shelly currently) also implement very efficient mechanisms for piping/redirecting.

Haskell supplements

  • FileManip - more efficient file finding code (uses Lazy IO). Shelly's finders are currently being re-worked

Shell commands with richer input/output

Shelly does not change the nature of shell scripting (text in, text out). If you want something more revolutionary you might try these:

Usage

Shelly's main goal is ease of use. There should be a primitive for every shell operation you need so you can easily build abstractions, so there are many of the usual file and environment operations.

There are 2 main entry points for running arbitrary commands: run and cmd. They take a FilePath as their first argument. run takes a [Text] as its second argument. cmd takes a variadic number of arguments, and they can be either Text or FilePath.

    {-# LANGUAGE OverloadedStrings #-}
    {-# LANGUAGE ExtendedDefaultRules #-}
    {-# OPTIONS_GHC -fno-warn-type-defaults #-}
    import Shelly
    import Data.Text.Lazy as LT
    default (LT.Text)

    monit_ = command_ "monit" ["-c", ".monitrc"]

    main = shelly $ verbosely $ do
      listing <- cmd "ls" "-a" "foo"

      monit_ ["reload"]
      echo "monit reloaded"

Yes, you can write variadic functions in Haskell quite easily, you just can't compose them as easily. I find cmd to be more convenient, but I use run when I am building up abstractions.

Escaping

By default, all commands are shell escaped. If you want the shell to interpret special characters such as *, just use escaping False $ do ...

Using Text and FilePath together

Shelly's usage of system-filepath means you may need to convert between Text and FilePath sometimes. This should be infrequent though because

  • cmd will convert FilePath to Text
  • The </> and <.> combinators convert String/Text into a FilePath automatically

Manual conversion is done through toTextIgnore or toTextWarn.

Thread-safe working directory

cd does not change the process working directory (essentially a global variable), but instead changes the shelly state (which is thread safe). All of the Shelly API takes this into account, internally shelly converts all paths to absolute paths. You can get turn a relative path into an absolute with absPath or canonic or you can make a path relative to the Shelly working directory with relPath.

Good error messages

Haskell's #1 weakness for IO code is a lack of stack traces. Shelly gives you something different: detailed logging. In most cases this should be more useful than a stack trace. Shelly keeps a log of API usage and saves it to a .shelly directory on failure. If you use shellyNoDir, the log will instead be printed to stderr. This is in addition to the verbosely settings that will print out commands and their output as the program is running. Shelly's own error messages are detailed and in some cases it will catch Haskell exceptions and re-throw them with better messages.

If you make your own primitive functions that don't use the Shelly API, use trace or tag to log what they are doing. You can turn tracing off (not generally recommended) by setting tracing False.

Future plans

  • improved SSH API
  • Switch from lazy text to strict
  • fix PATH/which implementation
  • more efficient piping/redirecting (issue #18)
Something went wrong with that request. Please try again.