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


-- | This has a bunch of code for specifying and managing ranges in your code.
--   
@package range
@version 0.1.2.0

module Data.Range.Algebra
data RangeExpr a
const :: a -> RangeExpr a
invert :: RangeExpr a -> RangeExpr a
union :: RangeExpr a -> RangeExpr a -> RangeExpr a
intersection :: RangeExpr a -> RangeExpr a -> RangeExpr a
difference :: RangeExpr a -> RangeExpr a -> RangeExpr a
type Algebra f a = f a -> a
class RangeAlgebra a
eval :: RangeAlgebra a => Algebra RangeExpr a
instance [safe] RangeAlgebra (a -> Bool)
instance [safe] (Ord a, Enum a) => RangeAlgebra [Range a]


-- | Internally the range library converts your ranges into an internal
--   representation of multiple ranges that I call a RangeMerge. When you
--   do multiple unions and intersections in a row converting to and from
--   that data structure becomes extra work that is not required. To
--   amortize those costs away the RangeTree structure exists. You can
--   specify a tree of operations in advance and then evaluate them all at
--   once. This is not only useful for efficiency but for parsing too. Use
--   RangeTree's whenever you wish to perform multiple operations in a row
--   and wish for it to be as efficient as possible.
module Data.Range.RangeTree

-- | Evaluates a Range Tree into the final set of ranges that it compresses
--   down to. Use this whenever you want to finally evaluate your
--   constructed Range Tree.
evaluate :: (Ord a, Enum a) => RangeTree a -> [Range a]

-- | A Range Tree is a construct that can be built and then efficiently
--   evaluated so that you can compress an entire tree of operations on
--   ranges into a single range quickly. The only purpose of this tree is
--   to allow efficient construction of range operations that can be
--   evaluated as is required.
data RangeTree a

-- | Combine two range trees together with a single operation
RangeNode :: RangeOperation -> (RangeTree a) -> (RangeTree a) -> RangeTree a

-- | Invert a range tree, this is a <a>not</a> operation.
RangeNodeInvert :: (RangeTree a) -> RangeTree a

-- | A leaf with a set of ranges that are collected together.
RangeLeaf :: [Range a] -> RangeTree a

-- | These are the operations that can join two disjunct lists of ranges
--   together.
data RangeOperation

-- | Represents the set union operation.
RangeUnion :: RangeOperation

-- | Represents the set intersection operation.
RangeIntersection :: RangeOperation

-- | Represents the set difference operation.
RangeDifference :: RangeOperation


-- | This entire library is concerned with ranges and this module
--   implements the absolute basic range functions.
module Data.Range.Range

-- | The Range Data structure; it is capable of representing any type of
--   range. This is the primary data structure in this library. Everything
--   should be possible to convert back into this datatype. All ranges in
--   this structure are inclusively bound.
data Range a

-- | Represents a single element as a range.
SingletonRange :: a -> Range a

-- | Represents a bounded and inclusive range of elements.
SpanRange :: a -> a -> Range a

-- | Represents a range with only an inclusive lower bound.
LowerBoundRange :: a -> Range a

-- | Represents a range with only an inclusive upper bound.
UpperBoundRange :: a -> Range a

-- | Represents an infinite range over all values.
InfiniteRange :: Range a

-- | Given a range and a value it will tell you wether or not the value is
--   in the range. Remember that all ranges are inclusive.
inRange :: Ord a => Range a -> a -> Bool

-- | Given a list of ranges this function tells you if a value is in any of
--   those ranges. This is especially useful for more complex ranges.
inRanges :: Ord a => [Range a] -> a -> Bool

-- | A check to see if two ranges overlap. If they do then true is
--   returned; false otherwise.
rangesOverlap :: Ord a => Range a -> Range a -> Bool

-- | When you create a range there may be overlaps in your ranges. However,
--   for the sake of efficiency you probably want the list of ranges with
--   no overlaps. The mergeRanges function takes a set of ranges and
--   returns the same set specified by the minimum number of Range objects.
--   A useful function for cleaning up your ranges. Please note that, if
--   you use any of the other operations on sets of ranges like invert,
--   union and intersection then this is automatically done for you. Which
--   means that a function like this is redundant: mergeRanges .
--   intersection
mergeRanges :: (Ord a, Enum a) => [Range a] -> [Range a]

-- | An inversion function, given a set of ranges it returns the inverse
--   set of ranges.
invert :: (Ord a, Enum a) => [Range a] -> [Range a]

-- | Performs a set union between the two input ranges and returns the
--   resultant set of ranges.
union :: (Ord a, Enum a) => [Range a] -> [Range a] -> [Range a]

-- | Performs a set intersection between the two input ranges and returns
--   the resultant set of ranges.
intersection :: (Ord a, Enum a) => [Range a] -> [Range a] -> [Range a]

-- | Performs a set difference between the two input ranges and returns the
--   resultant set of ranges.
difference :: (Ord a, Enum a) => [Range a] -> [Range a] -> [Range a]

-- | A set of ranges represents a collection of real values without
--   actually instantiating those values. This allows you to have infinite
--   ranges. However, sometimes you wish to actually get the values that
--   your range represents, or even get a sample set of the values. This
--   function generates as many of the values that belong to your range as
--   you like.
fromRanges :: (Ord a, Enum a) => [Range a] -> [a]


-- | Nested Ranges are common in practical usage. They appear in such forms
--   as library version numbers ("Version 1.4.5.6" for example). And it is
--   very useful to be able to compare these ranges to one another. This
--   module exists for the purpose of allowing these comparisons between
--   nested ranges. The module builds upon the basic range concept from
--   other parts of this library.
module Data.Range.NestedRange

-- | The Nested Range is a structure that in a nested form of many ranges
--   where there can be multiple ranges at every level.
data NestedRange a
NestedRange :: [[Range a]] -> NestedRange a

-- | Given a list of nested values and a nested range tell us wether the
--   nested value exists inside the nested range.
inNestedRange :: Ord a => [a] -> NestedRange a -> Bool


-- | It should not be unexpected that you will be given a string
--   representation of some ranges and you will need to parse them so that
--   you can then do some further processing. This parser exists in order
--   to make the most common forms of range strings easy to parse. It does
--   not cover all cases however but you should not be too worried about
--   that because you should be able to write your own parser using parsec
--   or Alex/Happy and then you can convert everything that you parse into
--   a RangeTree object for easier processing.
module Data.Range.Parser

-- | Given a string this function will either return a parse error back to
--   the user or the list of ranges that are represented by the parsed
--   string.
parseRanges :: Read a => String -> Either ParseError [Range a]

-- | Given the parser arguments this returns a parser that is capable of
--   parsing a list of ranges.
ranges :: Read a => RangeParserArgs -> Parser [Range a]

-- | The arguments that are used, and can be modified, while parsing a
--   standard range string.
data RangeParserArgs
Args :: String -> String -> String -> RangeParserArgs

-- | A separator that represents a union.
unionSeparator :: RangeParserArgs -> String

-- | A separator that separates the two halves of a range.
rangeSeparator :: RangeParserArgs -> String

-- | A separator that implies an unbounded range.
wildcardSymbol :: RangeParserArgs -> String

-- | These are the default arguments that are used by the parser. Please
--   feel free to use the default arguments for you own parser and modify
--   it from the defaults at will.
defaultArgs :: RangeParserArgs
instance Show RangeParserArgs