-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Archive execution tool.
--   
--   The <tt>ARX</tt> 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 <tt>sh</tt> on STDIN. This latter feature is
--   useful when one would like to use <tt>ssh</tt> and <tt>sudo</tt> to
--   set an appropriate executation context, for example running: <tt>ssh
--   user@example.com sudo sh</tt>.
--   
--   The shell tools used are <tt>head</tt>, <tt>sed</tt>, <tt>date</tt>,
--   <tt>tr</tt> and <tt>tar</tt>. The calls to <tt>tar</tt> sometimes use
--   <tt>-j</tt> and <tt>-z</tt>; these calls to <tt>tar</tt> may result in
--   calls to <tt>bzip2</tt> and <tt>gzip</tt>. Scripts have been tested
--   with <tt>dash</tt> and the GNU tools as well as the <tt>sh</tt> and
--   tools that are part of <tt>busybox</tt>.
--   
--   The <tt>arx</tt> command line tool provides the <tt>tmpx</tt>
--   subcommand for preparing jobs to run and the <tt>shdat</tt> subcommand
--   for access to the low-level shell encoder. The
--   <tt>System.Posix.ARX</tt> module provides access to the routines used
--   for constructing commands and environments, describing archives and
--   building Bourne shell scripts.
--   
--   One way I have used <tt>arx</tt> is to test the Cabal source archive
--   for this package:
--   
--   <pre>
--   arx tmpx ./dist/arx-* // 'cd arx-* &amp;&amp; cabal configure &amp;&amp; cabal build' | sh
--   </pre>
--   
--   There are binary <tt>arx</tt> command line tool releases available
--   from:
--   
--   <a>https://github.com/solidsnack/arx/downloads</a>
--   
--   For each supported platform, there is an archive containing
--   <tt>arx</tt> and signature files (SHA 512 and GPG).
@package arx
@version 0.3.2


-- | 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 <a>EnvBinding</a> has the form <tt><a>var
--   name</a>=<a>string</a></tt>. For example, <tt>SENDIN=the_clowns</tt>.
EnvBinding :: Class

-- | A <a>QualifiedPath</a> is a file path starting with <tt>/</tt>,
--   <tt>./</tt>, or <tt>../</tt>.
QualifiedPath :: Class

-- | A <a>DashDash</a> is a string of two dashes, <tt>--</tt>, commonly
--   used to indicate the end of options processing.
DashDash :: Class

-- | A <a>LongOption</a> is a string beginning with two dashes and then at
--   least one non-dash.
LongOption :: Class

-- | A <a>Dash</a> is a single dash, <tt>-</tt>, commonly used to indicate
--   input from <tt>stdin</tt> or output to <tt>stdout</tt>.
Dash :: Class

-- | A <a>ShortOption</a> is a beginning with a dash and then at least one
--   non-dash.
ShortOption :: Class

-- | A <a>URL</a> is a scheme, separated from the resource, represented as
--   an arbitrary string, by <tt>://</tt>. The scheme consists of ASCII,
--   lower-case letters and digits, and may be multi-part, with each part
--   separated by a <tt>+</tt> or <tt>/</tt> (for example,
--   <tt>git+ssh</tt>). An example URL:
--   <tt><a>http://example.com/?q=special</a></tt>.
URL :: Class

-- | A <a>HexNum</a> is a sequence of hexadecimal digits, upper or lower
--   case, beginning with <tt>0x</tt>; for example: <tt>0x01a3</tt>.
HexNum :: Class

-- | A <a>DecimalNum</a> is a string of decimal digits: <tt>123123</tt>.
DecimalNum :: Class

-- | A <a>Size</a> is a decimal number followed by a multiplicative suffix,
--   in the manner of <tt>dd</tt> or <tt>head</tt>. Note that counts in
--   terms of bytes require <tt>B</tt> (unlike <tt>dd</tt> or
--   <tt>head</tt>). For a full list of suffixes, see <a>sizes</a> below.
Size :: Class

-- | Determine if a particular <a>ByteString</a> matches the given
--   <a>Class</a> of token.
match :: Class -> ByteString -> Bool

