Safe Haskell	Safe-Inferred
Language	Haskell2010

Data.Range.Parser

Contents

Parsing
Configuration
Lower-level parser
Re-exports

Description

A simple parser for human-readable range strings, designed for CLI programs.

By default, ranges are separated by commas and span endpoints by a hyphen:

>>> parseRanges "-5,8-10,13-15,20-" :: Either ParseError (Ranges Integer)
Right (Ranges [ubi 5,8 +=+ 10,13 +=+ 15,lbi 20])

The * wildcard produces an infinite range:

>>> parseRanges "*" :: Either ParseError (Ranges Integer)
Right (Ranges [inf])

Use customParseRanges to change the separator characters:

>>> let args = defaultArgs { unionSeparator = ";", rangeSeparator = ".." }
>>> customParseRanges args "1..5;10" :: Either ParseError (Ranges Integer)
Right (Ranges [1 +=+ 5,SingletonRange 10])

Known limitations:

Only non-negative integer literals are recognised. The input "-5" is parsed as UpperBoundRange 5 (an upper-bounded range), not SingletonRange (-5). For negative values, use customParseRanges with a different rangeSeparator, or pre-process the input string.
Unrecognised input is silently consumed as an empty set rather than producing a parse error. For example, parseRanges "abc" returns Right mempty. This is a consequence of using sepBy internally and is by design for CLI use where partial input is common.

For more complex parsing (e.g. .cabal or package.json files), parse version strings with Parsec or Alex/Happy and convert the results into Range values directly, then call mergeRanges.

Synopsis

parseRanges :: (Read a, Ord a) => String -> Either ParseError (Ranges a)
customParseRanges :: (Read a, Ord a) => RangeParserArgs -> String -> Either ParseError (Ranges a)
data RangeParserArgs = Args {
- unionSeparator :: String
- rangeSeparator :: String
- wildcardSymbol :: String
}
defaultArgs :: RangeParserArgs
ranges :: Read a => RangeParserArgs -> Parser [Range a]
data ParseError

Parsing

parseRanges :: (Read a, Ord a) => String -> Either ParseError (Ranges a) Source #

Parses a range string using the default separators (, and -). Returns either a ParseError or a canonicalised Ranges value ready for membership testing and set operations.

The Read instance of a is used to parse individual numeric literals, so the type must have a well-behaved Read. Exotic types with unusual Read instances may not parse correctly.

See the module documentation for known limitations around negative numbers and unrecognised input.

customParseRanges :: (Read a, Ord a) => RangeParserArgs -> String -> Either ParseError (Ranges a) Source #

Like parseRanges but with caller-supplied separator configuration. Use this when the default , and - characters conflict with your input format.

>>> let args = defaultArgs { unionSeparator = ";", rangeSeparator = ".." }
>>> customParseRanges args "1..5;10" :: Either ParseError (Ranges Integer)
Right (Ranges [1 +=+ 5,SingletonRange 10])

Configuration

data RangeParserArgs Source #

Configuration for the range parser. All three fields are plain strings, so multi-character separators (e.g. "..") are supported.

Constructors

Args
Fields unionSeparator :: String Separates multiple ranges in a union. Default: `","`. rangeSeparator :: String Separates the two endpoints of a span. Default: `"-"`. wildcardSymbol :: String Symbol for an infinite range. Default: `"*"`.

Instances

Instances details

Show RangeParserArgs Source #
Instance details Defined in Data.Range.Parser Methods showsPrec :: Int -> RangeParserArgs -> ShowS show :: RangeParserArgs -> String showList :: [RangeParserArgs] -> ShowS

defaultArgs :: RangeParserArgs Source #

The default parser configuration: comma-separated ranges, hyphen-separated endpoints, and * as the wildcard. Modify individual fields with record syntax:

>>> defaultArgs { unionSeparator = ";", rangeSeparator = ".." }
Args {unionSeparator = ";", rangeSeparator = "..", wildcardSymbol = "*"}

Lower-level parser

ranges :: Read a => RangeParserArgs -> Parser [Range a] Source #

Returns a Parsec Parser for a list of ranges using the given configuration. Use this when embedding range parsing into a larger Parsec grammar; for standalone parsing prefer parseRanges or customParseRanges.

The returned list is unmerged — call mergeRanges on the result to produce a canonical Ranges value.

Re-exports

ParseError is re-exported from Text.Parsec for convenience, so callers do not need to import Parsec directly just to match on parse failures.

data ParseError #

Instances

Instances details

Exception ParseError
Instance details Defined in Text.Parsec.Error Methods toException :: ParseError -> SomeException fromException :: SomeException -> Maybe ParseError displayException :: ParseError -> String backtraceDesired :: ParseError -> Bool
Show ParseError
Instance details Defined in Text.Parsec.Error Methods showsPrec :: Int -> ParseError -> ShowS show :: ParseError -> String showList :: [ParseError] -> ShowS
Eq ParseError
Instance details Defined in Text.Parsec.Error Methods (==) :: ParseError -> ParseError -> Bool (/=) :: ParseError -> ParseError -> Bool