HSH-2.1.2: Library to mix shell scripting with Haskell programs

Copyright | Copyright (C) 2009 John Goerzen
License | GNU LGPL, version 2.1 or above
Maintainer | John Goerzen <jgoerzen@complete.org>
Stability | provisional
Portability | portable
Safe Haskell | None
Language | Haskell98

HSH.ShellEquivs

Description

Copyright (c) 2006-2009 John Goerzen, jgoerzen@complete.org

This module provides shell-like commands. Most, but not all, are designed to be used directly as part of a HSH pipeline. All may be used outside HSH entirely as well.

Synopsis

- abspath :: FilePath -> IO FilePath
- appendTo :: FilePath -> String -> IO String
- basename :: FilePath -> FilePath
- bracketCD :: FilePath -> IO a -> IO a
- catFrom :: [FilePath] -> Channel -> IO Channel
- catBytes :: Maybe Integer -> Channel -> IO Channel
- catBytesFrom :: Channel -> Maybe Integer -> Channel -> IO Channel
- catTo :: FilePath -> Channel -> IO Channel
- catToFIFO :: FilePath -> Channel -> IO Channel
- cd :: FilePath -> IO ()
- cut :: Integer -> Char -> String -> String
- cutR :: [Integer] -> Char -> String -> String
- dirname :: FilePath -> FilePath
- discard :: Channel -> IO Channel
- echo :: Channelizable a => a -> Channel -> IO Channel
- exit :: Int -> IO a
- glob :: FilePath -> IO [FilePath]
- grep :: String -> [String] -> [String]
- grepV :: String -> [String] -> [String]
- egrep :: String -> [String] -> [String]
- egrepV :: String -> [String] -> [String]
- joinLines :: [String] -> [String]
- lower :: String -> String
- upper :: String -> String
- mkdir :: FilePath -> FileMode -> IO ()
- numberLines :: [String] -> [String]
- pwd :: IO FilePath
- readlink :: FilePath -> IO FilePath
- readlinkabs :: FilePath -> IO FilePath
- rev :: [String] -> [String]
- revW :: [String] -> [String]
- setenv :: ShellCommand cmd => [(String, String)] -> cmd -> EnvironCommand cmd
- space :: [String] -> [String]
- unspace :: [String] -> [String]
- tac :: [String] -> [String]
- tee :: [FilePath] -> Channel -> IO Channel
- teeFIFO :: [FilePath] -> Channel -> IO Channel
- tr :: Char -> Char -> String -> String
- trd :: Char -> String -> String
- wcW :: [String] -> [String]
- wcL :: [String] -> [String]
- unsetenv :: ShellCommand cmd => [String] -> cmd -> EnvironCommand cmd
- uniq :: String -> String

# Documentation

abspath :: FilePath -> IO FilePath Source #

Return the absolute path of the arg. Raises an error if the computation is impossible. This is a thin wrapper around System.Path.absNormPath. Unix/Linux users note: System.Path.absNormPath is known to produce odd results when a tilde expansion is requested; you might prefer `glob` to this function if you know your input is free of wildcards. See https:/github.comjgoerzenhshissues/7 for details.

appendTo :: FilePath -> String -> IO String Source #

Like `catTo`, but appends to the file.

basename :: FilePath -> FilePath Source #

The filename part of a path

bracketCD :: FilePath -> IO a -> IO a Source #

Changes the current working directory to the given path, executes the given I/O action, then changes back to the original directory, even if the I/O action raised an exception.

This is an alias for the MissingH function System.Path.bracketCWD.

catFrom :: [FilePath] -> Channel -> IO Channel Source #

Load the specified files and display them, one at a time.

The special file `-` means to display the input. If it is not given, no input is processed at all.

`-` may be given a maximum of one time.

See also `catBytes` .

catBytes Source #

Arguments

:: Maybe Integer | Maximum amount of data to transfer
-> Channel | Handle for input
-> IO Channel |

Copy data from input to output, optionally with a fixed maximum size, in bytes. Processes data using ByteStrings internally, so be aware of any possible UTF-8 conversions.

You may wish to use `hSetBuffering h (BlockBuffering Nothing)` prior to calling this function for optimal performance.

See also `catFrom`, `catBytesFrom`

catBytesFrom Source #

Arguments

:: Channel | Handle to read from
-> Maybe Integer | Maximum amount of data to transfer
-> Channel | Handle for input (ignored)
-> IO Channel |

Generic version of `catBytes`; reads data from specified Channel, and ignores stdin.

catTo :: FilePath -> Channel -> IO Channel Source #

Takes input, writes it to the specified file, and does not pass it on. The return value is the empty string. See also `catToBS`, `catToFIFO`

catToFIFO :: FilePath -> Channel -> IO Channel Source #

Like `catTo`, but opens the destination in ReadWriteMode instead of ReadOnlyMode. Due to an oddity of the Haskell IO system, this is required when writing to a named pipe (FIFO) even if you will never read from it.

This call will BLOCK all threads on open until a reader connects.

This is provided in addition to `catTo` because you may want to cat to something that you do not have permission to read from.

This function is only available on POSIX platforms.

See also `catTo`

cd :: FilePath -> IO () Source #

An alias for System.Directory.setCurrentDirectory.

Want to change to a user's home directory? Try this:

    glob "~jgoerzen" >>= cd . head

See also `bracketCD`.

cut :: Integer -> Char -> String -> String Source #

Split a list by a given character and select the nth list.

    cut ' ' 2 "foo bar baz quux" -> "bar"

cutR :: [Integer] -> Char -> String -> String Source #

