shh: Simple shell scripting from Haskell

[ bsd3, library, program, system ] [ Propose Tags ]

Provides a shell scripting environment for Haskell. It helps you all external binaries, and allows you to perform many shell-like functions, such as piping and redirection.


[Skip to Readme]

Modules

[Last Documentation]

  • Shh
    • Shh.Example
    • Shh.Internal

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

  • No Candidates
Versions [RSS] 0.1.0.0, 0.1.0.1, 0.1.1.0, 0.2.0.0, 0.2.0.1, 0.2.0.2, 0.2.0.3, 0.2.0.4, 0.2.0.5, 0.2.0.6, 0.3.0.0, 0.3.0.1, 0.3.1.0, 0.3.1.1, 0.3.1.2, 0.3.1.3, 0.4.0.0, 0.4.0.1, 0.5.0.0, 0.6.0.0, 0.7.0.0, 0.7.0.1, 0.7.0.2, 0.7.0.3, 0.7.0.4, 0.7.0.5, 0.7.0.6, 0.7.0.7, 0.7.0.8, 0.7.1.0, 0.7.1.1, 0.7.1.2, 0.7.1.3, 0.7.1.4, 0.7.2.0, 0.7.2.1, 0.7.2.2, 0.7.3.0
Change log ChangeLog.md
Dependencies async, base (>=4.9 && <4.13), deepseq, directory, filepath, mtl, process, shh, split, template-haskell, unix [details]
License BSD-3-Clause
Copyright (c) 2018 Luke Clifton
Author Luke Clifton
Maintainer lukec@themk.net
Revised Revision 1 made by lukec at 2018-11-22T09:21:25Z
Category System
Source repo head: git clone https://github.com/luke-clifton/shh
Uploaded by lukec at 2018-11-02T11:19:36Z
Distributions NixOS:0.7.3.0
Reverse Dependencies 1 direct, 0 indirect [details]
Executables shh-example
Downloads 14593 total (91 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
All reported builds failed as of 2018-11-02 [all 2 reports]

Readme for shh-0.1.0.0

[back to package description]

Shh

Shh is a library to enable convinient shell-like programming in Haskell. It works well in scripts, and from GHCi, allowing you to use GHCi as a shell.

It supports

  • Automatically defining a function for each executable on your $PATH using template Haskell.

  • Redirction of stdout and stderr

    -- Redirect stdout
    λ echo "Hello" &> StdErr
    λ echo "Hello" &> Truncate ".tmp_file"
    
    -- Redirect stderr
    λ echo "Hello" &!> Append "/dev/null"
    λ echo "Hello" &!> StdOut
    
  • Piping stdout or stderr to the input of a chained process

    λ cat "/dev/urandom" |> xxd |> head "-n" 5
    
  • Multiple processes sequentially feeding a single process

    λ (echo 1 >> echo 2) |> cat
    
  • Use of Haskells concurrency primitives.

    λ race (sleep 1) $ curl "http://this_needs_to_timeout_after_1_second"
    
    λ d <- readTrim $ mktemp "-d"
    λ :{
    | System.Directory.withCurrentDirectory d $ do
    |   mapConcurrently_ (curl "-LOJs")
    |     [ "https://raw.githubusercontent.com/luke-clifton/shh/master/shell.nix"
    |     , "https://raw.githubusercontent.com/luke-clifton/shh/master/shh.cabal"
    |     ]
    |   ls
    | :}
    
  • Capturing of process output

    λ loggedIn <- nub . words <$> readProc users
    λ putStrLn $ "Logged in users: " ++ show loggedIn
    
    λ mapM_ putStrLn =<< readSplit0 (Shh.Example.find "-maxdepth" 1 "-print0")
    
  • Capturing infinite output of a process lazily

    λ withRead (cat "/dev/urandom" |> xxd) $ mapM_ putStrLn . take 3 . lines
    00000000: 8fcb ebee 9228 a897 3bfc 1d05 491d aceb  .....(..;...I...
    00000010: 47de 3ea3 2788 44ac 9b85 0a0f a458 b949  G.>.'.D......X.I
    00000020: 5308 ddfe 5790 5a5f 39e3 bbb6 b689 2b03  S...W.Z_9.....+.
    
  • Write strings to stdin of a process.

    λ writeProc cat "Hello\n"
    Hello
    
    λ "Hello" >>> shasum
    f7ff9e8b7bb2e09b70935a5d785e0cc5d9d0abf0  -
    
    λ shasum <<< "Hello"
    f7ff9e8b7bb2e09b70935a5d785e0cc5d9d0abf0  -
    
  • Proper exceptions, when a process exits with a failure code, an exception is thrown. You can catch these normally. The exception includes the error code, the command, and all it's arguments.

    λ false "Ha, it died"
    *** Exception: Command `false "Ha, it died"` failed [exit 1]
    
    λ catchCode false
    1
    

Mnemonics

Shh has many symbols that might seem intimidating at first, but there is a simple mnemonic for them.

|     Piping. Looks like a pipe, same as in POSIX shells.
&     Redirection, think of the shell `2>&1`
>,<   The direction of flow of a command
!     Operate on stderr instead of stdout

So, for example,

ls |> cat      Pipe the stdout of `ls` into stdin of `cat`
cat <| ls      Same as above
ls &> StdErr   Redirect stdout of `ls` to wherever stderr is going.
StdErr <& ls   Same as above
ls &!> StdOut  Redirect stderr of `ls` to wherever stdout is going.
StdOut <!& ls  Same as above

Usage

Enable Temlpate Haskell and load the environment

{-# LANGUAGE TemplateHaskell #-}
$(loadEnv)

You now have all your executables available as simple to read Haskell functions.

Usage in GHCi

If you want ^D to be recognised as a EOF marker (when running commands that read from stdin) when running in GHCi, you will need to run the initInteractive function. This sets the line buffering appropriately and ensures the terminal is in canonical mode.

Script Usage

TODO: Fill this in once on Hackage.