turtle-1.3.1: Shell programming, Haskell-style

Safe Haskell | None
Language | Haskell2010

Turtle.Options

Contents

- Types
- Flag-based option parsers
- Positional argument parsers
- Consume parsers

Description

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.

Synopsis

- data Parser a :: * -> *
- newtype ArgName = ArgName {
  - getArgName :: Text
  }
- newtype CommandName = CommandName {
  - getCommandName :: Text
  }
- type ShortName = Char
- newtype Description = Description {
  - getDescription :: Doc
  }
- newtype HelpMessage = HelpMessage {
  - getHelpMessage :: Text
  }
- switch :: ArgName -> ShortName -> Optional HelpMessage -> Parser Bool
- optText :: ArgName -> ShortName -> Optional HelpMessage -> Parser Text
- optInt :: ArgName -> ShortName -> Optional HelpMessage -> Parser Int
- optInteger :: ArgName -> ShortName -> Optional HelpMessage -> Parser Integer
- optDouble :: ArgName -> ShortName -> Optional HelpMessage -> Parser Double
- optPath :: ArgName -> ShortName -> Optional HelpMessage -> Parser FilePath
- optRead :: Read a => ArgName -> ShortName -> Optional HelpMessage -> Parser a
- opt :: (Text -> Maybe a) -> ArgName -> ShortName -> Optional HelpMessage -> Parser a
- argText :: ArgName -> Optional HelpMessage -> Parser Text
- argInt :: ArgName -> Optional HelpMessage -> Parser Int
- argInteger :: ArgName -> Optional HelpMessage -> Parser Integer
- argDouble :: ArgName -> Optional HelpMessage -> Parser Double
- argPath :: ArgName -> Optional HelpMessage -> Parser FilePath
- argRead :: Read a => ArgName -> Optional HelpMessage -> Parser a
- arg :: (Text -> Maybe a) -> ArgName -> Optional HelpMessage -> Parser a
- subcommand :: CommandName -> Description -> Parser a -> Parser a
- subcommandGroup :: forall a. Description -> [(CommandName, Description, Parser a)] -> Parser a
- options :: MonadIO io => Description -> Parser a -> io a

# Types

data Parser a :: * -> * #

A `Parser a` is an option parser returning a value of type `a`.

Instances

Functor Parser |
Methods fmap :: (a -> b) -> Parser a -> Parser b # (<$) :: a -> Parser b -> Parser a #
Applicative Parser |
Methods pure :: a -> Parser a # (<*>) :: Parser (a -> b) -> Parser a -> Parser b # (*>) :: Parser a -> Parser b -> Parser b # (<*) :: Parser a -> Parser b -> Parser a #
Alternative Parser |
Methods empty :: Parser a # (<|>) :: Parser a -> Parser a -> Parser a # some :: Parser a -> Parser [a] # many :: Parser a -> Parser [a] #

newtype ArgName #

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

Constructors

ArgName |
Fields getArgName :: Text

Instances

IsString ArgName # |
Methods fromString :: String -> ArgName #

newtype CommandName #

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.

Constructors

CommandName |
Fields getCommandName :: Text

Instances

IsString CommandName # |
Methods fromString :: String -> CommandName #

type ShortName = Char #

The short one-character abbreviation for a flag (i.e. `-n`)

newtype Description #

A brief description of what your program does

This description will appear in the header of the `--help` output

Constructors

Description |
Fields getDescription :: Doc

Instances

IsString Description # |
Methods fromString :: String -> Description #

newtype HelpMessage #

A helpful message explaining what a flag does

This will appear in the `--help` output

Constructors

HelpMessage |
Fields getHelpMessage :: Text

Instances

IsString HelpMessage # |
Methods fromString :: String -> HelpMessage #

# Flag-based option parsers

switch :: ArgName -> ShortName -> Optional HelpMessage -> Parser Bool #

This parser returns `True` if the given flag is set and `False` if the flag is absent

optText :: ArgName -> ShortName -> Optional HelpMessage -> Parser Text #

Parse a `Text` value as a flag-based option

optInt :: ArgName -> ShortName -> Optional HelpMessage -> Parser Int #

Parse an `Int` as a flag-based option

optInteger :: ArgName -> ShortName -> Optional HelpMessage -> Parser Integer #

Parse an `Integer` as a flag-based option

optDouble :: ArgName -> ShortName -> Optional HelpMessage -> Parser Double #

Parse a `Double` as a flag-based option

optPath :: ArgName -> ShortName -> Optional HelpMessage -> Parser FilePath #

Parse a `FilePath` value as a flag-based option

optRead :: Read a => ArgName -> ShortName -> Optional HelpMessage -> Parser a #

Parse any type that implements `Read`

opt :: (Text -> Maybe a) -> ArgName -> ShortName -> Optional HelpMessage -> Parser a #

Build a flag-based option parser for any type by providing a `Text`-parsing function

# Positional argument parsers

argText :: ArgName -> Optional HelpMessage -> Parser Text #

Parse a `Text` as a positional argument

argInt :: ArgName -> Optional HelpMessage -> Parser Int #

Parse an `Int` as a positional argument

argInteger :: ArgName -> Optional HelpMessage -> Parser Integer #

Parse an `Integer` as a positional argument

argDouble :: ArgName -> Optional HelpMessage -> Parser Double #

Parse a `Double` as a positional argument

argPath :: ArgName -> Optional HelpMessage -> Parser FilePath #

Parse a `FilePath` as a positional argument

argRead :: Read a => ArgName -> Optional HelpMessage -> Parser a #

Parse any type that implements `Read` as a positional argument

arg :: (Text -> Maybe a) -> ArgName -> Optional HelpMessage -> Parser a #

Build a positional argument parser for any type by providing a `Text`-parsing function

# Consume parsers

subcommand :: CommandName -> Description -> Parser a -> 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

subcommandGroup :: forall a. Description -> [(CommandName, Description, Parser a)] -> Parser a #

Create a named group of sub-commands

options :: MonadIO io => Description -> Parser a -> io a #

Parse the given options from the command line