shelly: shell-like (systems) programming in Haskell

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Shelly provides convenient systems programming in Haskell, similar in spirit to POSIX shells. Shelly:

Shelly is originally forked from the Shellish package.

See the shelly-extra package for additional functionality.

An overview is available in the README: https://github.com/gregwebs/Shelly.hs/blob/master/README.md


[Skip to Readme]

Properties

Versions 0.3.0, 0.3.0.1, 0.3.0.2, 0.3.1, 0.4, 0.4.1, 0.5.0, 0.5.1, 0.6, 0.7, 0.7.1, 0.8.0.1, 0.8.0.2, 0.9.0, 0.9.2, 0.9.3, 0.9.4.1, 0.9.4.2, 0.9.5, 0.9.5.1, 0.9.6, 0.9.7, 0.9.7.1, 0.9.7.2, 0.9.7.3, 0.10, 0.10.0.1, 0.11, 0.12, 0.12.0.1, 0.12.0.2, 0.12.1, 0.12.1.1, 0.12.2, 0.13, 0.13.0.1, 0.13.1, 0.13.2, 0.13.2.1, 0.13.3, 0.13.4, 0.13.5, 0.13.5.1, 0.14, 0.14.0.1, 0.14.1, 0.14.2, 0.14.2.1, 0.14.2.2, 0.14.2.3, 0.14.3, 0.15.0, 0.15.1, 0.15.2, 0.15.3, 0.15.3.1, 0.15.3.2, 0.15.3.3, 0.15.4, 0.15.4.1, 1.0.0.0, 1.1.0.0, 1.2.0.0, 1.3.0.0, 1.3.0.1, 1.3.0.2, 1.3.0.3, 1.3.0.4, 1.3.0.5, 1.3.0.6, 1.3.0.7, 1.3.1, 1.3.2, 1.4.0.1, 1.4.0.2, 1.4.1, 1.4.2, 1.4.3, 1.4.3.1, 1.4.4, 1.4.4.1, 1.4.4.2, 1.5, 1.5.0.1, 1.5.1, 1.5.1.1, 1.5.2, 1.5.3, 1.5.3.1, 1.5.3.2, 1.5.4, 1.5.4.1, 1.5.5, 1.5.6, 1.5.7, 1.6.0, 1.6.0.1, 1.6.1, 1.6.1.1, 1.6.1.2, 1.6.2, 1.6.2.1, 1.6.2.2, 1.6.2.3, 1.6.2.4, 1.6.2.5, 1.6.3, 1.6.3.1, 1.6.3.2, 1.6.3.3, 1.6.3.4, 1.6.4, 1.6.4.1, 1.6.5, 1.6.6, 1.6.7, 1.6.8, 1.6.8.1, 1.6.8.2, 1.6.8.3, 1.6.8.4, 1.6.8.5, 1.6.8.6, 1.6.8.7, 1.6.9, 1.7.0, 1.7.0.1, 1.7.1, 1.7.2, 1.8.0, 1.8.1, 1.8.2, 1.9.0, 1.10.0, 1.10.0.1, 1.11.0, 1.11.0, 1.12.0, 1.12.0.1, 1.12.1
Change log ChangeLog.md
Dependencies async, base (>=4.9 && <5), bytestring (>=0.10.6.0), containers (>=0.5.7.0), directory (>=1.3.0.0 && <1.4), enclosed-exceptions, exceptions (>=0.8.2.1), filepath, lifted-async, lifted-base (>=0.2.3.2), monad-control (>=0.3.2 && <1.1), mtl (>=2.2.2), process (>=1.4), text (>=1.2.2.0), time (>=1.3 && <1.13), transformers (>=0.5.0.0), transformers-base, unix-compat (>=0.4.1.1 && <0.7) [details]
License BSD-3-Clause
Author Greg Weber, Petr Rockai
Maintainer Andreas Abel
Category Development
Home page https://github.com/gregwebs/Shelly.hs
Source repo head: git clone https://github.com/gregwebs/Shelly.hs
Uploaded by AndreasAbel at 2023-01-24T20:34:31Z

Modules

[Index] [Quick Jump]

Flags

Manual Flags

NameDescriptionDefault
build-examples

build some example programs

Disabled
Automatic Flags
NameDescriptionDefault
lifted

run the tests against Shelly.Lifted

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for shelly-1.11.0

[back to package description]

Shelly

Build Status Build Status Hackage Stackage Nightly Stackage LTS

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

The focus of this library on convenience combined with good error messages should make shelly approachable for newer users of Haskell.

More shelly packages

The shelly-extra package has some additional functionality that requires additional dependencies, currently including a convenient concurrency/futures implementation.

Examples

Blog Posts

Testimonials

Help

Alternatives

Haskell shell scripting libraries

HSH, HsShellScript and shh (unlike Shelly currently) implement very efficient mechanisms for piping/redirecting in the system. turtle, like Shelly offers folding as a way to efficiently deal with a stream.

None of the alternatives to Shelly offer command tracing. For some this is an absolutely critical feature, particularly given that Haskell does not yet offer up stack traces.

Haskell file-finding supplements

Shelly's finders load all files into memory. This is simpler to use if you control the filesystem structure and know the system is bounded in size. However, if the filesystem structure is unbounded it consumes unbounded memory.

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.

Fun Example: shows an infectious script: it uploads itself to a server and runs itself over ssh. Of course, the development machine may need to be exactly the same OS as the server.

I recommend using the boilerplate at the top of this example in your projects. This includes setting line buffering if you are dealing with text and not binary data.

    {-# LANGUAGE OverloadedStrings #-}
    {-# LANGUAGE ExtendedDefaultRules #-}
    {-# OPTIONS_GHC -fno-warn-type-defaults #-}

    import Shelly
    import System.IO
    import Data.Text as T
    default (T.Text)

    main :: IO ()
    main =  do
      hSetBuffering stdout LineBuffering
      shelly $ verbosely $ do
        host <- run "uname" ["-n"]
        if T.stripEnd host == "local-machine"
          then do d <- cmd "date"
                  c <- escaping False $ cmd "git" "log -1 | head -1 | awk '{print $2}'"
                  appendfile "log/deploy.log" $ T.intercalate " - " [T.stripEnd d, c]
                  uploads "my-server:/remote/path/" ["deploy"]
                  sshPairs_ "my-server" [("cd", ["/remote/path"]), ("./deploy", [])]
          else do
                cmd "./script/angel"

    -- same path on remote host
    -- will create directories
    uploads :: Text -> [Text] -> Sh ()
    uploads remote locals = rsync $ ["--relative"] ++ locals ++ [remote]

    rsync :: [Text] -> Sh ()
    rsync args = run_ "rsync" $ ["--delete", "-avz", "--no-g"] ++ args

Variadic arguments to cmd

Yes, as seen above 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 often use run and command variants when I am building up abstractions. Building up abstractions with cmd will require type signatures.

    -- easy signature, but only allows one argument
    let cabal = cmd "cabal" :: Text -> Sh Text

    -- more complex signature that allows partial application of cmd
    let cabal = cmd "cabal" :: Shelly.ShellCmd result => result

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 Text means you may need to convert between Text and FilePath sometimes. This should be infrequent though because:

Manual conversion is done through toTextIgnore or toTextWarn.

Thread-safe working directory and relative paths

Command 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 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 do not use the existing Shelly API, you can create a wrapper in the Sh monad that use trace or tag to log what they are doing. You can turn tracing off (not generally recommended) by setting tracing False.