Module

ArgParse.Basic

Package
purescript-argparse-basic
Repository
natefaubion/purescript-argparse-basic

#ArgParser Source

data ArgParser a

Instances

#ArgError Source

data ArgError

Constructors

#flag Source

flag :: Array String -> String -> ArgParser Unit

Matches a single flag. For flags that return Boolean, combine with boolean.

example =
  flag [ "--toggle", "-t" ] "Toggles something."
    # boolean

#flagHelp Source

flagHelp :: ArgParser Unit

Adds a --help flag to a parser, which will immediately halt the parser and display help documentation. Best combined with *> or <*.

example =
  flagHelp *> fromRecord
    { ...
    }

#flagInfo Source

flagInfo :: Array String -> String -> String -> ArgParser Unit

Adds an info flag to a parser, which will immediately halt the parser and display the information. Useful for version flags. Best combined with *> or <*.

example =
  flagInfo [ "--version", "-v" ] "1.0.0"
    *> fromRecord { ... }

#argument Source

argument :: Array String -> String -> ArgParser String

Matches a flag, followed by a single argument, yielding the argument. The argument and flag may be separated by either a space or =.

example = argument [ "--arg", "-a" ] "Some argument."

In this example, all of the following would be valid ways to pass in an argument:

  • --arg value
  • --arg=value
  • -a value
  • -a=value

#fromRecord Source

fromRecord :: forall rin rl rout. RowToList rin rl => BuildRecordArgs rl (Record rin) (Record ()) (Record rout) => Record rin -> ArgParser (Record rout)

Builds a record parser from a record of parsers.

example = fromRecord
  { int:
      argument [ "--int", "-i" ] "Some integer."
        # int
  , date:
      argument [ "--date", "-d" ] " Some date."
        # unformat "DATE" (unformatDateTime "YYYY-MM-DD")
  , many:
      argument [ "--many", "-m" ] "Collect multiple arguments"
        # many
  }

#unformat Source

unformat :: forall a b. String -> (a -> Either String b) -> ArgParser a -> ArgParser b

Parses a value into some other type, or fails with an error.

example =
  argument [ "--date", "-d" ] "Some date."
    # unformat "DATE" (unformatDateTime "YYYY-MM-DD")
    -- From purescript-formatters

#int Source

int :: ArgParser String -> ArgParser Int

Parses an argument as an Int.

example =
  argument [ "--int", "-i" ] "Some integer."
    # int

#number Source

number :: ArgParser String -> ArgParser Number

Parses an argument as an Number.

example =
  argument [ "--num", "-n" ] "Some number."
    # number

#boolean Source

boolean :: ArgParser Unit -> ArgParser Boolean

Parses a flag as a Boolean, defaulting to false.

example =
  flag [ "--flag", "-f" ] "Some boolean."
    # boolean

#separated Source

separated :: String -> Pattern -> ArgParser String -> ArgParser (Array String)

Splits a value on some separator (using Data.String.split).

example =
  argument [ "--sep", "-s" ] "Separated by commas"
    # separated "ARG" (Pattern ",")

#many Source

many :: forall a. ArgParser a -> ArgParser (List a)

Collects multiple matches of a parser into a List.

example =
  argument [ "--many", "-m" ] "Collect multiple arguments"
    # many

In this example, passing int --many a --many b -m c would yield a List with three values.

#many1 Source

many1 :: forall a. ArgParser a -> ArgParser (NonEmptyList a)

Collects multiple matches of a parser into a NonEmptyList. Omitting the argument yields an error.

#unfolded Source

unfolded :: forall f a. Unfoldable f => ArgParser a -> ArgParser (f a)

Similar to many, but collects matches into any Unfoldable.

#unfolded1 Source

unfolded1 :: forall f a. Unfoldable1 f => ArgParser a -> ArgParser (f a)

Similar to many1, but collects matches into any Unfoldable1.

#folded Source

folded :: forall a. Monoid a => ArgParser a -> ArgParser a

Similar to many, but collects matches with Monoid.

#folded1 Source

folded1 :: forall a. Semigroup a => ArgParser a -> ArgParser a

Similar to many1, but collects matches with Semigroup.

#default Source

default :: forall a. a -> ArgParser a -> ArgParser a

Provides a default value for when an argument is not otherwise provided.

#optional Source

optional :: forall a. ArgParser a -> ArgParser (Maybe a)

Makes any argument optional with Maybe.

#choose Source

choose :: forall a. String -> Array (ArgParser a) -> ArgParser a

Matches one value from a set of parsers. This is useful for commmands and enumerations.

data Order = First | Second | Third

example = choose "order"
  [ flag [ "--first", "-1" ] "First in order." $> First
  , flag [ "--second", "-2" ] "Second in order." $> Second
  [ flag [ "--third", "-3" ] "Third in order." $> Third
  ]

#command Source

command :: forall a. Array String -> String -> ArgParser a -> ArgParser a

Runs a parser as a sub-command, where it is expected to consume the rest of the argument input. Best combined with choose for multiple commands.

example =
  command [ "some-command", "sc" ] "Some command." do
    flagHelp *> fromRecord
      { ...
      }

#any Source

any :: forall a. String -> String -> (String -> Maybe a) -> ArgParser a

Matches any argument that satisfies a given predicate. Good for collecting leftover arguments. It is not recommended to use any with fromRecord, but instead order it specifically after other parsers using Applicative combinators.

example =
  Tuple
    <$> fromRecord { ... }
    <*> any "ANY" "Any leftover arguments." Just

#anyNotFlag Source

anyNotFlag :: String -> String -> ArgParser String

Like any, but matches anything that does not start with a "-". This works better with fromRecord since it generally does not overlap with other arguments.

#rest Source

rest :: forall f. Unfoldable f => String -> ArgParser (f String)

Collects the rest of the arguments in an input stream after encountering a --.

#parseArgs Source

parseArgs :: forall f a. Foldable f => String -> String -> ArgParser a -> f String -> Either ArgError a

Parses an input stream of arguments given a command name and description. The name and description will be used to generate help.

example =
  parseArgs "my-cli" "This is my CLI." myParser
    [ "-n", "42" ]

#printArgError Source

printArgError :: ArgError -> String

Prints an error to a String. This will include the full error context and help.

#printHelp Source

printHelp :: ArgHelp -> String

Prints help to a string.

#parserHelp Source

parserHelp :: forall a. ArgParser a -> ArgHelp

Gets the help associated with a parser.

#BuildRecordArgs Source

class BuildRecordArgs :: RowList Type -> Type -> Type -> Type -> Constraintclass BuildRecordArgs (rl :: RowList Type) rs rin rout | rl -> rout where

Members

Instances

Modules
ArgParse.Basic