turtle-1.6.2: Shell programming, Haskell-style

Safe Haskell | None
Language | Haskell2010

Turtle.Bytes

Contents

- Byte operations
- Subprocess management

Description

This module provides `ByteString` analogs of several utilities in Turtle.Prelude. The main difference is that the chunks of bytes read by these utilities are not necessarily aligned to line boundaries.

Synopsis

- stdin :: Shell ByteString
- input :: FilePath -> Shell ByteString
- inhandle :: Handle -> Shell ByteString
- stdout :: MonadIO io => Shell ByteString -> io ()
- output :: MonadIO io => FilePath -> Shell ByteString -> io ()
- outhandle :: MonadIO io => Handle -> Shell ByteString -> io ()
- append :: MonadIO io => FilePath -> Shell ByteString -> io ()
- stderr :: MonadIO io => Shell ByteString -> io ()
- strict :: MonadIO io => Shell ByteString -> io ByteString
- compress :: Int -> WindowBits -> Shell ByteString -> Shell ByteString
- decompress :: WindowBits -> Shell ByteString -> Shell ByteString
- newtype WindowBits = WindowBits Int
- defaultWindowBits :: WindowBits
- fromUTF8 :: Shell Text -> Shell ByteString
- toUTF8 :: Shell ByteString -> Shell Text
- proc :: MonadIO io => Text -> [Text] -> Shell ByteString -> io ExitCode
- shell :: MonadIO io => Text -> Shell ByteString -> io ExitCode
- procs :: MonadIO io => Text -> [Text] -> Shell ByteString -> io ()
- shells :: MonadIO io => Text -> Shell ByteString -> io ()
- inproc :: Text -> [Text] -> Shell ByteString -> Shell ByteString
- inshell :: Text -> Shell ByteString -> Shell ByteString
- inprocWithErr :: Text -> [Text] -> Shell ByteString -> Shell (Either ByteString ByteString)
- inshellWithErr :: Text -> Shell ByteString -> Shell (Either ByteString ByteString)
- procStrict :: MonadIO io => Text -> [Text] -> Shell ByteString -> io (ExitCode, ByteString)
- shellStrict :: MonadIO io => Text -> Shell ByteString -> io (ExitCode, ByteString)
- procStrictWithErr :: MonadIO io => Text -> [Text] -> Shell ByteString -> io (ExitCode, ByteString, ByteString)
- shellStrictWithErr :: MonadIO io => Text -> Shell ByteString -> io (ExitCode, ByteString, ByteString)
- system :: MonadIO io => CreateProcess -> Shell ByteString -> io ExitCode
- stream :: CreateProcess -> Shell ByteString -> Shell ByteString
- streamWithErr :: CreateProcess -> Shell ByteString -> Shell (Either ByteString ByteString)
- systemStrict :: MonadIO io => CreateProcess -> Shell ByteString -> io (ExitCode, ByteString)
- systemStrictWithErr :: MonadIO io => CreateProcess -> Shell ByteString -> io (ExitCode, ByteString, ByteString)

# Byte operations

stdin :: Shell ByteString #

Read chunks of bytes from standard input

The chunks are not necessarily aligned to line boundaries

input :: FilePath -> Shell ByteString #

Read chunks of bytes from a file

The chunks are not necessarily aligned to line boundaries

inhandle :: Handle -> Shell ByteString #

Read chunks of bytes from a `Handle`

The chunks are not necessarily aligned to line boundaries

stdout :: MonadIO io => Shell ByteString -> io () #

Stream chunks of bytes to standard output

The chunks are not necessarily aligned to line boundaries

output :: MonadIO io => FilePath -> Shell ByteString -> io () #

Stream chunks of bytes to a file

The chunks do not need to be aligned to line boundaries

outhandle :: MonadIO io => Handle -> Shell ByteString -> io () #

Stream chunks of bytes to a `Handle`

The chunks do not need to be aligned to line boundaries

append :: MonadIO io => FilePath -> Shell ByteString -> io () #

Append chunks of bytes to append to a file

The chunks do not need to be aligned to line boundaries

stderr :: MonadIO io => Shell ByteString -> io () #

Stream chunks of bytes to standard error

The chunks do not need to be aligned to line boundaries

strict :: MonadIO io => Shell ByteString -> io ByteString #

Read in a stream's contents strictly

compress #

Arguments

:: Int | Compression level
-> WindowBits |
-> Shell ByteString |
-> Shell ByteString |

Compress a stream using `zlib`

Note that this can decompress streams that are the concatenation of multiple compressed streams (just like `gzip`)

    >>> let compressed = select [ "ABC", "DEF" ] & compress 0 defaultWindowBits
    >>> compressed & decompress defaultWindowBits & view
    "ABCDEF"
    >>> (compressed <|> compressed) & decompress defaultWindowBits & view
    "ABCDEF"
    "ABCDEF"

