-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Archive execution tool.
--
-- The ARX system provides services for packaging, deploying and
-- running source code. No particular format or framework is needed -- a
-- directory of code and a command to run are enough. The system has no
-- in-built notion of remote connections, job servers or clusters; all
-- automation is captured as Bourne compatible scripts.
--
-- An archive of the source code, a command and optionally an environment
-- are encoded together in a Bourne shell script that uses a small number
-- of UNIX utilities in a broadly portable way. The generated scripts can
-- be run directly or fed to sh on STDIN. This latter feature is
-- useful when one would like to use ssh and sudo to
-- set an appropriate executation context, for example running: ssh
-- user@example.com sudo sh.
--
-- The shell tools used are head, sed, date,
-- tr and tar. The calls to tar sometimes use
-- -j and -z; these calls to tar may result in
-- calls to bzip2 and gzip. Scripts have been tested
-- with dash and the GNU tools as well as the sh and
-- tools that are part of busybox.
--
-- The arx command line tool provides the tmpx
-- subcommand for preparing jobs to run and the shdat subcommand
-- for access to the low-level shell encoder. The
-- System.Posix.ARX module provides access to the routines used
-- for constructing commands and environments, describing archives and
-- building Bourne shell scripts.
--
-- One way I have used arx is to test the Cabal source archive
-- for this package:
--
--
-- arx tmpx ./dist/arx-* // 'cd arx-* && cabal configure && cabal build' | sh
--
--
-- There are binary arx command line tool releases available
-- from:
--
-- https://github.com/solidsnack/arx/downloads
--
-- For each supported platform, there is an archive containing
-- arx and signature files (SHA 512 and GPG).
@package arx
@version 0.2.0
module System.Posix.ARX.BlazeIsString
instance IsString Builder
module System.Posix.ARX.TMPXTools
data Template
Template :: Bool -> Bool -> Builder -> Builder -> Builder -> Template
-- | Remove tmp on run success?
rm0 :: Template -> Bool
-- | Remove tmp on run error?
rm1 :: Template -> Bool
-- | Stream for env text.
env :: Template -> Builder
-- | Stream for run text.
run :: Template -> Builder
-- | Data unpacking text.
dat :: Template -> Builder
render :: Template -> Builder
findChunks :: ByteString -> [ByteString]
coalesce :: [Maybe ByteString] -> [ByteString]
markHoles :: ByteString -> [Maybe ByteString]
isHole :: ByteString -> Bool
instance Show Template
-- | Utilities for encoding arbitrary data as Bourne shell fragments that
-- stream the data to standard output, using HERE documents and simple
-- shell decoders.
module System.Posix.ARX.HEREDat
-- | A chunk describes a block of binary data ready for inclusion in a
-- shell script. For many data blocks, no encoding or decoding is
-- necessary; these are stored in a SafeChunk. Those blocks
-- needing byte-translation are stored in an EncodedChunk.
data Chunk
SafeChunk :: !ByteString -> Chunk
EncodedChunk :: !ByteString -> !Int -> !EscapeChar -> !EscapeChar -> Chunk
-- | Converts a ByteString into a string safe for inclusion in a
-- shell HERE document and annotates with information to construct a
-- shell decoder for that document, if necessary.
--
-- A ByteString with nulls is rewritten in a complicated way. Two
-- escape characters are chosen from a class of ASCII printable
-- characters that look like reasonable escape characters; the two that
-- show up least frequently in the document (including 0 times) become
-- the null replacer and the escaper. All instances of these two
-- characters are rewritten to escape sequences formed with the escaper,
-- while nulls are rewritten to the null replacer. Given the two
-- characters thus chosen, a command line with tr and
-- sed in sequence can be constructed to decode the document.
--
-- This encoding doubles the amount of space consumed by the escape
-- characters. In the worst case, where the data is made of all 20
-- potential escapes, evenly distributed, and one null (so we can't punt
-- on escaping), the data will grow in size by 10 percent. For data that
-- is more evenly distributed over the bytes -- as we might expect of
-- compressed tarballs -- we expect a size growth of two 256ths, or less
-- than 0.8 percent.
chunk :: ByteString -> Chunk
-- | Given a byte to replace nulls and an escape byte, rewrites the data
-- such that nulls are mapped to the replace byte, replace bytes are
-- mapped to a pair of escape bytes and the escape byte is is mapped to
-- an escape byte followed by an underscore. For example, if the null
-- replace byte is ! and the escape byte is # then all
-- nulls become !, any ! become ## and all
-- # become #_.
--
-- This escaping scheme is dictated by the needs of our Sed decoder,
-- which is just two global substitions, one after another. If the
-- escaping were such that, with our characters above, # escaped
-- to ## and ! to #_, then #_ in the
-- input becomes ##_. We want to run the subsitution for
-- # first, to catch this; it produces #_; then Sed
-- feeds the input to the second substitution which unfortunately renders
-- !. In the alternate scheme, the input is encoded
-- #__, the ! decoder runs first and ignores it, then
-- the # decoder runs and catches it. When using a pipeline of
-- stream processors to interpret escape sequences, it seems best to
-- ensure that only the very last processor inserts escape characters, to
-- prevent their further interpretation.
encode :: Word8 -> Word8 -> ByteString -> ByteString
-- | Given the byte used to replace nulls and the escape byte, undoes the
-- result of the encode operation -- rewriting null replacers to literal
-- nulls and escape patterns to the original bytes. This function is not
-- intended to be used in practice -- it will be shell commands that
-- unpack the data -- but serves to document the ideas behind decoding as
-- well as offering a way to check the encoder.
decode :: Word8 -> Word8 -> ByteString -> ByteString
data EscapeChar
EscapeChar :: !Word8 -> !ByteString -> !ByteString -> !ByteString -> EscapeChar
-- | The candidate escape characters, with the forms to be used in
-- constructed tr and sed commands.
escapes :: [EscapeChar]
-- | Many binary strings can be embedded as-is in a HEREDOC, without
-- escaping.
safeForHereDoc :: ByteString -> Bool
-- | Predicate to determine whether data is represented as an encoded chunk
-- or is unencoded.
encoded :: Chunk -> Bool
script :: Chunk -> Builder
instance Show EscapeChar
instance Show Chunk
instance IsString Chunk
-- | The CLTokens module describes non-overlapping classes of strings that
-- are useful for disambiguating arguments to command line programs. Many
-- common string formats -- environment variable assignments, URLs,
-- option strings -- are recognized by this module's utilities.
module System.Posix.ARX.CLI.CLTokens
-- | Non-overlapping classes of command line argument strings.
data Class
-- | An EnvBinding has the form var
-- name=string. For example, SENDIN=the_clowns.
EnvBinding :: Class
-- | A QualifiedPath is a file path starting with @,
-- @., or ../.
QualifiedPath :: Class
-- | A DashDash is a string of two dashes, --, commonly
-- used to indicate the end of options processing.
DashDash :: Class
-- | A LongOption is a string beginning with two dashes and then at
-- least one non-dash.
LongOption :: Class
-- | A Dash is a single dash, -, commonly used to indicate
-- input from stdin or output to stdout.
Dash :: Class
-- | A ShortOption is a beginning with a dash and then at least one
-- non-dash.
ShortOption :: Class
-- | A URL is a scheme, separated from the resource, represented as
-- an arbitrary string, by :. The scheme consists of
-- ASCII, lower-case letters and digits, and may be multi-part, with each
-- part separated by a + or / (for example,
-- git+ssh). An example URL:
-- http:example.com/?q=special.
URL :: Class
-- | A HexNum is a sequence of hexadecimal digits, upper or lower
-- case, beginning with 0x; for example: 0x01a3.
HexNum :: Class
-- | A DecimalNum is a string of decimal digits: 123123.
DecimalNum :: Class
-- | A Size is a decimal number followed by a multiplicative suffix,
-- in the manner of dd or head. Note that counts in
-- terms of bytes require B (unlike dd or
-- head). For a full list of suffixes, see sizes below.
Size :: Class
-- | Determine if a particular ByteString matches the given
-- Class of token.
match :: Class -> ByteString -> Bool
-- | Determine if a particular ByteString matches any Class
-- of token.
recognize :: ByteString -> Maybe Class
-- | A ByteString stand-in that demoes each token class.
exemplar :: Class -> ByteString
-- | The recognizer appropriate to each token class. Parses successfully if
-- a the token class is recognized, returning '()'. Most token types are
-- defined in terms of a prefix of the input -- for example,
-- QualifiedPath -- and the parsers for these tokens naturally
-- return as soon as the prefix is recognized.
recognizer :: Class -> Parser ()
schemeSeparator :: Parser ByteString Word8
varFirst :: Char -> Bool
varBody :: Char -> Bool
isLongOptionChar :: Char -> Bool
isShortOptionChar :: Char -> Bool
isSchemeChar :: Char -> Bool
isHexDigit :: Char -> Bool
isURLSchemeChar :: Char -> Bool
-- | A map from suffixes to sizes, following the conventions of command
-- line tools (GNU dd or head and many others) as well
-- as the standard for binary sizes established by the IEC. B = 1 K
-- = KiB = 1024B kB = 1000B M = MiB = 1024K MB = 1000kB G = GiB = 1024M
-- GB = 1000MB T = TiB = 1024G TB = 1000GB P = PiB = 1024T PB = 1000TB E
-- = EiB = 1024P EB = 1000PB Z = ZiB = 1024E ZB = 1000EB Y = YiB = 1024Z
-- YB = 1000ZB
sizes :: Map ByteString Integer
-- | Parse a size, consuming the entire input string.
size :: Parser Integer
-- | Parse a size, consuming the entire input string, with the final result
-- bounded by the maximum of a Bounded type.
sizeBounded :: (Bounded b, Integral b) => Parser b
instance Show Class
instance Ord Class
instance Eq Class
module System.Posix.ARX.Tar
-- | Handled styles of Tar archive.
data Tar
TAR :: Tar
TGZ :: Tar
TBZ :: Tar
-- | Scan a lazy ByteString for file magic.
magic :: ByteString -> Maybe Tar
bzMagic :: ByteString -> Bool
gzMagic :: ByteString -> Bool
tarMagic :: ByteString -> Bool
instance Show Tar
instance Ord Tar
instance Eq Tar
-- | Utilities for working with shell script.
module System.Posix.ARX.Sh
-- | Valid shell string values contain any byte but null.
data Val
val :: ByteString -> Maybe Val
-- | Valid shell variable names consist of a leading letter or underscore
-- and then any number of letters, underscores or digits.
data Var
var :: ByteString -> Maybe Var
setEU :: Builder
class Render t
render :: Render t => t -> Builder
class Raw t
raw :: Raw t => t -> ByteString
instance Show Var
instance Ord Var
instance Eq Var
instance Show Val
instance Ord Val
instance Eq Val
instance Render [Val]
instance Render [(Var, Val)]
instance Raw Var
instance Render Var
instance Raw Val
instance Render Val
module System.Posix.ARX.CLI.Options
shdat :: ArgsParser ([Word], [IOStream], [IOStream])
tmpx :: ArgsParser ([Word], [IOStream], [IOStream], [(Var, Val)], [(Bool, Bool)], [ByteSource])
blockSize :: ArgsParser Word
outputFile :: ArgsParser IOStream
ioStream :: ArgsParser IOStream
qPath :: ArgsParser ByteString
rm :: ArgsParser (Bool, Bool)
env :: ArgsParser (Var, Val)
scriptToRun :: ArgsParser ByteSource
cmd :: ByteString -> ArgsParser ByteSource
-- | A byte-oriented store that can be read from or written to in a
-- streaming fashion.
data IOStream
STDIO :: IOStream
Path :: !ByteString -> IOStream
-- | A source of bytes (no writing, only reading).
data ByteSource
ByteString :: !ByteString -> ByteSource
IOStream :: !IOStream -> ByteSource
type ArgsParser = Parsec [ByteString] ()
satisfy :: (ByteString -> Bool) -> ArgsParser ByteString
anyArg :: ArgsParser ByteString
arg :: ByteString -> ArgsParser ByteString
argPrim :: (ByteString -> Maybe t) -> ArgsParser t
(<@>) :: Parser t -> ArgsParser ByteString -> ArgsParser t
tokCL :: Class -> ArgsParser ByteString
slashes :: ArgsParser (Maybe ByteString)
instance Show ByteSource
instance Ord ByteSource
instance Eq ByteSource
instance Show IOStream
instance Ord IOStream
instance Eq IOStream
module System.Posix.ARX.Programs
-- | ARX subprograms process some input to produce a script.
class ARX program input | program -> input
interpret :: ARX program input => program -> input -> Builder
-- | An SHDAT program processes byte streams with the specified
-- chunking to produce a script.
newtype SHDAT
SHDAT :: Word -> SHDAT
-- | A TMPX program archives streams to produce a script that
-- unpacks the file data in a temporary location and runs the command
-- with the attached environment information in that location. The
-- command may be any executable file contents, modulo architectural
-- compatibility. It is written along side the temporary work location,
-- to ensure it does not collide with any files in the archive. The two
-- boolean flags determine when to delete the temporary directory. The
-- first flag determines whether or not to delete successful (exit code
-- zero) runs; the second determines whether or not to delete failed
-- (exit code non-zero) runs.
data TMPX
TMPX :: SHDAT -> ByteString -> [(Var, Val)] -> Bool -> Bool -> TMPX
instance ARX TMPX [(Tar, ByteString)]
instance ARX SHDAT ByteString
module System.Posix.ARX
-- | ARX subprograms process some input to produce a script.
class ARX program input | program -> input
interpret :: ARX program input => program -> input -> Builder
-- | An SHDAT program processes byte streams with the specified
-- chunking to produce a script.
newtype SHDAT
SHDAT :: Word -> SHDAT
-- | A TMPX program archives streams to produce a script that
-- unpacks the file data in a temporary location and runs the command
-- with the attached environment information in that location. The
-- command may be any executable file contents, modulo architectural
-- compatibility. It is written along side the temporary work location,
-- to ensure it does not collide with any files in the archive. The two
-- boolean flags determine when to delete the temporary directory. The
-- first flag determines whether or not to delete successful (exit code
-- zero) runs; the second determines whether or not to delete failed
-- (exit code non-zero) runs.
data TMPX
TMPX :: SHDAT -> ByteString -> [(Var, Val)] -> Bool -> Bool -> TMPX
-- | Valid shell string values contain any byte but null.
data Val
val :: ByteString -> Maybe Val
-- | Valid shell variable names consist of a leading letter or underscore
-- and then any number of letters, underscores or digits.
data Var
var :: ByteString -> Maybe Var
-- | Handled styles of Tar archive.
data Tar
TAR :: Tar
TGZ :: Tar
TBZ :: Tar
-- | Scan a lazy ByteString for file magic.
magic :: ByteString -> Maybe Tar
module System.Posix.ARX.CLI
-- | Run CLI tool, processing arguments and options.
main :: IO ()
-- | Apply defaulting and overrides appropriate to SHDAT programs.
shdatResolve :: ([Word], [IOStream], [IOStream]) -> (Word, IOStream, [IOStream])
shdatCheckStreams :: [IOStream] -> Maybe ByteString
-- | Apply defaulting and overrides appropriate to TMPX programs.
tmpxResolve :: ([Word], [IOStream], [IOStream], [(Var, Val)], [(Bool, Bool)], [ByteSource]) -> (Word, IOStream, [IOStream], [(Var, Val)], (Bool, Bool), ByteSource)
tmpxCheckStreams :: [IOStream] -> ByteSource -> Maybe ByteString
tmpxOpen :: Word -> [(Var, Val)] -> (Bool, Bool) -> ByteSource -> IO TMPX
openByteSource :: ByteSource -> IO ByteString
inIOStream :: IOStream -> IO ByteString
outIOStream :: IOStream -> ByteString -> IO ()
arIOStream :: IOStream -> IO (Maybe (Tar, ByteString))
-- | By default, we encode binary data to HERE docs 4MiB at a time. (The
-- encoded result may be up to 10% larger, though 1% is more likely.)
defaultBlock :: Word
-- | The default task is a no-op call to /bin/true.
defaultTask :: ByteSource
data ZOM
Zero :: ZOM
One :: !ByteString -> ZOM
Many :: ![ByteString] -> ZOM
streamsMessage :: [ZOM] -> Maybe ByteString
blockMessage :: ByteString -> [ByteString] -> ByteString -> ByteString
err :: ByteString -> IO ()
die :: ByteString -> IO b
instance Monoid ZOM