-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Shell programming, Haskell-style
--
-- turtle is a reimplementation of the Unix command line
-- environment in Haskell so that you can use Haskell as both a shell and
-- a scripting language.
--
-- Features include:
--
--
-- - Batteries included: Command an extended suite of predefined
-- utilities
-- - Interoperability: You can still run external shell commands
-- - Portability: Works on Windows, OS X, and Linux
-- - Exception safety: Safely acquire and release resources
-- - Streaming: Transform or fold command output in constant space
-- - Patterns: Use typed regular expressions that can parse structured
-- values
-- - Formatting: Type-safe printf-style text formatting
-- - Modern: Supports text and system-filepath
--
--
-- Read Turtle.Tutorial for a detailed tutorial or
-- Turtle.Prelude for a quick-start guide
--
-- turtle is designed to be beginner-friendly, but as a result
-- lacks certain features, like tracing commands. If you feel comfortable
-- using turtle then you should also check out the
-- Shelly library which provides similar functionality.
@package turtle
@version 1.4.1
-- | You can think of Shell as [] + IO +
-- Managed. In fact, you can embed all three of them within a
-- Shell:
--
--
-- select :: [a] -> Shell a
-- liftIO :: IO a -> Shell a
-- using :: Managed a -> Shell a
--
--
-- Those three embeddings obey these laws:
--
--
-- do { x <- select m; select (f x) } = select (do { x <- m; f x })
-- do { x <- liftIO m; liftIO (f x) } = liftIO (do { x <- m; f x })
-- do { x <- with m; using (f x) } = using (do { x <- m; f x })
--
-- select (return x) = return x
-- liftIO (return x) = return x
-- using (return x) = return x
--
--
-- ... and select obeys these additional laws:
--
--
-- select xs <|> select ys = select (xs <|> ys)
-- select empty = empty
--
--
-- You typically won't build Shells using the Shell
-- constructor. Instead, use these functions to generate primitive
-- Shells:
--
--
-- - empty, to create a Shell that outputs nothing
-- - return, to create a Shell that outputs a single
-- value
-- - select, to range over a list of values within a
-- Shell
-- - liftIO, to embed an IO action within a
-- Shell
-- - using, to acquire a Managed resource within a
-- Shell
--
--
-- Then use these classes to combine those primitive Shells into
-- larger Shells:
--
--
--
-- If you still insist on building your own Shell from scratch,
-- then the Shell you build must satisfy this law:
--
--
-- -- For every shell `s`:
-- _foldIO s (FoldM step begin done) = do
-- x <- begin
-- x' <- _foldIO s (FoldM step (return x) return)
-- done x'
--
--
-- ... which is a fancy way of saying that your Shell must call
-- 'begin' exactly once when it begins and call 'done'
-- exactly once when it ends.
module Turtle.Shell
-- | A (Shell a) is a protected stream of a's with side
-- effects
newtype Shell a
Shell :: (forall r. FoldM IO a r -> IO r) -> Shell a
[_foldIO] :: Shell a -> forall r. FoldM IO a r -> IO r
-- | Use a FoldM IO to reduce the stream of
-- a's produced by a Shell
foldIO :: MonadIO io => Shell a -> FoldM IO a r -> io r
-- | Use a Fold to reduce the stream of a's produced by a
-- Shell
fold :: MonadIO io => Shell a -> Fold a b -> io b
-- | Run a Shell to completion, discarding any unused values
sh :: MonadIO io => Shell a -> io ()
-- | Run a Shell to completion, printing any unused values
view :: (MonadIO io, Show a) => Shell a -> io ()
-- | Convert a list to a Shell that emits each element of the list
select :: Foldable f => f a -> Shell a
-- | Lift a computation from the IO monad.
liftIO :: MonadIO m => forall a. IO a -> m a
using :: MonadManaged m => forall a. Managed a -> m a
instance GHC.Base.Functor Turtle.Shell.Shell
instance GHC.Base.Applicative Turtle.Shell.Shell
instance GHC.Base.Monad Turtle.Shell.Shell
instance GHC.Base.Alternative Turtle.Shell.Shell
instance GHC.Base.MonadPlus Turtle.Shell.Shell
instance Control.Monad.IO.Class.MonadIO Turtle.Shell.Shell
instance Control.Monad.Managed.MonadManaged Turtle.Shell.Shell
instance GHC.Base.Monoid a => GHC.Base.Monoid (Turtle.Shell.Shell a)
instance GHC.Base.Monoid a => GHC.Num.Num (Turtle.Shell.Shell a)
instance Data.String.IsString a => Data.String.IsString (Turtle.Shell.Shell a)
-- | Use this module to either:
--
--
-- - match Text with light-weight backtracking patterns,
-- or:
-- - parse structured values from Text.
--
--
-- Example usage:
--
--
-- >>> :set -XOverloadedStrings
--
-- >>> match ("can" <|> "cat") "cat"
-- ["cat"]
--
-- >>> match ("can" <|> "cat") "dog"
-- []
--
-- >>> match (decimal `sepBy` ",") "1,2,3"
-- [[1,2,3]]
--
--
-- This pattern has unlimited backtracking, and will return as many
-- solutions as possible:
--
--
-- >>> match (prefix (star anyChar)) "123"
-- ["123","12","1",""]
--
--
-- Use do notation to structure more complex patterns:
--
--
-- >>> :{
-- let bit = ("0" *> pure False) <|> ("1" *> pure True) :: Pattern Bool;
-- portableBitMap = do
-- { "P1"
-- ; width <- spaces1 *> decimal
-- ; height <- spaces1 *> decimal
-- ; count width (count height (spaces1 *> bit))
-- };
-- in match (prefix portableBitMap) "P1\n2 2\n0 0\n1 0\n"
-- :}
-- [[[False,False],[True,False]]]
--
module Turtle.Pattern
-- | A fully backtracking pattern that parses an 'a' from some
-- Text
data Pattern a
-- | Match a Pattern against a Text input, returning all
-- possible solutions
--
-- The Pattern must match the entire Text
match :: Pattern a -> Text -> [a]
-- | Match any character
--
--
-- >>> match anyChar "1"
-- "1"
--
-- >>> match anyChar ""
-- ""
--
anyChar :: Pattern Char
-- | Matches the end of input
--
--
-- >>> match eof "1"
-- []
--
-- >>> match eof ""
-- [()]
--
eof :: Pattern ()
-- | Synonym for anyChar
dot :: Pattern Char
-- | Match any character that satisfies the given predicate
--
--
-- >>> match (satisfy (== '1')) "1"
-- "1"
--
-- >>> match (satisfy (== '2')) "1"
-- ""
--
satisfy :: (Char -> Bool) -> Pattern Char
-- | Match a specific character
--
--
-- >>> match (char '1') "1"
-- "1"
--
-- >>> match (char '2') "1"
-- ""
--
char :: Char -> Pattern Char
-- | Match any character except the given one
--
--
-- >>> match (notChar '2') "1"
-- "1"
--
-- >>> match (notChar '1') "1"
-- ""
--
notChar :: Char -> Pattern Char
-- | Match a specific string
--
--
-- >>> match (text "123") "123"
-- ["123"]
--
--
-- You can also omit the text function if you enable the
-- OverloadedStrings extension:
--
--
-- >>> match "123" "123"
-- ["123"]
--
text :: Text -> Pattern Text
-- | Match a specific string in a case-insensitive way
--
-- This only handles ASCII strings
--
--
-- >>> match (asciiCI "abc") "ABC"
-- ["ABC"]
--
asciiCI :: Text -> Pattern Text
-- | Match any one of the given characters
--
--
-- >>> match (oneOf "1a") "1"
-- "1"
--
-- >>> match (oneOf "2a") "1"
-- ""
--
oneOf :: [Char] -> Pattern Char
-- | Match anything other than the given characters
--
--
-- >>> match (noneOf "2a") "1"
-- "1"
--
-- >>> match (noneOf "1a") "1"
-- ""
--
noneOf :: [Char] -> Pattern Char
-- | Match a whitespace character
--
--
-- >>> match space " "
-- " "
--
-- >>> match space "1"
-- ""
--
space :: Pattern Char
-- | Match zero or more whitespace characters
--
--
-- >>> match spaces " "
-- [" "]
--
-- >>> match spaces ""
-- [""]
--
spaces :: Pattern Text
-- | Match one or more whitespace characters
--
--
-- >>> match spaces1 " "
-- [" "]
--
-- >>> match spaces1 ""
-- []
--
spaces1 :: Pattern Text
-- | Match the tab character ('t')
--
--
-- >>> match tab "\t"
-- "\t"
--
-- >>> match tab " "
-- ""
--
tab :: Pattern Char
-- | Match the newline character ('n')
--
--
-- >>> match newline "\n"
-- "\n"
--
-- >>> match newline " "
-- ""
--
newline :: Pattern Char
-- | Matches a carriage return ('r') followed by a newline
-- ('n')
--
--
-- >>> match crlf "\r\n"
-- ["\r\n"]
--
-- >>> match crlf "\n\r"
-- []
--
crlf :: Pattern Text
-- | Match an uppercase letter
--
--
-- >>> match upper "A"
-- "A"
--
-- >>> match upper "a"
-- ""
--
upper :: Pattern Char
-- | Match a lowercase letter
--
--
-- >>> match lower "a"
-- "a"
--
-- >>> match lower "A"
-- ""
--
lower :: Pattern Char
-- | Match a letter or digit
--
--
-- >>> match alphaNum "1"
-- "1"
--
-- >>> match alphaNum "a"
-- "a"
--
-- >>> match alphaNum "A"
-- "A"
--
-- >>> match alphaNum "."
-- ""
--
alphaNum :: Pattern Char
-- | Match a letter
--
--
-- >>> match letter "A"
-- "A"
--
-- >>> match letter "a"
-- "a"
--
-- >>> match letter "1"
-- ""
--
letter :: Pattern Char
-- | Match a digit
--
--
-- >>> match digit "1"
-- "1"
--
-- >>> match digit "a"
-- ""
--
digit :: Pattern Char
-- | Match a hexadecimal digit
--
--
-- >>> match hexDigit "1"
-- "1"
--
-- >>> match hexDigit "A"
-- "A"
--
-- >>> match hexDigit "a"
-- "a"
--
-- >>> match hexDigit "g"
-- ""
--
hexDigit :: Pattern Char
-- | Match an octal digit
--
--
-- >>> match octDigit "1"
-- "1"
--
-- >>> match octDigit "9"
-- ""
--
octDigit :: Pattern Char
-- | Match an unsigned decimal number
--
--
-- >>> match decimal "123"
-- [123]
--
-- >>> match decimal "-123"
-- []
--
decimal :: Num n => Pattern n
-- | Transform a numeric parser to accept an optional leading '+'
-- or '-' sign
--
--
-- >>> match (signed decimal) "+123"
-- [123]
--
-- >>> match (signed decimal) "-123"
-- [-123]
--
-- >>> match (signed decimal) "123"
-- [123]
--
signed :: Num a => Pattern a -> Pattern a
-- | Use this to match the prefix of a string
--
--
-- >>> match "A" "ABC"
-- []
--
-- >>> match (prefix "A") "ABC"
-- ["A"]
--
prefix :: Pattern a -> Pattern a
-- | Use this to match the suffix of a string
--
--
-- >>> match "C" "ABC"
-- []
--
-- >>> match (suffix "C") "ABC"
-- ["C"]
--
suffix :: Pattern a -> Pattern a
-- | Use this to match the interior of a string
--
--
-- >>> match "B" "ABC"
-- []
--
-- >>> match (has "B") "ABC"
-- ["B"]
--
has :: Pattern a -> Pattern a
-- | Match the entire string if it begins with the given pattern
--
-- This returns the entire string, not just the matched prefix
--
--
-- >>> match (begins "A" ) "ABC"
-- ["ABC"]
--
-- >>> match (begins ("A" *> pure "1")) "ABC"
-- ["1BC"]
--
begins :: Pattern Text -> Pattern Text
-- | Match the entire string if it ends with the given pattern
--
-- This returns the entire string, not just the matched prefix
--
--
-- >>> match (ends "C" ) "ABC"
-- ["ABC"]
--
-- >>> match (ends ("C" *> pure "1")) "ABC"
-- ["AB1"]
--
ends :: Pattern Text -> Pattern Text
-- | Match the entire string if it contains the given pattern
--
-- This returns the entire string, not just the interior pattern
--
--
-- >>> match (contains "B" ) "ABC"
-- ["ABC"]
--
-- >>> match (contains ("B" *> pure "1")) "ABC"
-- ["A1C"]
--
contains :: Pattern Text -> Pattern Text
-- | (invert p) succeeds if p fails and fails if
-- p succeeds
--
--
-- >>> match (invert "A") "A"
-- []
--
-- >>> match (invert "A") "B"
-- [()]
--
invert :: Pattern a -> Pattern ()
-- | Match a Char, but return Text
--
--
-- >>> match (once (char '1')) "1"
-- ["1"]
--
-- >>> match (once (char '1')) ""
-- []
--
once :: Pattern Char -> Pattern Text
-- | Parse 0 or more occurrences of the given character
--
--
-- >>> match (star anyChar) "123"
-- ["123"]
--
-- >>> match (star anyChar) ""
-- [""]
--
--
-- See also: chars
star :: Pattern Char -> Pattern Text
-- | Parse 1 or more occurrences of the given character
--
--
-- >>> match (plus digit) "123"
-- ["123"]
--
-- >>> match (plus digit) ""
-- []
--
--
-- See also: chars1
plus :: Pattern Char -> Pattern Text
-- | Patterns that match multiple times are greedy by default, meaning that
-- they try to match as many times as possible. The selfless
-- combinator makes a pattern match as few times as possible
--
-- This only changes the order in which solutions are returned, by
-- prioritizing less greedy solutions
--
--
-- >>> match (prefix (selfless (some anyChar))) "123"
-- ["1","12","123"]
--
-- >>> match (prefix (some anyChar) ) "123"
-- ["123","12","1"]
--
selfless :: Pattern a -> Pattern a
-- | Apply the patterns in the list in order, until one of them succeeds
--
--
-- >>> match (choice ["cat", "dog", "egg"]) "egg"
-- ["egg"]
--
-- >>> match (choice ["cat", "dog", "egg"]) "cat"
-- ["cat"]
--
-- >>> match (choice ["cat", "dog", "egg"]) "fan"
-- []
--
choice :: [Pattern a] -> Pattern a
-- | Apply the given pattern a fixed number of times, collecting the
-- results
--
--
-- >>> match (count 3 anyChar) "123"
-- ["123"]
--
-- >>> match (count 4 anyChar) "123"
-- []
--
count :: Int -> Pattern a -> Pattern [a]
-- | Apply the given pattern at least the given number of times, collecting
-- the results
--
--
-- >>> match (lowerBounded 5 dot) "123"
-- []
--
-- >>> match (lowerBounded 2 dot) "123"
-- ["123"]
--
lowerBounded :: Int -> Pattern a -> Pattern [a]
-- | Apply the given pattern 0 or more times, up to a given bound,
-- collecting the results
--
--
-- >>> match (upperBounded 5 dot) "123"
-- ["123"]
--
-- >>> match (upperBounded 2 dot) "123"
-- []
--
-- >>> match ((,) <$> upperBounded 2 dot <*> chars) "123"
-- [("12","3"),("1","23")]
--
upperBounded :: Int -> Pattern a -> Pattern [a]
-- | Apply the given pattern a number of times restricted by given lower
-- and upper bounds, collecting the results
--
--
-- >>> match (bounded 2 5 "cat") "catcatcat"
-- [["cat","cat","cat"]]
--
-- >>> match (bounded 2 5 "cat") "cat"
-- []
--
-- >>> match (bounded 2 5 "cat") "catcatcatcatcatcat"
-- []
--
--
-- bounded could be implemented naively as follows:
--
--
-- bounded m n p = do
-- x <- choice (map pure [m..n])
-- count x p
--
bounded :: Int -> Int -> Pattern a -> Pattern [a]
-- | Transform a parser to a succeed with an empty value instead of failing
--
-- See also: optional
--
--
-- >>> match (option "1" <> "2") "12"
-- ["12"]
--
-- >>> match (option "1" <> "2") "2"
-- ["2"]
--
option :: Monoid a => Pattern a -> Pattern a
-- | (between open close p) matches 'p' in between
-- 'open' and 'close'
--
--
-- >>> match (between (char '(') (char ')') (star anyChar)) "(123)"
-- ["123"]
--
-- >>> match (between (char '(') (char ')') (star anyChar)) "(123"
-- []
--
between :: Pattern a -> Pattern b -> Pattern c -> Pattern c
-- | Discard the pattern's result
--
--
-- >>> match (skip anyChar) "1"
-- [()]
--
-- >>> match (skip anyChar) ""
-- []
--
skip :: Pattern a -> Pattern ()
-- | Restrict the pattern to consume no more than the given number of
-- characters
--
--
-- >>> match (within 2 decimal) "12"
-- [12]
--
-- >>> match (within 2 decimal) "1"
-- [1]
--
-- >>> match (within 2 decimal) "123"
-- []
--
within :: Int -> Pattern a -> Pattern a
-- | Require the pattern to consume exactly the given number of characters
--
--
-- >>> match (fixed 2 decimal) "12"
-- [12]
--
-- >>> match (fixed 2 decimal) "1"
-- []
--
fixed :: Int -> Pattern a -> Pattern a
-- | p sepBy sep matches zero or more occurrences of
-- p separated by sep
--
--
-- >>> match (decimal `sepBy` char ',') "1,2,3"
-- [[1,2,3]]
--
-- >>> match (decimal `sepBy` char ',') ""
-- [[]]
--
sepBy :: Pattern a -> Pattern b -> Pattern [a]
-- | p sepBy1 sep matches one or more occurrences of
-- p separated by sep
--
--
-- >>> match (decimal `sepBy1` ",") "1,2,3"
-- [[1,2,3]]
--
-- >>> match (decimal `sepBy1` ",") ""
-- []
--
sepBy1 :: Pattern a -> Pattern b -> Pattern [a]
-- | Like star dot or star anyChar, except more efficient
chars :: Pattern Text
-- | Like plus dot or plus anyChar, except more efficient
chars1 :: Pattern Text
instance GHC.Base.MonadPlus Turtle.Pattern.Pattern
instance GHC.Base.Alternative Turtle.Pattern.Pattern
instance GHC.Base.Monad Turtle.Pattern.Pattern
instance GHC.Base.Applicative Turtle.Pattern.Pattern
instance GHC.Base.Functor Turtle.Pattern.Pattern
instance GHC.Base.Monoid a => GHC.Base.Monoid (Turtle.Pattern.Pattern a)
instance GHC.Base.Monoid a => GHC.Num.Num (Turtle.Pattern.Pattern a)
instance a ~ Data.Text.Internal.Text => Data.String.IsString (Turtle.Pattern.Pattern a)
module Turtle.Line
-- | A line of text (does not contain newlines).
data Line
-- | Convert a line to a text value.
lineToText :: Line -> Text
-- | Split text into lines. The inverse of linesToText.
textToLines :: Text -> NonEmpty Line
-- | Merge lines into a single text value.
linesToText :: [Line] -> Text
-- | Try to convert a text value into a line. Precondition (checked): the
-- argument does not contain newlines.
textToLine :: Text -> Maybe Line
-- | Convert a text value into a line. Precondition (unchecked): the
-- argument does not contain newlines.
unsafeTextToLine :: Text -> Line
-- | The NewlineForbidden exception is thrown when you construct a
-- Line using an overloaded string literal or by calling
-- fromString explicitly and the supplied string contains
-- newlines. This is a programming error to do so: if you aren't sure
-- that the input string is newline-free, do not rely on the
-- IsString Line instance.
--
-- When debugging, it might be useful to look for implicit invocations of
-- fromString for Line:
--
--
-- >>> sh (do { line <- "Hello\nWorld"; echo line })
-- *** Exception: NewlineForbidden
--
--
-- In the above example, echo expects its argument to be a
-- Line, thus line :: Line. Since we bind
-- line in Shell, the string literal
-- "Hello\nWorld" has type Shell Line.
-- The IsString (Shell Line) instance
-- delegates the construction of a Line to the IsString
-- Line instance, where the exception is thrown.
--
-- To fix the problem, use textToLines:
--
--
-- >>> sh (do { line <- select (textToLines "Hello\nWorld"); echo line })
-- Hello
-- World
--
data NewlineForbidden
NewlineForbidden :: NewlineForbidden
instance GHC.Base.Monoid Turtle.Line.Line
instance GHC.Show.Show Turtle.Line.Line
instance GHC.Classes.Ord Turtle.Line.Line
instance GHC.Classes.Eq Turtle.Line.Line
instance GHC.Show.Show Turtle.Line.NewlineForbidden
instance GHC.Exception.Exception Turtle.Line.NewlineForbidden
instance Data.String.IsString Turtle.Line.Line
-- | Example usage of this module:
--
--
-- -- options.hs
--
-- {-# LANGUAGE OverloadedStrings #-}
--
-- import Turtle
--
-- parser :: Parser (Text, Int)
-- parser = (,) <$> optText "name" 'n' "Your first name"
-- <*> optInt "age" 'a' "Your current age"
--
-- main = do
-- (name, age) <- options "Greeting script" parser
-- echo (format ("Hello there, "%s) name)
-- echo (format ("You are "%d%" years old") age)
--
--
--
-- $ ./options --name John --age 42
-- Hello there, John
-- You are 42 years old
--
--
--
-- $ ./options --help
-- Greeting script
--
-- Usage: options (-n|--name NAME) (-a|--age AGE)
--
-- Available options:
-- -h,--help Show this help text
-- --name NAME Your first name
-- --age AGE Your current age
--
--
-- See the Turtle.Tutorial module which contains more examples on
-- how to use command-line parsing.
module Turtle.Options
-- | A Parser a is an option parser returning a value of type
-- a.
data Parser a :: * -> *
-- | The name of a command-line argument
--
-- This is used to infer the long name and metavariable for the command
-- line flag. For example, an ArgName of "name" will
-- create a --name flag with a NAME metavariable
newtype ArgName
ArgName :: Text -> ArgName
[getArgName] :: ArgName -> Text
-- | The name of a sub-command
--
-- This is lower-cased to create a sub-command. For example, a
-- CommandName of "Name" will parse name on the
-- command line before parsing the remaining arguments using the
-- command's subparser.
newtype CommandName
CommandName :: Text -> CommandName
[getCommandName] :: CommandName -> Text
-- | The short one-character abbreviation for a flag (i.e. -n)
type ShortName = Char
-- | A brief description of what your program does
--
-- This description will appear in the header of the --help
-- output
newtype Description
Description :: Doc -> Description
[getDescription] :: Description -> Doc
-- | A helpful message explaining what a flag does
--
-- This will appear in the --help output
newtype HelpMessage
HelpMessage :: Text -> HelpMessage
[getHelpMessage] :: HelpMessage -> Text
-- | This parser returns True if the given flag is set and
-- False if the flag is absent
switch :: ArgName -> ShortName -> Optional HelpMessage -> Parser Bool
-- | Parse a Text value as a flag-based option
optText :: ArgName -> ShortName -> Optional HelpMessage -> Parser Text
-- | Parse a Line value as a flag-based option
optLine :: ArgName -> ShortName -> Optional HelpMessage -> Parser Line
-- | Parse an Int as a flag-based option
optInt :: ArgName -> ShortName -> Optional HelpMessage -> Parser Int
-- | Parse an Integer as a flag-based option
optInteger :: ArgName -> ShortName -> Optional HelpMessage -> Parser Integer
-- | Parse a Double as a flag-based option
optDouble :: ArgName -> ShortName -> Optional HelpMessage -> Parser Double
-- | Parse a FilePath value as a flag-based option
optPath :: ArgName -> ShortName -> Optional HelpMessage -> Parser FilePath
-- | Parse any type that implements Read
optRead :: Read a => ArgName -> ShortName -> Optional HelpMessage -> Parser a
-- | Build a flag-based option parser for any type by providing a
-- Text-parsing function
opt :: (Text -> Maybe a) -> ArgName -> ShortName -> Optional HelpMessage -> Parser a
-- | Parse a Text as a positional argument
argText :: ArgName -> Optional HelpMessage -> Parser Text
-- | Parse a Line as a positional argument
argLine :: ArgName -> Optional HelpMessage -> Parser Line
-- | Parse an Int as a positional argument
argInt :: ArgName -> Optional HelpMessage -> Parser Int
-- | Parse an Integer as a positional argument
argInteger :: ArgName -> Optional HelpMessage -> Parser Integer
-- | Parse a Double as a positional argument
argDouble :: ArgName -> Optional HelpMessage -> Parser Double
-- | Parse a FilePath as a positional argument
argPath :: ArgName -> Optional HelpMessage -> Parser FilePath
-- | Parse any type that implements Read as a positional argument
argRead :: Read a => ArgName -> Optional HelpMessage -> Parser a
-- | Build a positional argument parser for any type by providing a
-- Text-parsing function
arg :: (Text -> Maybe a) -> ArgName -> Optional HelpMessage -> Parser a
-- | Create a sub-command that parses CommandName and then parses
-- the rest of the command-line arguments
--
-- The sub-command will have its own Description and help text
subcommand :: CommandName -> Description -> Parser a -> Parser a
-- | Create a named group of sub-commands
subcommandGroup :: forall a. Description -> [(CommandName, Description, Parser a)] -> Parser a
-- | Parse the given options from the command line
options :: MonadIO io => Description -> Parser a -> io a
instance Data.String.IsString Turtle.Options.HelpMessage
instance Data.String.IsString Turtle.Options.Description
instance Data.String.IsString Turtle.Options.CommandName
instance Data.String.IsString Turtle.Options.ArgName
-- | Minimalist implementation of type-safe formatted strings, borrowing
-- heavily from the implementation of the formatting package.
--
-- Example use of this module:
--
--
-- >>> :set -XOverloadedStrings
--
-- >>> import Turtle.Format
--
-- >>> format ("This is a "%s%" string that takes "%d%" arguments") "format" 2
-- "This is a format string that takes 2 arguments"
--
--
-- A Format string that takes no arguments has this type:
--
--
-- "I take 0 arguments" :: Format r r
--
-- format "I take 0 arguments" :: Text
--
--
--
-- >>> format "I take 0 arguments"
-- "I take 0 arguments"
--
--
-- A Format string that takes one argument has this type:
--
--
-- "I take "%d%" arguments" :: Format r (Int -> r)
--
-- format ("I take "%d%" argument") :: Int -> Text
--
--
--
-- >>> format ("I take "%d%" argument") 1
-- "I take 1 argument"
--
--
-- A Format string that takes two arguments has this type:
--
--
-- "I "%s%" "%d%" arguments" :: Format r (Text -> Int -> r)
--
-- format ("I "%s%" "%d%" arguments") :: Text -> Int -> Text
--
--
--
-- >>> format ("I "%s%" "%d%" arguments") "take" 2
-- "I take 2 arguments"
--
module Turtle.Format
-- | A Format string
data Format a b
-- | Concatenate two Format strings
(%) :: Format b c -> Format a b -> Format a c
-- | Convert a Format string to a print function that takes zero or
-- more typed arguments and returns a Text string
format :: Format Text r -> r
-- | Print a Format string to standard output (without a trailing
-- newline)
--
--
-- >>> printf ("Hello, "%s%"!\n") "world"
-- Hello, world!
--
printf :: MonadIO io => Format (io ()) r -> r
-- | Create your own format specifier
makeFormat :: (a -> Text) -> Format r (a -> r)
-- | Format any Showable value
--
--
-- >>> format w True
-- "True"
--
w :: Show a => Format r (a -> r)
-- | Format an Integral value as a signed decimal
--
--
-- >>> format d 25
-- "25"
--
-- >>> format d (-25)
-- "-25"
--
d :: Integral n => Format r (n -> r)
-- | Format a Word value as an unsigned decimal
--
--
-- >>> format u 25
-- "25"
--
u :: Format r (Word -> r)
-- | Format a Word value as an unsigned octal number
--
--
-- >>> format o 25
-- "31"
--
o :: Format r (Word -> r)
-- | Format a Word value as an unsigned hexadecimal number
-- (without a leading "0x")
--
--
-- >>> format x 25
-- "19"
--
x :: Format r (Word -> r)
-- | Format a Double using decimal notation with 6 digits of
-- precision
--
--
-- >>> format f 25.1
-- "25.100000"
--
f :: Format r (Double -> r)
-- | Format a Double using scientific notation with 6 digits
-- of precision
--
--
-- >>> format e 25.1
-- "2.510000e1"
--
e :: Format r (Double -> r)
-- | Format a Double using decimal notation for small
-- exponents and scientific notation for large exponents
--
--
-- >>> format g 25.1
-- "25.100000"
--
-- >>> format g 123456789
-- "1.234568e8"
--
-- >>> format g 0.00000000001
-- "1.000000e-11"
--
g :: Format r (Double -> r)
-- | Format that inserts Text
--
--
-- >>> format s "ABC"
-- "ABC"
--
s :: Format r (Text -> r)
-- | Format that inserts a Line
--
--
-- >>> format l "ABC"
-- "ABC"
--
l :: Format r (Line -> r)
-- | Format a FilePath into Text
fp :: Format r (FilePath -> r)
-- | Format a UTCTime into Text
utc :: Format r (UTCTime -> r)
-- | Convert a Showable value to any type that implements
-- IsString (such as Text)
--
--
-- >>> repr (1,2)
-- "(1,2)"
--
repr :: (Show a, IsString text) => a -> text
instance Control.Category.Category Turtle.Format.Format
instance a ~ b => Data.String.IsString (Turtle.Format.Format a b)
-- | This module provides a large suite of utilities that resemble Unix
-- utilities.
--
-- Many of these commands are just existing Haskell commands renamed to
-- match their Unix counterparts:
--
--
-- >>> :set -XOverloadedStrings
--
-- >>> cd "/tmp"
--
-- >>> pwd
-- FilePath "/tmp"
--
--
-- Some commands are Shells that emit streams of values.
-- view prints all values in a Shell stream:
--
--
-- >>> view (ls "/usr")
-- FilePath "/usr/lib"
-- FilePath "/usr/src"
-- FilePath "/usr/sbin"
-- FilePath "/usr/include"
-- FilePath "/usr/share"
-- FilePath "/usr/games"
-- FilePath "/usr/local"
-- FilePath "/usr/bin"
--
-- >>> view (find (suffix "Browser.py") "/usr/lib")
-- FilePath "/usr/lib/python3.4/idlelib/ClassBrowser.py"
-- FilePath "/usr/lib/python3.4/idlelib/RemoteObjectBrowser.py"
-- FilePath "/usr/lib/python3.4/idlelib/PathBrowser.py"
-- FilePath "/usr/lib/python3.4/idlelib/ObjectBrowser.py"
--
--
-- Use fold to reduce the output of a Shell stream:
--
--
-- >>> import qualified Control.Foldl as Fold
--
-- >>> fold (ls "/usr") Fold.length
-- 8
--
-- >>> fold (find (suffix "Browser.py") "/usr/lib") Fold.head
-- Just (FilePath "/usr/lib/python3.4/idlelib/ClassBrowser.py")
--
--
-- Create files using output:
--
--
-- >>> output "foo.txt" ("123" <|> "456" <|> "ABC")
--
-- >>> realpath "foo.txt"
-- FilePath "/tmp/foo.txt"
--
--
-- Read in files using input:
--
--
-- >>> stdout (input "foo.txt")
-- 123
-- 456
-- ABC
--
--
-- Format strings in a type safe way using format:
--
--
-- >>> dir <- pwd
--
-- >>> format ("I am in the "%fp%" directory") dir
-- "I am in the /tmp directory"
--
--
-- Commands like grep, sed and find accept arbitrary
-- Patterns
--
--
-- >>> stdout (grep ("123" <|> "ABC") (input "foo.txt"))
-- 123
-- ABC
--
-- >>> let exclaim = fmap (<> "!") (plus digit)
--
-- >>> stdout (sed exclaim (input "foo.txt"))
-- 123!
-- 456!
-- ABC
--
--
-- Note that grep and find differ from their Unix
-- counterparts by requiring that the Pattern matches the entire
-- line or file name by default. However, you can optionally match the
-- prefix, suffix, or interior of a line:
--
--
-- >>> stdout (grep (has "2") (input "foo.txt"))
-- 123
--
-- >>> stdout (grep (prefix "1") (input "foo.txt"))
-- 123
--
-- >>> stdout (grep (suffix "3") (input "foo.txt"))
-- 123
--
--
-- You can also build up more sophisticated Shell programs using
-- sh in conjunction with do notation:
--
--
-- {-# LANGUAGE OverloadedStrings #-}
--
-- import Turtle
--
-- main = sh example
--
-- example = do
-- -- Read in file names from "files1.txt" and "files2.txt"
-- file <- fmap fromText (input "files1.txt" <|> input "files2.txt")
--
-- -- Stream each file to standard output only if the file exists
-- True <- liftIO (testfile file)
-- line <- input file
-- liftIO (echo line)
--
--
-- See Turtle.Tutorial for an extended tutorial explaining how to
-- use this library in greater detail.
module Turtle.Prelude
-- | Print exactly one line to stdout
--
-- To print more than one line see printf, which also supports
-- formatted output
echo :: MonadIO io => Line -> io ()
-- | Print exactly one line to stderr
err :: MonadIO io => Line -> io ()
-- | Read in a line from stdin
--
-- Returns Nothing if at end of input
readline :: MonadIO io => io (Maybe Line)
-- | Read in the entire content of a text file.
--
-- This computation throws IOError on failure. See “Classifying
-- I/O errors” in the System.IO.Error documentation for
-- information on why the failure occured.
readTextFile :: FilePath -> IO Text
-- | Replace the entire content of a text file with the provided
-- Text.
--
-- This computation throws IOError on failure. See “Classifying
-- I/O errors” in the System.IO.Error documentation for
-- information on why the failure occured.
writeTextFile :: FilePath -> Text -> IO ()
-- | Get command line arguments in a list
arguments :: MonadIO io => io [Text]
-- | Set or modify an environment variable
export :: MonadIO io => Text -> Text -> io ()
-- | Delete an environment variable
unset :: MonadIO io => Text -> io ()
-- | Look up an environment variable
need :: MonadIO io => Text -> io (Maybe Text)
-- | Retrieve all environment variables
env :: MonadIO io => io [(Text, Text)]
-- | Change the current directory
cd :: MonadIO io => FilePath -> io ()
-- | Get the current directory
pwd :: MonadIO io => io FilePath
-- | Get the home directory
home :: MonadIO io => io FilePath
-- | Canonicalize a path
realpath :: MonadIO io => FilePath -> io FilePath
-- | Move a file or directory
--
-- Works if the two paths are on the same filesystem. If not, mv
-- will still work when dealing with a regular file, but the operation
-- will not be atomic
mv :: MonadIO io => FilePath -> FilePath -> io ()
-- | Create a directory
--
-- Fails if the directory is present
mkdir :: MonadIO io => FilePath -> io ()
-- | Create a directory tree (equivalent to mkdir -p)
--
-- Does not fail if the directory is present
mktree :: MonadIO io => FilePath -> io ()
-- | Copy a file
cp :: MonadIO io => FilePath -> FilePath -> io ()
-- | Copy a directory tree
cptree :: MonadIO io => FilePath -> FilePath -> io ()
-- | Remove a file
rm :: MonadIO io => FilePath -> io ()
-- | Remove a directory
rmdir :: MonadIO io => FilePath -> io ()
-- | Remove a directory tree (equivalent to rm -r)
--
-- Use at your own risk
rmtree :: MonadIO io => FilePath -> io ()
-- | Check if a file exists
testfile :: MonadIO io => FilePath -> io Bool
-- | Check if a directory exists
testdir :: MonadIO io => FilePath -> io Bool
-- | Check if a path exists
testpath :: MonadIO io => FilePath -> io Bool
-- | Get the current time
date :: MonadIO io => io UTCTime
-- | Get the time a file was last modified
datefile :: MonadIO io => FilePath -> io UTCTime
-- | Touch a file, updating the access and modification times to the
-- current time
--
-- Creates an empty file if it does not exist
touch :: MonadIO io => FilePath -> io ()
-- | Time how long a command takes in monotonic wall clock time
--
-- Returns the duration alongside the return value
time :: MonadIO io => io a -> io (a, NominalDiffTime)
-- | Get the system's host name
hostname :: MonadIO io => io Text
-- | Show the full path of an executable file
which :: MonadIO io => FilePath -> io (Maybe FilePath)
-- | Show all matching executables in PATH, not just the first
whichAll :: FilePath -> Shell FilePath
-- | Sleep for the given duration
--
-- A numeric literal argument is interpreted as seconds. In other words,
-- (sleep 2.0) will sleep for two seconds.
sleep :: MonadIO io => NominalDiffTime -> io ()
-- | Exit with the given exit code
--
-- An exit code of 0 indicates success
exit :: MonadIO io => ExitCode -> io a
-- | Throw an exception using the provided Text message
die :: MonadIO io => Text -> io a
-- | Analogous to && in Bash
--
-- Runs the second command only if the first one returns
-- ExitSuccess
(.&&.) :: Monad m => m ExitCode -> m ExitCode -> m ExitCode
infixr 3 .&&.
-- | Analogous to || in Bash
--
-- Run the second command only if the first one returns
-- ExitFailure
(.||.) :: Monad m => m ExitCode -> m ExitCode -> m ExitCode
infixr 2 .||.
-- | Acquire a Managed read-only Handle from a
-- FilePath
readonly :: MonadManaged managed => FilePath -> managed Handle
-- | Acquire a Managed write-only Handle from a
-- FilePath
writeonly :: MonadManaged managed => FilePath -> managed Handle
-- | Acquire a Managed append-only Handle from a
-- FilePath
appendonly :: MonadManaged managed => FilePath -> managed Handle
-- | Create a temporary file underneath the given directory
--
-- Deletes the temporary file when done
--
-- Note that this provides the Handle of the file in order to
-- avoid a potential race condition from the file being moved or deleted
-- before you have a chance to open the file. The mktempfile
-- function provides a simpler API if you don't need to worry about that
-- possibility.
mktemp :: MonadManaged managed => FilePath -> Text -> managed (FilePath, Handle)
-- | Create a temporary file underneath the given directory
--
-- Deletes the temporary file when done
mktempfile :: MonadManaged managed => FilePath -> Text -> managed FilePath
-- | Create a temporary directory underneath the given directory
--
-- Deletes the temporary directory when done
mktempdir :: MonadManaged managed => FilePath -> Text -> managed FilePath
-- | Fork a thread, acquiring an Async value
fork :: MonadManaged managed => IO a -> managed (Async a)
-- | Wait for an Async action to complete
wait :: MonadIO io => Async a -> io a
-- | Change the current directory. Once the current Shell is done,
-- it returns back to the original directory.
--
--
-- >>> :set -XOverloadedStrings
--
-- >>> cd "/"
--
-- >>> view (pushd "/tmp" >> pwd)
-- FilePath "/tmp"
--
-- >>> pwd
-- FilePath "/"
--
pushd :: MonadManaged managed => FilePath -> managed ()
-- | Read lines of Text from standard input
stdin :: Shell Line
-- | Read lines of Text from a file
input :: FilePath -> Shell Line
-- | Read lines of Text from a Handle
inhandle :: Handle -> Shell Line
-- | Stream lines of Text to standard output
stdout :: MonadIO io => Shell Line -> io ()
-- | Stream lines of Text to a file
output :: MonadIO io => FilePath -> Shell Line -> io ()
-- | Stream lines of Text to a Handle
outhandle :: MonadIO io => Handle -> Shell Line -> io ()
-- | Stream lines of Text to append to a file
append :: MonadIO io => FilePath -> Shell Line -> io ()
-- | Stream lines of Text to standard error
stderr :: MonadIO io => Shell Line -> io ()
-- | Read in a stream's contents strictly
strict :: MonadIO io => Shell Line -> io Text
-- | Stream all immediate children of the given directory, excluding
-- "." and ".."
ls :: FilePath -> Shell FilePath
-- | Stream all recursive descendents of the given directory
--
-- This skips any directories that fail the supplied predicate
--
--
-- lstree = lsif (\_ -> return True)
--
lsif :: (FilePath -> IO Bool) -> FilePath -> Shell FilePath
-- | Stream all recursive descendents of the given directory
lstree :: FilePath -> Shell FilePath
-- | Combine the output of multiple Shells, in order
cat :: [Shell a] -> Shell a
-- | Keep all lines that match the given Pattern
grep :: Pattern a -> Shell Line -> Shell Line
-- | Replace all occurrences of a Pattern with its Text
-- result
--
-- sed performs substitution on a line-by-line basis, meaning that
-- substitutions may not span multiple lines. Additionally, substitutions
-- may occur multiple times within the same line, like the behavior of
-- s/.../.../g.
--
-- Warning: Do not use a Pattern that matches the empty string,
-- since it will match an infinite number of times. sed tries to
-- detect such Patterns and die with an error message if
-- they occur, but this detection is necessarily incomplete.
sed :: Pattern Text -> Shell Line -> Shell Line
-- | Make a `Shell Text -> Shell Text` function work on FilePaths
-- instead. | Ignores any paths which cannot be decoded as valid
-- Text.
onFiles :: (Shell Text -> Shell Text) -> Shell FilePath -> Shell FilePath
-- | Like sed, but operates in place on a FilePath (analogous
-- to sed -i)
inplace :: MonadIO io => Pattern Text -> FilePath -> io ()
-- | Search a directory recursively for all files matching the given
-- Pattern
find :: Pattern a -> FilePath -> Shell FilePath
-- | A Stream of "y"s
yes :: Shell Line
-- | Number each element of a Shell (starting at 0)
nl :: Num n => Shell a -> Shell (n, a)
-- | Merge two Shells together, element-wise
--
-- If one Shell is longer than the other, the excess elements are
-- truncated
paste :: Shell a -> Shell b -> Shell (a, b)
-- | A Shell that endlessly emits ()
endless :: Shell ()
-- | Limit a Shell to a fixed number of values
limit :: Int -> Shell a -> Shell a
-- | Limit a Shell to values that satisfy the predicate
--
-- This terminates the stream on the first value that does not satisfy
-- the predicate
limitWhile :: (a -> Bool) -> Shell a -> Shell a
-- | Cache a Shell's output so that repeated runs of the script will
-- reuse the result of previous runs. You must supply a FilePath
-- where the cached result will be stored.
--
-- The stored result is only reused if the Shell successfully ran
-- to completion without any exceptions. Note: on some platforms Ctrl-C
-- will flush standard input and signal end of file before killing the
-- program, which may trick the program into "successfully" completing.
cache :: (Read a, Show a) => FilePath -> Shell a -> Shell a
-- | Run a list of IO actions in parallel using fork and wait.
--
--
-- >>> view (parallel [(sleep 3) >> date, date, date])
-- 2016-12-01 17:22:10.83296 UTC
-- 2016-12-01 17:22:07.829876 UTC
-- 2016-12-01 17:22:07.829963 UTC
--
parallel :: [IO a] -> Shell a
-- | Returns the result of a Shell that outputs a single line:
--
--
-- main = do
-- Just directory <- single (inshell "pwd" empty)
-- print directory
--
single :: MonadIO io => Shell a -> io a
-- | Count the number of characters in the stream (like wc -c)
--
-- This uses the convention that the elements of the stream are
-- implicitly ended by newlines that are one character wide
countChars :: Integral n => Fold Line n
-- | Count the number of words in the stream (like wc -w)
countWords :: Integral n => Fold Line n
-- | Count the number of lines in the stream (like wc -l)
--
-- This uses the convention that each element of the stream represents
-- one line
countLines :: Integral n => Fold Line n
-- | Split a line into chunks delimited by the given Pattern
cut :: Pattern a -> Text -> [Text]
-- | Run a command using execvp, retrieving the exit code
--
-- The command inherits stdout and stderr for the
-- current process
proc :: MonadIO io => Text -> [Text] -> Shell Line -> io ExitCode
-- | 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
shell :: MonadIO io => Text -> Shell Line -> io ExitCode
-- | This function is identical to proc except this throws
-- ProcFailed for non-zero exit codes
procs :: MonadIO io => Text -> [Text] -> Shell Line -> io ()
-- | This function is identical to shell except this throws
-- ShellFailed for non-zero exit codes
shells :: MonadIO io => Text -> Shell Line -> io ()
-- | Run a command using execvp, streaming stdout as
-- lines of Text
--
-- The command inherits stderr for the current process
inproc :: Text -> [Text] -> Shell Line -> Shell Line
-- | Run a command line using the shell, streaming stdout as lines
-- of Text
--
-- 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
inshell :: Text -> Shell Line -> Shell Line
-- | Run a command using the shell, streaming stdout and
-- stderr as lines of Text. Lines from stdout
-- are wrapped in Right and lines from stderr are wrapped
-- in Left.
--
-- Throws an ExitCode exception if the command returns a non-zero
-- exit code
inprocWithErr :: Text -> [Text] -> Shell Line -> Shell (Either Line Line)
-- | Run a command line using the shell, streaming stdout and
-- stderr as lines of Text. Lines from stdout
-- are wrapped in Right and lines 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
inshellWithErr :: Text -> Shell Line -> Shell (Either Line Line)
-- | 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
procStrict :: MonadIO io => Text -> [Text] -> Shell Line -> io (ExitCode, Text)
-- | 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
shellStrict :: MonadIO io => Text -> Shell Line -> io (ExitCode, Text)
-- | Run a command using execvp, retrieving the exit code, stdout,
-- and stderr as a non-lazy blob of Text
procStrictWithErr :: MonadIO io => Text -> [Text] -> Shell Line -> io (ExitCode, Text, Text)
-- | 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
shellStrictWithErr :: MonadIO io => Text -> Shell Line -> io (ExitCode, Text, Text)
-- | 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
system :: MonadIO io => CreateProcess -> Shell Line -> io ExitCode
-- | 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
stream :: CreateProcess -> Shell Line -> Shell Line
-- | 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
streamWithErr :: CreateProcess -> Shell Line -> Shell (Either Line Line)
-- | 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
systemStrict :: MonadIO io => CreateProcess -> Shell Line -> io (ExitCode, Text)
-- | 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
systemStrictWithErr :: MonadIO io => CreateProcess -> Shell Line -> io (ExitCode, Text, Text)
-- | This type is the same as
-- System.Directory.Permissions type except
-- combining the executable and searchable fields into a
-- single executable field for consistency with the Unix
-- chmod. This simplification is still entirely consistent with
-- the behavior of System.Directory, which treats the two fields
-- as interchangeable.
data Permissions
Permissions :: Bool -> Bool -> Bool -> Permissions
[_readable] :: Permissions -> Bool
[_writable] :: Permissions -> Bool
[_executable] :: Permissions -> Bool
-- | Update a file or directory's user permissions
--
--
-- chmod rwo "foo.txt" -- chmod u=rw foo.txt
-- chmod executable "foo.txt" -- chmod u+x foo.txt
-- chmod nonwritable "foo.txt" -- chmod u-w foo.txt
--
--
-- The meaning of each permission is:
--
--
-- - readable (+r for short): For files, determines
-- whether you can read from that file (such as with input). For
-- directories, determines whether or not you can list the directory
-- contents (such as with ls). Note: if a directory is not
-- readable then ls will stream an empty list of contents
-- - writable (+w for short): For files, determines
-- whether you can write to that file (such as with output). For
-- directories, determines whether you can create a new file underneath
-- that directory.
-- - executable (+x for short): For files, determines
-- whether or not that file is executable (such as with proc). For
-- directories, determines whether or not you can read or execute files
-- underneath that directory (such as with input or
-- proc)
--
chmod :: MonadIO io => (Permissions -> Permissions) -> FilePath -> io Permissions
-- | Get a file or directory's user permissions
getmod :: MonadIO io => FilePath -> io Permissions
-- | Set a file or directory's user permissions
setmod :: MonadIO io => Permissions -> FilePath -> io ()
-- | Copy a file or directory's permissions (analogous to chmod
-- --reference)
copymod :: MonadIO io => FilePath -> FilePath -> io ()
-- |
-- +r
--
readable :: Permissions -> Permissions
-- |
-- -r
--
nonreadable :: Permissions -> Permissions
-- |
-- +w
--
writable :: Permissions -> Permissions
-- |
-- -w
--
nonwritable :: Permissions -> Permissions
-- |
-- +x
--
executable :: Permissions -> Permissions
-- |
-- -x
--
nonexecutable :: Permissions -> Permissions
-- |
-- -r -w -x
--
ooo :: Permissions -> Permissions
-- |
-- +r -w -x
--
roo :: Permissions -> Permissions
-- |
-- -r +w -x
--
owo :: Permissions -> Permissions
-- |
-- -r -w +x
--
oox :: Permissions -> Permissions
-- |
-- +r +w -x
--
rwo :: Permissions -> Permissions
-- |
-- +r -w +x
--
rox :: Permissions -> Permissions
-- |
-- -r +w +x
--
owx :: Permissions -> Permissions
-- |
-- +r +w +x
--
rwx :: Permissions -> Permissions
-- | Get the size of a file or a directory
du :: MonadIO io => FilePath -> io Size
-- | An abstract file size
--
-- Specify the units you want by using an accessor like kilobytes
--
-- The Num instance for Size interprets numeric literals as
-- bytes
data Size
-- | Format a Size using a human readable representation
--
--
-- >>> format sz 42
-- "42 B"
--
-- >>> format sz 2309
-- "2.309 KB"
--
-- >>> format sz 949203
-- "949.203 KB"
--
-- >>> format sz 1600000000
-- "1.600 GB"
--
-- >>> format sz 999999999999999999
-- "999999.999 TB"
--
sz :: Format r (Size -> r)
-- | Extract a size in bytes
bytes :: Integral n => Size -> n
-- |
-- 1 kilobyte = 1000 bytes
--
kilobytes :: Integral n => Size -> n
-- |
-- 1 megabyte = 1000 kilobytes
--
megabytes :: Integral n => Size -> n
-- |
-- 1 gigabyte = 1000 megabytes
--
gigabytes :: Integral n => Size -> n
-- |
-- 1 terabyte = 1000 gigabytes
--
terabytes :: Integral n => Size -> n
-- |
-- 1 kibibyte = 1024 bytes
--
kibibytes :: Integral n => Size -> n
-- |
-- 1 mebibyte = 1024 kibibytes
--
mebibytes :: Integral n => Size -> n
-- |
-- 1 gibibyte = 1024 mebibytes
--
gibibytes :: Integral n => Size -> n
-- |
-- 1 tebibyte = 1024 gibibytes
--
tebibytes :: Integral n => Size -> n
-- | POSIX defines operations to get information, such as owner,
-- permissions, size and access times, about a file. This information is
-- represented by the FileStatus type.
--
-- Note: see chmod.
data FileStatus :: *
-- | Get the status of a file
stat :: MonadIO io => FilePath -> io FileStatus
-- | Get the status of a file, but don't follow symbolic links
lstat :: MonadIO io => FilePath -> io FileStatus
-- | Size of the file in bytes. Does not follow symlinks
fileSize :: FileStatus -> Size
-- | Time of last access
accessTime :: FileStatus -> POSIXTime
-- | Time of last modification
modificationTime :: FileStatus -> POSIXTime
-- | Time of last status change (i.e. owner, group, link count, mode, etc.)
statusChangeTime :: FileStatus -> POSIXTime
-- | Checks if this file is a block device.
isBlockDevice :: FileStatus -> Bool
-- | Checks if this file is a character device.
isCharacterDevice :: FileStatus -> Bool
-- | Checks if this file is a named pipe device.
isNamedPipe :: FileStatus -> Bool
-- | Checks if this file is a regular file device.
isRegularFile :: FileStatus -> Bool
-- | Checks if this file is a directory device.
isDirectory :: FileStatus -> Bool
-- | Checks if this file is a symbolic link device.
isSymbolicLink :: FileStatus -> Bool
-- | Checks if this file is a socket device.
isSocket :: FileStatus -> Bool
data WithHeader a
-- | The first line with the header
Header :: a -> WithHeader a
-- | Every other line: 1st element is header, 2nd element is original row
Row :: a -> a -> WithHeader a
header :: Shell a -> Shell (WithHeader a)
data ProcFailed
ProcFailed :: Text -> [Text] -> ExitCode -> ProcFailed
[procCommand] :: ProcFailed -> Text
[procArguments] :: ProcFailed -> [Text]
[procExitCode] :: ProcFailed -> ExitCode
data ShellFailed
ShellFailed :: Text -> ExitCode -> ShellFailed
[shellCommandLine] :: ShellFailed -> Text
[shellExitCode] :: ShellFailed -> ExitCode
instance GHC.Show.Show a => GHC.Show.Show (Turtle.Prelude.WithHeader a)
instance GHC.Num.Num Turtle.Prelude.Size
instance GHC.Classes.Ord Turtle.Prelude.Size
instance GHC.Classes.Eq Turtle.Prelude.Size
instance GHC.Show.Show Turtle.Prelude.Permissions
instance GHC.Classes.Ord Turtle.Prelude.Permissions
instance GHC.Read.Read Turtle.Prelude.Permissions
instance GHC.Classes.Eq Turtle.Prelude.Permissions
instance GHC.Show.Show Turtle.Prelude.ShellFailed
instance GHC.Show.Show Turtle.Prelude.ProcFailed
instance GHC.Exception.Exception Turtle.Prelude.ProcFailed
instance GHC.Exception.Exception Turtle.Prelude.ShellFailed
instance GHC.Show.Show Turtle.Prelude.Size
-- | 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.
module Turtle.Bytes
-- | Read chunks of bytes from standard input
--
-- The chunks are not necessarily aligned to line boundaries
stdin :: Shell ByteString
-- | Read chunks of bytes from a file
--
-- The chunks are not necessarily aligned to line boundaries
input :: FilePath -> Shell ByteString
-- | Read chunks of bytes from a Handle
--
-- The chunks are not necessarily aligned to line boundaries
inhandle :: Handle -> Shell ByteString
-- | Stream chunks of bytes to standard output
--
-- The chunks are not necessarily aligned to line boundaries
stdout :: MonadIO io => Shell ByteString -> io ()
-- | Stream chunks of bytes to a file
--
-- The chunks do not need to be aligned to line boundaries
output :: MonadIO io => FilePath -> Shell ByteString -> io ()
-- | Stream chunks of bytes to a Handle
--
-- The chunks do not need to be aligned to line boundaries
outhandle :: MonadIO io => Handle -> Shell ByteString -> io ()
-- | Append chunks of bytes to append to a file
--
-- The chunks do not need to be aligned to line boundaries
append :: MonadIO io => FilePath -> Shell ByteString -> io ()
-- | Stream chunks of bytes to standard error
--
-- The chunks do not need to be aligned to line boundaries
stderr :: MonadIO io => Shell ByteString -> io ()
-- | Read in a stream's contents strictly
strict :: MonadIO io => Shell ByteString -> io ByteString
-- | Run a command using execvp, retrieving the exit code
--
-- The command inherits stdout and stderr for the
-- current process
proc :: MonadIO io => Text -> [Text] -> Shell ByteString -> io ExitCode
-- | 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
shell :: MonadIO io => Text -> Shell ByteString -> io ExitCode
-- | This function is identical to proc except this throws
-- ProcFailed for non-zero exit codes
procs :: MonadIO io => Text -> [Text] -> Shell ByteString -> io ()
-- | This function is identical to shell except this throws
-- ShellFailed for non-zero exit codes
shells :: MonadIO io => Text -> Shell ByteString -> io ()
-- | Run a command using execvp, streaming stdout as
-- chunks of ByteString
--
-- The command inherits stderr for the current process
inproc :: Text -> [Text] -> Shell ByteString -> Shell ByteString
-- | 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
inshell :: Text -> Shell ByteString -> Shell ByteString
-- | 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
inprocWithErr :: Text -> [Text] -> Shell ByteString -> Shell (Either ByteString ByteString)
-- | 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
inshellWithErr :: Text -> Shell ByteString -> Shell (Either ByteString ByteString)
-- | 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
procStrict :: MonadIO io => Text -> [Text] -> Shell ByteString -> io (ExitCode, ByteString)
-- | 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
shellStrict :: MonadIO io => Text -> Shell ByteString -> io (ExitCode, ByteString)
-- | Run a command using execvp, retrieving the exit code, stdout,
-- and stderr as a non-lazy blob of Text
procStrictWithErr :: MonadIO io => Text -> [Text] -> Shell ByteString -> io (ExitCode, ByteString, ByteString)
-- | 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
shellStrictWithErr :: MonadIO io => Text -> Shell ByteString -> io (ExitCode, ByteString, ByteString)
-- | 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
system :: MonadIO io => CreateProcess -> Shell ByteString -> io ExitCode
-- | 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
stream :: CreateProcess -> Shell ByteString -> Shell ByteString
-- | 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
streamWithErr :: CreateProcess -> Shell ByteString -> Shell (Either ByteString ByteString)
-- | 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
systemStrict :: MonadIO io => CreateProcess -> Shell ByteString -> io (ExitCode, ByteString)
-- | 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
systemStrictWithErr :: MonadIO io => CreateProcess -> Shell ByteString -> io (ExitCode, ByteString, ByteString)
-- | See Turtle.Tutorial to learn how to use this library or
-- Turtle.Prelude for a quick-start guide.
--
-- Here is the recommended way to import this library:
--
--
-- {-# LANGUAGE OverloadedStrings #-}
--
-- import Turtle
-- import Prelude hiding (FilePath)
--
--
-- This module re-exports the rest of the library and also re-exports
-- useful modules from base:
--
-- Turtle.Format provides type-safe string formatting
--
-- Turtle.Pattern provides Patterns, which are like more
-- powerful regular expressions
--
-- Turtle.Shell provides a Shell abstraction for building
-- streaming, exception-safe pipelines
--
-- Turtle.Prelude provides a library of Unix-like utilities to get
-- you started with basic shell-like programming within Haskell
--
-- Control.Applicative provides two classes:
--
--
--
-- Control.Monad provides two classes:
--
--
--
-- Control.Monad.IO.Class provides one class:
--
--
--
-- Data.Monoid provides one class:
--
--
--
-- Control.Monad.Managed.Safe provides Managed resources
--
-- Filesystem.Path.CurrentOS provides FilePath-manipulation
-- utilities
--
-- Additionally, you might also want to import the following modules
-- qualified:
--
--
module Turtle
-- | Efficient representation of a left fold that preserves the fold's step
-- function, initial accumulator, and extraction function
--
-- This allows the Applicative instance to assemble derived folds
-- that traverse the container only once
--
-- A 'Fold a b' processes elements of type a and results in
-- a value of type b.
data Fold a b :: * -> * -> *
-- | Fold step initial extract
[Fold] :: Fold a b
-- | Like Fold, but monadic.
--
-- A 'FoldM m a b' processes elements of type a and results
-- in a monadic value of type m b.
data FoldM (m :: * -> *) a b :: (* -> *) -> * -> * -> *
-- | FoldM step initial extract
[FoldM] :: FoldM m a b
-- | A space efficient, packed, unboxed Unicode text type.
data Text :: *
-- | This is the simplest representation of UTC. It consists of the day
-- number, and a time offset from midnight. Note that if a day has a leap
-- second added to it, it will have 86401 seconds.
data UTCTime :: *
-- | This is a length of time, as measured by UTC. Conversion functions
-- will treat it as seconds. It has a precision of 10^-12 s. It ignores
-- leap-seconds, so it's not necessarily a fixed amount of clock time.
-- For instance, 23:00 UTC + 2 hours of NominalDiffTime = 01:00 UTC (+ 1
-- day), regardless of whether a leap-second intervened.
data NominalDiffTime :: *
-- | Haskell defines operations to read and write characters from and to
-- files, represented by values of type Handle. Each value of
-- this type is a handle: a record used by the Haskell run-time
-- system to manage I/O with file system objects. A handle has at
-- least the following properties:
--
--
-- - whether it manages input or output or both;
-- - whether it is open, closed or
-- semi-closed;
-- - whether the object is seekable;
-- - whether buffering is disabled, or enabled on a line or block
-- basis;
-- - a buffer (whose length may be zero).
--
--
-- Most handles will also have a current I/O position indicating where
-- the next input or output operation will occur. A handle is
-- readable if it manages only input or both input and output;
-- likewise, it is writable if it manages only output or both
-- input and output. A handle is open when first allocated. Once
-- it is closed it can no longer be used for either input or output,
-- though an implementation cannot re-use its storage while references
-- remain to it. Handles are in the Show and Eq classes.
-- The string produced by showing a handle is system dependent; it should
-- include enough information to identify the handle for debugging. A
-- handle is equal according to == only to itself; no attempt is
-- made to compare the internal state of different handles for equality.
data Handle :: *
-- | Defines the exit codes that a program can return.
data ExitCode :: *
-- | indicates successful termination;
ExitSuccess :: ExitCode
-- | indicates program failure with an exit code. The exact interpretation
-- of the code is operating-system dependent. In particular, some values
-- may be prohibited (e.g. 0 on a POSIX-compliant system).
ExitFailure :: Int -> ExitCode
-- | Class for string-like datastructures; used by the overloaded string
-- extension (-XOverloadedStrings in GHC).
class IsString a
fromString :: IsString a => String -> a
-- | & is a reverse application operator. This provides
-- notational convenience. Its precedence is one higher than that of the
-- forward application operator $, which allows & to be
-- nested in $.
(&) :: a -> (a -> b) -> b
infixl 1 &
-- | Use turtle if you want to write light-weight and maintainable
-- shell scripts.
--
-- turtle embeds shell scripting directly within Haskell for
-- three main reasons:
--
--
-- - Haskell code is easy to refactor and maintain because the language
-- is statically typed
-- - Haskell is syntactically lightweight, thanks to global type
-- inference
-- - Haskell programs can be type-checked and interpreted very rapidly
-- (< 1 second)
--
--
-- These features make Haskell ideal for scripting, particularly for
-- replacing large and unwieldy Bash scripts.
--
-- This tutorial introduces how to use the turtle library to
-- write Haskell scripts. This assumes no prior knowledge of Haskell, but
-- does assume prior knowledge of Bash or a similar shell scripting
-- language.
--
-- If you are already proficient with Haskell, then you can get quickly
-- up to speed by reading the Quick Start guide at the top of
-- Turtle.Prelude.
--
-- If you are on Windows, the easiest way to follow along is to install
-- Git for Windows and use the Git Bash program that it installs
-- to get a fully featured Unix-like environment.
--
-- For all operating systems, the recommended way to compile and run the
-- following examples is to download the stack package
-- management tool by following the instructions here:
--
-- https://github.com/commercialhaskell/stack
--
-- ... and then run the following instruction anywhere outside of a
-- Haskell project:
--
--
-- $ stack install turtle
--
--
-- This tutorial will mostly focus on using Haskell as a scripting
-- language. The first two lines of each script below contain boilerplate
-- instructions so that stack will load and run the script. This
-- helps ensure that a script will run on any computer that has a
-- stack executable, as stack can install a Haskell
-- compiler if one is not already present. If you are curious about how
-- these two lines work, they are described here:
--
--
-- https://github.com/commercialhaskell/stack/blob/master/doc/GUIDE.md#ghcrunghc
--
-- If you want to make a Windows script independently executable outside
-- of a Git Bash environment, you can either (A) compile the script into
-- an executable or (B) run these two commands from a cmd shell
-- with administrator privileges to make all *.hs scripts
-- executable:
--
--
-- assoc .hs=Haskell
-- ftype Haskell="C:\path\to\stack.exe" "%1" %*
--
module Turtle.Tutorial