https://github.com/luke-clifton/shh

Skip to content Toggle navigation
 
Sign up

  * Product
      +  
        Actions
        Automate any workflow
      +  
        Packages
        Host and manage packages
      +  
        Security
        Find and fix vulnerabilities
      +  
        Codespaces
        Instant dev environments
      +  
        Copilot
        Write better code with AI
      +  
        Code review
        Manage code changes
      +  
        Issues
        Plan and track work
      +  
        Discussions
        Collaborate outside of code
    Explore
      + All features
      + Documentation
      + GitHub Skills
      + Blog
  * Solutions
    For
      + Enterprise
      + Teams
      + Startups
      + Education
    By Solution
      + CI/CD & Automation
      + DevOps
      + DevSecOps
    Resources
      + Learning Pathways
      + White papers, Ebooks, Webinars
      + Customer Stories
      + Partners
  * Open Source
      +  
        GitHub Sponsors
        Fund open source developers
      +  
        The ReadME Project
        GitHub community articles
    Repositories
      + Topics
      + Trending
      + Collections
  * Pricing

Search or jump to...

Search code, repositories, users, issues, pull requests...

Search
[                    ]
Clear

Search syntax tips

Provide feedback

We read every piece of feedback, and take your input very seriously.

[                    ] [ ] Include my email address so I can be
contacted
Cancel Submit feedback

Saved searches

Use saved searches to filter your results more quickly

Name [                    ] 
Query [                    ]

To see all available qualifiers, see our documentation.

Cancel Create saved search
Sign in
Sign up
You signed in with another tab or window. Reload to refresh your
session. You signed out in another tab or window. Reload to refresh
your session. You switched accounts on another tab or window. Reload
to refresh your session. Dismiss alert
{{ message }}
luke-clifton / shh Public

  * Notifications
  * Fork 9
  * Star 183

Simple shell like scripting from Haskell

183 stars 9 forks Activity
Star
Notifications

  * Code
  * Issues 11
  * Pull requests 1
  * Actions
  * Projects 0
  * Security
  * Insights

Additional navigation options

  * Code
  * Issues
  * Pull requests
  * Actions
  * Projects
  * Security
  * Insights

luke-clifton/shh

This commit does not belong to any branch on this repository, and may
belong to a fork outside of the repository.
master
Switch branches/tags
[                    ]
Branches Tags
Could not load branches
Nothing to show
{{ refName }} default View all branches
Could not load tags
Nothing to show
{{ refName }} default
View all tags

Name already in use