-- | Determine if a particular <a>ByteString</a> matches any <a>Class</a>
--   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,
--   <a>QualifiedPath</a> -- 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 <tt>dd</tt> or <tt>head</tt> and many others) as well
--   as the standard for binary sizes established by the IEC. <tt> 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 </tt>
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 <a>Bounded</a> type.
sizeBounded :: forall b. (Bounded b, Integral b) => Parser b
instance GHC.Classes.Eq System.Posix.ARX.CLI.CLTokens.Class
instance GHC.Classes.Ord System.Posix.ARX.CLI.CLTokens.Class
instance GHC.Show.Show System.Posix.ARX.CLI.CLTokens.Class


-- | 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 <a>SafeChunk</a>. Those blocks
--   needing byte-translation are stored in an <a>EncodedChunk</a>.
data Chunk
SafeChunk :: !ByteString -> Chunk
EncodedChunk :: !ByteString -> !Int -> !EscapeChar -> !EscapeChar -> Chunk

-- | Converts a <a>ByteString</a> 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 <a>ByteString</a> 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 <tt>tr</tt> and
--   <tt>sed</tt> 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 <tt>!</tt> and the escape byte is <tt>#</tt> then all
--   nulls become <tt>!</tt>, any <tt>!</tt> become <tt>##</tt> and all
--   <tt>#</tt> become <tt>#_</tt>.
--   
--   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, <tt>#</tt> escaped
--   to <tt>##</tt> and <tt>!</tt> to <tt>#_</tt>, then <tt>#_</tt> in the
--   input becomes <tt>##_</tt>. We want to run the subsitution for
--   <tt>#</tt> first, to catch this; it produces <tt>#_</tt>; then Sed
--   feeds the input to the second substitution which unfortunately renders
--   <tt>!</tt>. In the alternate scheme, the input is encoded
--   <tt>#__</tt>, the <tt>!</tt> decoder runs first and ignores it, then
--   the <tt>#</tt> 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 <tt>tr</tt> and <tt>sed</tt> 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 GHC.Show.Show System.Posix.ARX.HEREDat.Chunk
instance GHC.Show.Show System.Posix.ARX.HEREDat.EscapeChar
instance Data.String.IsString System.Posix.ARX.HEREDat.Chunk


-- | 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 GHC.Classes.Eq System.Posix.ARX.Sh.Val
instance GHC.Classes.Ord System.Posix.ARX.Sh.Val
instance GHC.Show.Show System.Posix.ARX.Sh.Val
instance GHC.Classes.Eq System.Posix.ARX.Sh.Var
instance GHC.Classes.Ord System.Posix.ARX.Sh.Var
instance GHC.Show.Show System.Posix.ARX.Sh.Var
instance System.Posix.ARX.Sh.Raw System.Posix.ARX.Sh.Val
instance System.Posix.ARX.Sh.Raw System.Posix.ARX.Sh.Var
instance System.Posix.ARX.Sh.Render System.Posix.ARX.Sh.Val
instance System.Posix.ARX.Sh.Render System.Posix.ARX.Sh.Var
instance System.Posix.ARX.Sh.Render [(System.Posix.ARX.Sh.Var, System.Posix.ARX.Sh.Val)]
instance System.Posix.ARX.Sh.Render [System.Posix.ARX.Sh.Val]

module System.Posix.ARX.CLI.Options
shdat :: ArgsParser ([Word], [IOStream], [IOStream])
tmpx :: ArgsParser ([Word], [IOStream], [IOStream], [(Var, Val)], [ByteString], [(Bool, Bool)], [Bool], [ByteSource])
blockSize :: ArgsParser Word
outputFile :: ArgsParser IOStream
ioStream :: ArgsParser IOStream
qPath :: ArgsParser ByteString
shared :: ArgsParser Bool
tmpdir :: 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
infixl 4 <@>
tokCL :: Class -> ArgsParser ByteString
slashes :: ArgsParser (Maybe ByteString)
instance GHC.Classes.Eq System.Posix.ARX.CLI.Options.IOStream
instance GHC.Classes.Ord System.Posix.ARX.CLI.Options.IOStream
instance GHC.Show.Show System.Posix.ARX.CLI.Options.IOStream
instance GHC.Classes.Eq System.Posix.ARX.CLI.Options.ByteSource
instance GHC.Classes.Ord System.Posix.ARX.CLI.Options.ByteSource
instance GHC.Show.Show System.Posix.ARX.CLI.Options.ByteSource