decompress :: WindowBits -> Shell ByteString -> Shell ByteString #

Decompress a stream using `zlib` (just like the `gzip` command)

newtype WindowBits #

This specifies the size of the compression window. Larger values of this parameter result in better compression at the expense of higher memory usage.

The compression window size is the value of the the window bits raised to the power 2. The window bits must be in the range `9..15` which corresponds to compression window sizes of 512b to 32Kb. The default is 15 which is also the maximum size.

The total amount of memory used depends on the window bits and the `MemoryLevel`. See the `MemoryLevel` for the details.

Constructors

WindowBits Int |

#### Instances

Instances details

Generic WindowBits |
Instance details Defined in Codec.Compression.Zlib.Stream Associated Types
type Rep WindowBits |
Instance details Defined in Codec.Compression.Zlib.Stream type Rep WindowBits = D1 ('MetaData "WindowBits" "Codec.Compression.Zlib.Stream" "zlib-0.7.1.0-1mOT4jASaJp8whxsM9AySZ" 'True) (C1 ('MetaCons "WindowBits" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Int)))
Methods from :: WindowBits -> Rep WindowBits x # to :: Rep WindowBits x -> WindowBits #
Show WindowBits |
Instance details Defined in Codec.Compression.Zlib.Stream Methods showsPrec :: Int -> WindowBits -> ShowS # show :: WindowBits -> String # showList :: [WindowBits] -> ShowS #
Eq WindowBits |
Instance details Defined in Codec.Compression.Zlib.Stream Methods (==) :: WindowBits -> WindowBits -> Bool # (/=) :: WindowBits -> WindowBits -> Bool #
Ord WindowBits |
Instance details Defined in Codec.Compression.Zlib.Stream Methods compare :: WindowBits -> WindowBits -> Ordering # (<) :: WindowBits -> WindowBits -> Bool # (<=) :: WindowBits -> WindowBits -> Bool # (>) :: WindowBits -> WindowBits -> Bool # (>=) :: WindowBits -> WindowBits -> Bool # max :: WindowBits -> WindowBits -> WindowBits # min :: WindowBits -> WindowBits -> WindowBits #
type Rep WindowBits |
Instance details Defined in Codec.Compression.Zlib.Stream type Rep WindowBits = D1 ('MetaData "WindowBits" "Codec.Compression.Zlib.Stream" "zlib-0.7.1.0-1mOT4jASaJp8whxsM9AySZ" 'True) (C1 ('MetaCons "WindowBits" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Int)))

defaultWindowBits :: WindowBits #

The default `WindowBits`. Equivalent to ``windowBits` 15`. which is also the maximum size.

fromUTF8 :: Shell Text -> Shell ByteString #

Encode a stream of bytes as UTF8 `Text`

toUTF8 :: Shell ByteString -> Shell Text #

Decode a stream of bytes as UTF8 `Text`

NOTE: This function will throw a pure exception (i.e. an `error`) if UTF8 decoding fails (mainly due to limitations in the `text` package's stream decoding API)

# Subprocess management

proc #

Arguments

:: MonadIO io |
=> Text | Command
-> [Text] | Arguments
-> Shell ByteString | Chunks of bytes written to process input
-> io ExitCode | Exit code

Run a command using `execvp`, retrieving the exit code

The command inherits `stdout` and `stderr` for the current process

shell #

Arguments

:: MonadIO io |
=> Text | Command line
-> Shell ByteString | Chunks of bytes written to process input
-> io ExitCode | Exit code

Run a command line using the shell, retrieving the exit code

This command is more powerful than `proc`, but highly vulnerable to code injection if you template the command line with untrusted input

The command inherits `stdout` and `stderr` for the current process

procs #

Arguments

:: MonadIO io |
=> Text | Command
-> [Text] | Arguments
-> Shell ByteString | Chunks of bytes written to process input
-> io () |

This function is identical to `proc` except this throws `ProcFailed` for non-zero exit codes

shells #

Arguments

:: MonadIO io |
=> Text | Command line
-> Shell ByteString | Chunks of bytes written to process input
-> io () | Exit code

This function is identical to `shell` except this throws `ShellFailed` for non-zero exit codes

inproc #

Arguments

:: Text | Command
-> [Text] | Arguments
-> Shell ByteString | Chunks of bytes written to process input
-> Shell ByteString | Chunks of bytes read from process output

Run a command using `execvp`, streaming `stdout` as chunks of `ByteString`

The command inherits `stderr` for the current process

inshell #

Arguments

:: Text | Command line
-> Shell ByteString | Chunks of bytes written to process input
-> Shell ByteString | Chunks of bytes read from process output

Run a command line using the shell, streaming `stdout` as chunks of `ByteString`

This command is more powerful than `inproc`, but highly vulnerable to code injection if you template the command line with untrusted input

The command inherits `stderr` for the current process

inprocWithErr #

Arguments

:: Text | Command
-> [Text] | Arguments
-> Shell ByteString | Chunks of bytes written to process input
-> Shell (Either ByteString ByteString) | Chunks of either output (`Right`) or error (`Left`)

Run a command using the shell, streaming `stdout` and `stderr` as chunks of `ByteString`. Chunks from `stdout` are wrapped in `Right` and chunks from `stderr` are wrapped in `Left`.

Throws an `ExitCode` exception if the command returns a non-zero exit code

inshellWithErr #

Arguments

:: Text | Command line
-> Shell ByteString | Chunks of bytes written to process input
-> Shell (Either ByteString ByteString) | Chunks of either output (`Right`) or error (`Left`)

Run a command line using the shell, streaming `stdout` and `stderr` as chunks of `ByteString`. Chunks from `stdout` are wrapped in `Right` and chunks from `stderr` are wrapped in `Left`.

This command is more powerful than `inprocWithErr`, but highly vulnerable to code injection if you template the command line with untrusted input

Throws an `ExitCode` exception if the command returns a non-zero exit code

procStrict #

Arguments

:: MonadIO io |
=> Text | Command
-> [Text] | Arguments
-> Shell ByteString | Chunks of bytes written to process input
-> io (ExitCode, ByteString) | Exit code and stdout

Run a command using `execvp`, retrieving the exit code and stdout as a non-lazy blob of Text

The command inherits `stderr` for the current process

shellStrict #

Arguments

:: MonadIO io |
=> Text | Command line
-> Shell ByteString | Chunks of bytes written to process input
-> io (ExitCode, ByteString) | Exit code and stdout

Run a command line using the shell, retrieving the exit code and stdout as a non-lazy blob of Text

This command is more powerful than `proc`, but highly vulnerable to code injection if you template the command line with untrusted input

The command inherits `stderr` for the current process

procStrictWithErr #

Arguments

:: MonadIO io |
=> Text | Command
-> [Text] | Arguments
-> Shell ByteString | Chunks of bytes written to process input
-> io (ExitCode, ByteString, ByteString) | (Exit code, stdout, stderr)

Run a command using `execvp`, retrieving the exit code, stdout, and stderr as a non-lazy blob of Text

shellStrictWithErr #

Arguments

:: MonadIO io |
=> Text | Command line
-> Shell ByteString | Chunks of bytes written to process input
-> io (ExitCode, ByteString, ByteString) | (Exit code, stdout, stderr)

Run a command line using the shell, retrieving the exit code, stdout, and stderr as a non-lazy blob of Text

This command is more powerful than `proc`, but highly vulnerable to code injection if you template the command line with untrusted input

system #

Arguments

:: MonadIO io |
=> CreateProcess | Command
-> Shell ByteString | Chunks of bytes written to process input
-> io ExitCode | Exit code

`system` generalizes `shell` and `proc` by allowing you to supply your own custom `CreateProcess`. This is for advanced users who feel comfortable using the lower-level `process` API

stream #

Arguments

:: CreateProcess | Command
-> Shell ByteString | Chunks of bytes written to process input
-> Shell ByteString | Chunks of bytes read from process output

`stream` generalizes `inproc` and `inshell` by allowing you to supply your own custom `CreateProcess`. This is for advanced users who feel comfortable using the lower-level `process` API

Throws an `ExitCode` exception if the command returns a non-zero exit code

streamWithErr #

Arguments

:: CreateProcess | Command
-> Shell ByteString | Chunks of bytes written to process input
-> Shell (Either ByteString ByteString) | Chunks of bytes read from process output

`streamWithErr` generalizes `inprocWithErr` and `inshellWithErr` by allowing you to supply your own custom `CreateProcess`. This is for advanced users who feel comfortable using the lower-level `process` API

Throws an `ExitCode` exception if the command returns a non-zero exit code

systemStrict #

Arguments

:: MonadIO io |
=> CreateProcess | Command
-> Shell ByteString | Chunks of bytes written to process input
-> io (ExitCode, ByteString) | Exit code and stdout

`systemStrict` generalizes `shellStrict` and `procStrict` by allowing you to supply your own custom `CreateProcess`. This is for advanced users who feel comfortable using the lower-level `process` API

systemStrictWithErr #

Arguments

:: MonadIO io |
=> CreateProcess | Command
-> Shell ByteString | Chunks of bytes written to process input
-> io (ExitCode, ByteString, ByteString) | Exit code and stdout

`systemStrictWithErr` generalizes `shellStrictWithErr` and `procStrictWithErr` by allowing you to supply your own custom `CreateProcess`. This is for advanced users who feel comfortable using the lower-level `process` API