Split a list by a given character and select ranges of the resultant lists.

    cutR [2..4] ' ' "foo bar baz quux foobar" -> "baz quux foobar"
    cutR [1..1000] ' ' "foo bar baz quux foobar" -> "bar baz quux foobar"
    cutR [-1000..1000] ' ' "foo bar baz quux foobar" -> "foo bar baz quux foobar"

Note that too large and too small indices are essentially ignored.

dirname :: FilePath -> FilePath Source #

The directory part of a path

discard :: Channel -> IO Channel Source #

Read all input and produce no output. Discards input completely.

echo :: Channelizable a => a -> Channel -> IO Channel Source #

Takes a string and sends it on as standard output.

The input to this function is never read.

You can pass this thing a String, a ByteString, or even a Handle.

See also `echoBS`.

exit :: Int -> IO a Source #

Exits with the specified error code. 0 indicates no error.

glob :: FilePath -> IO [FilePath] Source #

Takes a pattern. Returns a list of names that match that pattern. Handles:

    ~username at beginning of file to expand to user's home dir
    ? matches exactly one character
    * matches zero or more characters
    [list] matches any character in list
    [!list] matches any character not in list

The result of a tilde expansion on a nonexistant username is to do no tilde expansion.

The tilde with no username equates to the current user.

Non-tilde expansion is done by the MissingH module System.Path.Glob.

grep :: String -> [String] -> [String] Source #

Search for the string in the lines. Return those that match. Same as:

    grep needle = filter (isInfixOf needle)

grepV :: String -> [String] -> [String] Source #

Search for the string in the lines. Return those that do NOT match.

egrep :: String -> [String] -> [String] Source #

Search for the regexp in the lines. Return those that match.

egrepV :: String -> [String] -> [String] Source #

Search for the regexp in the lines. Return those that do NOT match.

joinLines :: [String] -> [String] Source #

Join lines of a file

lower :: String -> String Source #

Convert a string to all lower case

upper :: String -> String Source #

Convert a string to all upper case

mkdir :: FilePath -> FileMode -> IO () Source #

Creates the given directory. A value of 0o755 for mode would be typical.

An alias for System.Posix.Directory.createDirectory.

The second argument will be ignored on non-POSIX systems.

numberLines :: [String] -> [String] Source #

Number each line of a file

pwd :: IO FilePath Source #

An alias for System.Directory.getCurrentDirectory.

readlink :: FilePath -> IO FilePath Source #

Return the destination that the given symlink points to.

An alias for System.Posix.Files.readSymbolicLink

This function is only available on POSIX platforms.

readlinkabs :: FilePath -> IO FilePath Source #

As `readlink`, but turns the result into an absolute path.

This function is only available on POSIX platforms.

rev :: [String] -> [String] Source #

Reverse characters on each line (rev)

revW :: [String] -> [String] Source #

Reverse words on each line

Reverse characters on each line (rev)

setenv :: ShellCommand cmd => [(String, String)] -> cmd -> EnvironCommand cmd Source #

Sets an environment variable, replacing an existing one if it exists.

Here's a sample ghci session to illustrate. First, let's see the defaults for some variables:

    Prelude HSH> runIO $ "echo $TERM, $LANG"
    xterm, en_US.UTF-8

Now, let's set one:

    Prelude HSH> runIO $ setenv [("TERM", "foo")] $ "echo $TERM, $LANG"
    foo, en_US.UTF-8

Or two:

    Prelude HSH> runIO $ setenv [("TERM", "foo")] $ setenv [("LANG", "de_DE.UTF-8")] $ "echo $TERM, $LANG"
    foo, de_DE.UTF-8

We could also do it easier, like this:

    Prelude HSH> runIO $ setenv [("TERM", "foo"), ("LANG", "de_DE.UTF-8")] $ "echo $TERM, $LANG"
    foo, de_DE.UTF-8

It can be combined with unsetenv:

    Prelude HSH> runIO $ setenv [("TERM", "foo")] $ unsetenv ["LANG"] $ "echo $TERM, $LANG"
    foo,

And used with pipes:

    Prelude HSH> runIO $ setenv [("TERM", "foo")] $ "echo $TERM, $LANG" -|- "tr a-z A-Z"
    FOO, EN_US.UTF-8

See also `unsetenv`.

space :: [String] -> [String] Source #

Double space a file; add an empty line between each line.

unspace :: [String] -> [String] Source #

Inverse of double `space`; drop all empty lines.

tac :: [String] -> [String] Source #

Reverse lines in a String (like Unix tac).

Implemented as:

    tac = reverse

See `uniq`.

tee :: [FilePath] -> Channel -> IO Channel Source #

Takes input, writes it to all the specified files, and passes it on. This function does NOT buffer input.

See also `catFrom`.

teeFIFO :: [FilePath] -> Channel -> IO Channel Source #

FIFO-safe version of `tee`.

This call will BLOCK all threads on open until a reader connects.

This function is only available on POSIX platforms.

tr :: Char -> Char -> String -> String Source #

Translate a character x to y, like:

    tr 'e' 'f'

Or, in sed,

    y//

trd :: Char -> String -> String Source #

Delete specified character in a string.

wcW :: [String] -> [String] Source #

Count number of words in a file (like wc -w)

wcL :: [String] -> [String] Source #

Count number of lines. Like wc -l

unsetenv :: ShellCommand cmd => [String] -> cmd -> EnvironCommand cmd Source #

Removes an environment variable if it exists; does nothing otherwise.

See also `setenv`, which has a more extensive example.

uniq :: String -> String Source #

Remove duplicate lines from a file (like Unix uniq).

Takes a String representing a file or output and plugs it through lines and then nub to uniqify on a line basis.