module System.Posix.ARX.TMPXTools
data Template
Template :: Bool -> Bool -> Bool -> ByteString -> Builder -> Builder -> Builder -> Template

-- | Remove tmp on run success?
[rm0] :: Template -> Bool

-- | Remove tmp on run error?
[rm1] :: Template -> Bool

-- | Share directory across runs?
[shared] :: Template -> Bool

-- | Temp file location.
[tmpdir] :: Template -> ByteString

-- | Stream for env text.
[env] :: Template -> Builder

-- | Stream for run text.
[run] :: Template -> Builder

-- | Data text.
[dat] :: Template -> Builder
render :: Template -> Builder
findChunks :: ByteString -> [ByteString]
coalesce :: [Maybe ByteString] -> [ByteString]
markHoles :: ByteString -> [Maybe ByteString]
isHole :: ByteString -> Bool
instance GHC.Show.Show System.Posix.ARX.TMPXTools.Template

module System.Posix.ARX.Tar

-- | Handled styles of Tar archive.
data Tar
TAR :: Tar
TBZ :: Tar
TGZ :: Tar
TXZ :: Tar

-- | Scan a lazy ByteString for file magic.
magic :: ByteString -> Maybe Tar
bzMagic :: ByteString -> Bool
gzMagic :: ByteString -> Bool
tarMagic :: ByteString -> Bool
xzMagic :: ByteString -> Bool
instance GHC.Classes.Eq System.Posix.ARX.Tar.Tar
instance GHC.Classes.Ord System.Posix.ARX.Tar.Tar
instance GHC.Show.Show System.Posix.ARX.Tar.Tar

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 <a>SHDAT</a> program processes byte streams with the specified
--   chunking to produce a script.
newtype SHDAT
SHDAT :: Word -> SHDAT

-- | A <a>TMPX</a> 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)] -> ByteString -> Bool -> Bool -> Bool -> TMPX
instance System.Posix.ARX.Programs.ARX System.Posix.ARX.Programs.TMPX [(System.Posix.ARX.Tar.Tar, Data.ByteString.Lazy.Internal.ByteString)]
instance System.Posix.ARX.Programs.ARX System.Posix.ARX.Programs.SHDAT Data.ByteString.Lazy.Internal.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 <a>SHDAT</a> program processes byte streams with the specified
--   chunking to produce a script.
newtype SHDAT
SHDAT :: Word -> SHDAT

-- | A <a>TMPX</a> 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)] -> ByteString -> Bool -> 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
TBZ :: Tar
TGZ :: Tar
TXZ :: 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 <a>SHDAT</a> programs.
shdatResolve :: ([Word], [IOStream], [IOStream]) -> (Word, IOStream, [IOStream])
shdatCheckStreams :: [IOStream] -> Maybe ByteString

-- | Apply defaulting and overrides appropriate to <a>TMPX</a> programs.
tmpxResolve :: ([Word], [IOStream], [IOStream], [(Var, Val)], [ByteString], [(Bool, Bool)], [Bool], [ByteSource]) -> (Word, IOStream, [IOStream], [(Var, Val)], ByteString, (Bool, Bool), Bool, ByteSource)
tmpxCheckStreams :: [IOStream] -> ByteSource -> Maybe ByteString
tmpxOpen :: Word -> [(Var, Val)] -> (Bool, Bool, Bool) -> ByteString -> 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 <tt>/bin/true</tt>.
defaultTask :: ByteSource
data ZOM
Zero :: ZOM
One :: !ByteString -> ZOM
Many :: ![ByteString] -> ZOM
streamsMessage :: Foldable t => t ZOM -> Maybe ByteString
blockMessage :: ByteString -> [ByteString] -> ByteString -> ByteString
err :: ByteString -> IO ()
die :: () => ByteString -> IO b
instance GHC.Base.Semigroup System.Posix.ARX.CLI.ZOM
instance GHC.Base.Monoid System.Posix.ARX.CLI.ZOM