A tag already exists with the provided branch name. Many Git commands
accept both tag and branch names, so creating this branch may cause
unexpected behavior. Are you sure you want to create this branch?
Cancel Create
2 branches 32 tags
Code

  * Local
  * Codespaces

  *  
    Clone
    HTTPS GitHub CLI
    [https://github.com/l]

    Use Git or checkout with SVN using the web URL.

    [gh repo clone luke-c]

    Work fast with our official CLI. Learn more about the CLI.

  * Open with GitHub Desktop
  * Download ZIP

Sign In Required

Please sign in to use Codespaces.

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Launching Xcode

If nothing happens, download Xcode and try again.

Launching Visual Studio Code

Your codespace will open once ready.

There was a problem preparing your codespace, please try again.

Latest commit

@luke-clifton
luke-clifton Fix reference to old function in docs.
...
f99538c Aug 28, 2023
Fix reference to old function in docs.

fixes #78

f99538c

Git stats

  * 334 commits

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
.builds
Test 9.2.4
August 11, 2022 11:55
docs
Recomend PyF as a minimal string interpolation library
November 30, 2021 15:23
shh-extras
Bump versions and fix deprecation warnings
July 17, 2023 11:02
shh
Fix reference to old function in docs.
August 28, 2023 19:25
.gitignore
Cabal Project
March 7, 2019 10:49
README.md
README tests
August 6, 2019 11:04
cabal.project
Add shh-extras
March 7, 2019 11:27
default.nix
Test multiple GHCs
December 5, 2021 09:53
release.hs
Translate release script to Haskell using Shh.
May 29, 2020 15:21
release.sh
Typo fix
March 10, 2019 10:33
View code
[                    ]
Shh Mnemonics Globbing String Interpolation/Expansion/Substitution
Usage Usage in GHCi Shh as a Shell Faster Startup Nix Wrapper Example
Script Usage Nix Alternatives Errors

README.md

 Shh

[6874747073] [6874747073] [6874747073]

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

{-# LANGUAGE TemplateHaskell #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE ExtendedDefaultRules #-}
{-# LANGUAGE QuasiQuotes #-}
module Readme (test) where

import Shh

import System.Environment
import Control.Concurrent.Async
import Prelude hiding (head)
import Test.Tasty
import Test.Tasty.HUnit
import Test.Tasty.QuickCheck
import qualified System.Directory
import qualified Data.ByteString.Lazy.Char8 as Char8
import Data.List (nub)
import Data.Char
import PyF

load SearchPath ["echo", "base64", "cat", "head", "sleep", "mktemp", "ls", "wc", "find", "tr", "users", "sha256sum", "false", "true"]

curl :: Cmd
curl = true

test :: IO ()
test = do

It's primary purpose is in replacing shell scripts. As such, many
functions are provided to mimic the shell environment, and porting
shell scripts to shh should be fairly straightforward. A simple
"cargo culting" port should work in most situations, and perhaps be
even more robust than the original.

It is also a wrapper tool around launching GHCi as a shell.

It supports

  * Automatically defining a function for each executable on your
    $PATH using template Haskell, as well as a runtime check to
    ensure they all exist on startup.

  * Redirection 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" |> base64 |> head "-n" 5

  * Multiple processes sequentially feeding a single process

      (echo 1 >> echo 2) |> cat

  * Use of Haskell's concurrency primitives.

      race (sleep 1 >> echo "Slept for 1") (sleep 2 >> echo "Slept for 2")

      mapConcurrently_ (\url -> curl "-Ls" url |> wc)
        [ "https://raw.githubusercontent.com/luke-clifton/shh/master/shell.nix"
        , "https://raw.githubusercontent.com/luke-clifton/shh/master/README.md"
        ]

  * Capturing of process output

      s <- echo "Hello" |> tr "-d" "l" |> capture
      print s

      loggedIn <- nub . Char8.words <$> (users |> capture)
      putStrLn $ "Logged in users: " ++ show loggedIn

      mapM_ Char8.putStrLn =<< (find "-maxdepth" 1 "-print0" |> captureEndBy0)

  * Capturing infinite output of a process lazily

      cat "/dev/urandom"
        |> base64
        |> readInput (mapM_ Char8.putStrLn . take 3 . Char8.lines)

  * Write strings to stdin of a process.

      writeOutput "Hello\n" |> cat
      -- Hello

      "Hello" >>> sha256sum

      sha256sum <<< "Hello"

  * 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]

      exitCode false
      --  1

  * "Native" processes, i.e. Haskell functions that behave like a
    process.

      echo "Hello" |> pureProc (Char8.map toUpper) |> tr "-d" "L"
      -- HEO

  * And much, much more! Look at the documentation on Hackage for a
    comprehensive overview of all the possibilities.

 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

 Globbing

Currently Shh does not have any built in globbing support. Rather, it
is currently suggested to use another library to do globbing. For
example, using the Glob package, it is possible to do something like

wc "--" =<< glob "*.md"

Certainly more verbose than the Bash equivalent, however, also more
explicit, which is probably a good thing. If this turns out to be too
cumbersome, we might introduce a more succinct globbing feature,
though it will always be explicit, and thus always more verbose than
most other shells.

 String Interpolation/Expansion/Substitution

String interpolation, much like globbing, is left to an external
library. I lightweight, zero-dependency solution is to use PyF,
which, since 0.10.0.1, has no dependencies other than ones included
with GHC.

greet =  do
    user <- getEnv "USER"
    echo [fmt|Hello, {user}!|]

 Usage

Some of the features in Shh require that you use the threaded
runtime. Please compile with the -threaded flag to avoid deadlocks.

Enable Template Haskell and load the environment. It is also strongly
recommended to use ExtendedDefaultRules. This is especially important
if you want to use OverloadedStrings.

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

You now have all your executables available as simple Haskell
functions. If you don't want to load your entire environment you can
load specific commands directly:

load SearchPath ["echo", "grep", "cat", "ls"]

If you want to check that all the dependencies still exist, you can
use missingExecutables :: IO [String], which will tell you if
anything is missing.

For use in a project, it makes sense to have a dedicated module for
your project which does the template Haskell above. This will prevent
recompilation of all the executables, and also allow you to easily
namespace them to avoid collisions with normal 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.

 Shh as a Shell

There is a tool called shh which is a fairly small wrapper around
launching GHCi which automatically loads your environment and allows
you to have custom config when using GHCi as a shell.

To install it, one option is to use cabal new-install

cabal new-install --lib shh
cabal new-install --lib shh-extras

The shh binary will look in your $SHH_DIR (defaults to $HOME/.shh)
for a Shell.hs, init.ghci and wrapper files. If these don't exist
default ones will be created.

The Shell.hs file should contain any top level definitions that you
would like to be available in your Shell. By default it loads your
environment.

The init.ghci file is loaded by GHCi after your .ghci files. This
lets you specify settings that you want to take effect when using
GHCi as a shell. By default it sets a shell-like prompt.

The wrapper file is an executable that is called with the command
that is to be executed. By default it just calls exec with the
arguments passed to it. The use-case for this is to be able to set up
the environment for shh. You might, for example, wrap the execution
in a nix-shell. Either way, it is up to you to make sure that the
compiler, and packages you require are available, either globally, or
provided by the wrapper script.

 Faster Startup

shh precompiles your Shell.hs file so that starting up shh is very
quick on subsequent launches. Unfortunately, shh isn't quite able to
detect this perfectly. If you see GHCi telling you that it is
Compiling Shell, and you notice the delay when starting shh, try
manually forcing a rebuild by passing in the --rebuild argument to
shh.

This is particularly likely to happen if you upgrade your GHC, or
installed packages, or even shh itself.

 Nix Wrapper Example

The following snippet could act as a wrapper file to set up a
suitable environment using nix-shell

#! /usr/bin/env nix-shell
#! nix-shell -i bash -p "(haskellPackages.ghcWithPackages (p: with p; [shh shh-extras]))"
exec "$@"

 Script Usage

 Nix

Nixpkgs provides a writeHaskellBin function which is very convenient
for writing quick scripts for your Nix setup.

writers.writeHaskellBin "example" {libraries = [haskellPackages.shh];} ''
  {-# LANGUAGE TemplateHaskell #-}
  import Shh

  -- Load binaries from Nix packages. The dependencies will be captured
  -- in the closure.
  loadFromBins ["${git}", "${coreutils}", "${curl}"]

  main :: IO ()
  main = do
    cat "/a/file"
    cp "/a/file" "/b/file"
''

 Alternatives

There are quite a few players in the "shell programming for Haskell"
field.

This table attempts to summarise some of the differences.

  * Pipe Style refers to how processes are joined together, "native"
    means that the mechanisms provided by the OS are used, while "via
    Haskell" means that the data is read into the Haskell process,
    and then written into the subprocess.
  * Via Shell refers to whether subprocesses are launched directly or
    via a shell (which can provide a "native" piping solution at the
    cost of composability)
  * Run in IO refers to whether commands need to be prefixed with run
    or similar functions to actually execute them.
  * TH Helper refers to whether the use of TH to generate Haskell
    functions based on commands found at compile time is encouraged
    in the main library.
  * Monadic Subshell refers to the ability to join multiple processes
    together and feed them all from the same input and to the same
    output. echo a | (cat; echo b) | wc -l should report that 2 lines
    appeared.

               Pipe     Via    Run Threadsafe   TH      Monadic    Redirect
   Library     Style   Shell   in      cd     Helper   Subshell     stderr
                               IO
Shh           Native  No       Yes No         Yes    Yes           Yes
Shelly        Via     Yes      No  Yes        No     No            Yes
              Haskell
Turtle        Via     Optional No  ?          No     No            Yes
              Haskell                                (Alternative)
shell-conduit Via     Optional No  ?          Yes    Yes           No?
              Haskell

 Errors

   Library     Exception on     Contains     Contains    Terminates
                 non-zero       arguments     stderr      pipeline
Shh           Yes             Yes           Optional    Yes
Shelly        Yes             Yes           Yes         Yes
Turtle        Sometimes       No            No          ?
shell-conduit Yes             Yes           No          No

About

Simple shell like scripting from Haskell

Resources

Readme
Activity

Stars

183 stars

Watchers

9 watching

Forks

9 forks
Report repository

Releases

32 tags

Packages 0

No packages published

Contributors 6

  * @luke-clifton
  * @maralorn
  * @jhrcek
  * @tomjaguarpaw
  * @pbarill
  * @kozross

Languages

  * Haskell 96.1%
  * Shell 3.0%
  * Nix 0.9%

Footer

 (c) 2023 GitHub, Inc.

Footer navigation

  * Terms
  * Privacy
  * Security
  * Status
  * Docs
  * Contact GitHub
  * Pricing
  * API
  * Training
  * Blog
  * About

You can't perform that action at this time.