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


-- | GIS Vector Tiles, as defined by Mapbox.
--   
--   GIS Vector Tiles, as defined by Mapbox.
--   
--   This library implements version 2.1 of the official Mapbox spec, as
--   defined here:
--   <a>https://github.com/mapbox/vector-tile-spec/tree/master/2.1</a>
--   
--   Note that currently this library ignores top-level protobuf
--   extensions, <i>Value</i> extensions, and <i>UNKNOWN</i> geometries.
--   
--   The order in which to explore the modules of this library is as
--   follows:
--   
--   <ol>
--   <li><a>Geography.VectorTile.VectorTile</a> (high-level types)</li>
--   <li><a>Geography.VectorTile.Geometry</a> (typical GIS geometry
--   types)</li>
--   <li><a>Geography.VectorTile.Protobuf</a> (mid-level representation of
--   parsed protobuf data with conversion functions)</li>
--   </ol>
@package vectortiles
@version 1.2.0.5


module Geography.VectorTile.Util

-- | A sort of "self-zip", forming pairs from every two elements in a list.
--   Fails if there is an uneven number of elements.
pairs :: [a] -> Either Text [(a, a)]

-- | Flatten a list of pairs. Equivalent to:
--   
--   <pre>
--   ps ^.. each . both
--   </pre>
unpairs :: [(a, a)] -> [a]

-- | Apply a pure function to both elements of a tuple.
both :: (a -> b) -> (a, a) -> (b, b)

-- | Convert a <a>Maybe</a> to an <a>Either</a>, with some given default
--   value should the result of the <a>Maybe</a> be <a>Nothing</a>.
mtoe :: a -> Maybe b -> Either a b


module Geography.VectorTile.Geometry

-- | Points in space. Using "Record Pattern Synonyms" here allows us to
--   treat <a>Point</a> like a normal ADT, while its implementation remains
--   an unboxed <tt>(Int,Int)</tt>.
type Point = (Int, Int)
x :: (Int, Int) -> Int
y :: (Int, Int) -> Int

-- | <i>newtype</i> compiles away to expose only the <a>Vector</a> of
--   unboxed <a>Point</a>s at runtime.
newtype LineString
LineString :: Vector Point -> LineString
[lsPoints] :: LineString -> Vector Point

-- | A polygon aware of its interior rings.
data Polygon
Polygon :: Vector Point -> Vector Polygon -> Polygon
[polyPoints] :: Polygon -> Vector Point
[inner] :: Polygon -> Vector Polygon

-- | The area of a <a>Polygon</a> is the difference between the areas of
--   its outer ring and inner rings.
area :: Polygon -> Float

-- | The surveyor's formula for calculating the area of a <a>Polygon</a>.
--   If the value reported here is negative, then the <a>Polygon</a> should
--   be considered an Interior Ring.
--   
--   Assumption: The <a>Vector</a> given has at least 4 <a>Point</a>s.
surveyor :: Vector Point -> Float

-- | Euclidean distance.
distance :: Point -> Point -> Float
instance GHC.Generics.Generic Geography.VectorTile.Geometry.Polygon
instance GHC.Show.Show Geography.VectorTile.Geometry.Polygon
instance GHC.Classes.Eq Geography.VectorTile.Geometry.Polygon
instance GHC.Generics.Generic Geography.VectorTile.Geometry.LineString
instance GHC.Show.Show Geography.VectorTile.Geometry.LineString
instance GHC.Classes.Eq Geography.VectorTile.Geometry.LineString
instance Control.DeepSeq.NFData Geography.VectorTile.Geometry.LineString
instance Control.DeepSeq.NFData Geography.VectorTile.Geometry.Polygon


-- | High-level types for representing Vector Tiles.
module Geography.VectorTile.VectorTile

-- | A high-level representation of a Vector Tile. Implemented internally
--   as a <a>Map</a>, so that access to individual layers can be fast if
--   you know the layer names ahead of time.
newtype VectorTile
VectorTile :: Map Text Layer -> VectorTile
[_layers] :: VectorTile -> Map Text Layer

-- | A layer, which could contain any number of <a>Feature</a>s of any
--   <tt>Geometry</tt> type. This codec only respects the canonical three
--   <tt>Geometry</tt> types, and we split them here explicitely to allow
--   for more fine-grained access to each type.
data Layer
Layer :: Int -> Text -> Vector (Feature Point) -> Vector (Feature LineString) -> Vector (Feature Polygon) -> Int -> Layer

-- | The version of the spec we follow. Should always be 2.
[_version] :: Layer -> Int
[_name] :: Layer -> Text
[_points] :: Layer -> Vector (Feature Point)
[_linestrings] :: Layer -> Vector (Feature LineString)
[_polygons] :: Layer -> Vector (Feature Polygon)

-- | Default: 4096
[_extent] :: Layer -> Int

-- | A geographic feature. Features are a set of geometries that share some
--   common theme:
--   
--   <ul>
--   <li>Points: schools, gas station locations, etc.</li>
--   <li>LineStrings: Roads, power lines, rivers, etc.</li>
--   <li>Polygons: Buildings, water bodies, etc.</li>
--   </ul>
--   
--   Where, for instance, all school locations may be stored as a single
--   <a>Feature</a>, and no <a>Point</a> within that <a>Feature</a> would
--   represent anything else.
--   
--   Note: Each <tt>Geometry</tt> type and their <i>Multi*</i> counterpart
--   are considered the same thing, as a <a>Vector</a> of that
--   <tt>Geometry</tt>.
data Feature g
Feature :: Int -> Map Text Val -> Vector g -> Feature g

-- | Default: 0
[_featureId] :: Feature g -> Int
[_metadata] :: Feature g -> Map Text Val
[_geometries] :: Feature g -> Vector g

-- | Legal Metadata <i>Value</i> types. Note that <a>S64</a> are Z-encoded
--   automatically by the underlying <a>Data.ProtocolBuffers</a> library.
data Val
St :: Text -> Val
Fl :: Float -> Val
Do :: Double -> Val
I64 :: Int64 -> Val
W64 :: Word64 -> Val
S64 :: Int64 -> Val
B :: Bool -> Val

-- | <pre>
--   Lens' VectorTile (Map Text Layer)
--   </pre>
layers :: Functor f => (Map Text Layer -> f (Map Text Layer)) -> VectorTile -> f VectorTile

-- | <pre>
--   Lens' Layer Int
--   </pre>
version :: Functor f => (Int -> f Int) -> Layer -> f Layer

-- | <pre>
--   Lens' Layer Text
--   </pre>
name :: Functor f => (Text -> f Text) -> Layer -> f Layer

-- | <pre>
--   Lens' Layer (Vector (Feature Point))
--   </pre>
points :: Functor f => (Vector (Feature Point) -> f (Vector (Feature Point))) -> Layer -> f Layer

-- | <pre>
--   Lens' Layer (Vector (Feature LineString)))
--   </pre>
linestrings :: Functor f => (Vector (Feature LineString) -> f (Vector (Feature LineString))) -> Layer -> f Layer

-- | <pre>
--   Lens' Layer (Vector (Feature Polygon)))
--   </pre>
polygons :: Functor f => (Vector (Feature Polygon) -> f (Vector (Feature Polygon))) -> Layer -> f Layer

-- | <pre>
--   Lens' Layer Int
--   </pre>
extent :: Functor f => (Int -> f Int) -> Layer -> f Layer

-- | <pre>
--   Lens' (Feature g) Int
--   </pre>
featureId :: Functor f => (Int -> f Int) -> Feature g -> f (Feature g)

-- | <pre>
--   Lens' (Feature g) (Map Text Val)
--   </pre>
metadata :: Functor f => (Map Text Val -> f (Map Text Val)) -> Feature g -> f (Feature g)

-- | <pre>
--   Lens' (Feature g) (Vector g)
--   </pre>
geometries :: Functor f => (Vector g -> f (Vector g)) -> Feature g -> f (Feature g)
instance GHC.Generics.Generic Geography.VectorTile.VectorTile.VectorTile
instance GHC.Show.Show Geography.VectorTile.VectorTile.VectorTile
instance GHC.Classes.Eq Geography.VectorTile.VectorTile.VectorTile
instance GHC.Generics.Generic Geography.VectorTile.VectorTile.Layer
instance GHC.Show.Show Geography.VectorTile.VectorTile.Layer
instance GHC.Classes.Eq Geography.VectorTile.VectorTile.Layer
instance GHC.Generics.Generic (Geography.VectorTile.VectorTile.Feature g)
instance GHC.Show.Show g => GHC.Show.Show (Geography.VectorTile.VectorTile.Feature g)
instance GHC.Classes.Eq g => GHC.Classes.Eq (Geography.VectorTile.VectorTile.Feature g)
instance GHC.Generics.Generic Geography.VectorTile.VectorTile.Val
instance GHC.Show.Show Geography.VectorTile.VectorTile.Val
instance GHC.Classes.Ord Geography.VectorTile.VectorTile.Val
instance GHC.Classes.Eq Geography.VectorTile.VectorTile.Val
instance Control.DeepSeq.NFData Geography.VectorTile.VectorTile.VectorTile
instance Control.DeepSeq.NFData Geography.VectorTile.VectorTile.Layer
instance Control.DeepSeq.NFData g => Control.DeepSeq.NFData (Geography.VectorTile.VectorTile.Feature g)
instance Control.DeepSeq.NFData Geography.VectorTile.VectorTile.Val


-- | Raw Vector Tile data is stored as binary protobuf data. This module
--   reads and writes raw protobuf ByteStrings between a data type which
--   closely matches the current Mapbox vector tile spec defined here:
--   <a>https://github.com/mapbox/vector-tile-spec/blob/master/2.1/vector_tile.proto</a>
--   
--   As this raw version of the data is hard to work with, in practice we
--   convert to a more canonical Haskell type for further processing. See
--   <a>Geography.VectorTile.VectorTile</a> for the user-friendly version.
--   
--   Please import this module <tt>qualified</tt> to avoid namespace
--   clashes:
--   
--   <pre>
--   import qualified Geography.VectorTile.Protobuf.Internal as PB
--   </pre>
module Geography.VectorTile.Protobuf.Internal

-- | A family of data types which can associated with concrete underlying
--   Protobuf types.

-- | A type which can be converted to and from an underlying Protobuf type,
--   according to the <a>Protobuf</a> type family.
class Protobuffable a
fromProtobuf :: Protobuffable a => Protobuf a -> Either Text a
toProtobuf :: Protobuffable a => a -> Protobuf a

-- | Any classical type considered a GIS "geometry". These must be able to
--   convert between an encodable list of <a>Command</a>s.
class ProtobufGeom g
fromCommands :: ProtobufGeom g => [Command] -> Either Text (Vector g)
toCommands :: ProtobufGeom g => Vector g -> [Command]

-- | A list of <a>RawLayer</a>s.
data RawVectorTile
RawVectorTile :: Repeated 3 (Message RawLayer) -> RawVectorTile
[_layers] :: RawVectorTile -> Repeated 3 (Message RawLayer)

-- | Contains a pseudo-map of metadata, to be shared across all
--   <a>RawFeature</a>s of this <a>RawLayer</a>.
data RawLayer
RawLayer :: Required 15 (Value Word32) -> Required 1 (Value Text) -> Repeated 2 (Message RawFeature) -> Repeated 3 (Value Text) -> Repeated 4 (Message RawVal) -> Optional 5 (Value Word32) -> RawLayer
[_version] :: RawLayer -> Required 15 (Value Word32)
[_name] :: RawLayer -> Required 1 (Value Text)
[_features] :: RawLayer -> Repeated 2 (Message RawFeature)
[_keys] :: RawLayer -> Repeated 3 (Value Text)
[_values] :: RawLayer -> Repeated 4 (Message RawVal)
[_extent] :: RawLayer -> Optional 5 (Value Word32)

-- | The <i>Value</i> types of metadata fields.
data RawVal
RawVal :: Optional 1 (Value Text) -> Optional 2 (Value Float) -> Optional 3 (Value Double) -> Optional 4 (Value Int64) -> Optional 5 (Value Word64) -> Optional 6 (Value (Signed Int64)) -> Optional 7 (Value Bool) -> RawVal
[_string] :: RawVal -> Optional 1 (Value Text)
[_float] :: RawVal -> Optional 2 (Value Float)
[_double] :: RawVal -> Optional 3 (Value Double)
[_int64] :: RawVal -> Optional 4 (Value Int64)
[_uint64] :: RawVal -> Optional 5 (Value Word64)

-- | Z-encoded.
[_sint] :: RawVal -> Optional 6 (Value (Signed Int64))
[_bool] :: RawVal -> Optional 7 (Value Bool)

-- | A set of geometries unified by some theme.
data RawFeature
RawFeature :: Optional 1 (Value Word64) -> Packed 2 (Value Word32) -> Optional 3 (Enumeration GeomType) -> Packed 4 (Value Word32) -> RawFeature
[_featureId] :: RawFeature -> Optional 1 (Value Word64)
[_tags] :: RawFeature -> Packed 2 (Value Word32)
[_geom] :: RawFeature -> Optional 3 (Enumeration GeomType)
[_geometries] :: RawFeature -> Packed 4 (Value Word32)

-- | The four potential Geometry types. The spec allows for encoders to set
--   <a>Unknown</a> as the type, but our decoder ignores these.
data GeomType
Unknown :: GeomType
Point :: GeomType
LineString :: GeomType
Polygon :: GeomType

-- | The possible commands, and the values they hold.
data Command
MoveTo :: (Vector (Int, Int)) -> Command
LineTo :: (Vector (Int, Int)) -> Command
ClosePath :: Command

-- | Attempt to parse a list of Command/Parameter integers, as defined
--   here:
--   
--   
--   <a>https://github.com/mapbox/vector-tile-spec/tree/master/2.1#43-geometry-encoding</a>
commands :: [Word32] -> Either Text [Command]

-- | Convert a list of parsed <a>Command</a>s back into their original
--   Command and Z-encoded Parameter integer forms.
uncommands :: [Command] -> [Word32]

-- | Z-encode a 64-bit Int.
zig :: Int -> Word32

-- | Decode a Z-encoded Word32 into a 64-bit Int.
unzig :: Word32 -> Int

-- | Convert a list of <a>RawFeature</a>s of parsed protobuf data into
--   <a>Vector</a>s of each of the three legal <a>ProtobufGeom</a> types.
--   
--   The long type signature is due to two things:
--   
--   <ol>
--   <li><tt>Feature</tt>s are polymorphic at the high level, but not at
--   the parsed protobuf mid-level. In a <tt>[RawFeature]</tt>, there are
--   features of points, linestrings, and polygons all mixed together.</li>
--   <li><a>RawLayer</a>s and <a>RawFeature</a>s are strongly coupled at
--   the protobuf level. In order to achieve higher compression ratios,
--   <a>RawLayer</a>s contain all metadata in key/value lists to be shared
--   across their <a>RawFeature</a>s, while those <a>RawFeature</a>s store
--   only indices into those lists. As a result, this function needs to be
--   passed those key/value lists from the parent <a>RawLayer</a>, and a
--   more isomorphic:</li>
--   </ol>
--   
--   <pre>
--   feature :: ProtobufGeom g =&gt; RawFeature -&gt; Either Text (Feature g)
--   </pre>
--   
--   is not possible.
features :: [Text] -> [RawVal] -> [RawFeature] -> Either Text (Vector (Feature Point), Vector (Feature LineString), Vector (Feature Polygon))

-- | Encode a high-level <tt>Feature</tt> back into its mid-level
--   <a>RawFeature</a> form.
unfeature :: ProtobufGeom g => Map Text Int -> Map Val Int -> GeomType -> Feature g -> RawFeature
instance GHC.Show.Show Geography.VectorTile.Protobuf.Internal.Command
instance GHC.Classes.Eq Geography.VectorTile.Protobuf.Internal.Command
instance GHC.Classes.Eq Geography.VectorTile.Protobuf.Internal.RawVectorTile
instance GHC.Show.Show Geography.VectorTile.Protobuf.Internal.RawVectorTile
instance GHC.Generics.Generic Geography.VectorTile.Protobuf.Internal.RawVectorTile
instance GHC.Classes.Eq Geography.VectorTile.Protobuf.Internal.RawLayer
instance GHC.Show.Show Geography.VectorTile.Protobuf.Internal.RawLayer
instance GHC.Generics.Generic Geography.VectorTile.Protobuf.Internal.RawLayer
instance GHC.Classes.Eq Geography.VectorTile.Protobuf.Internal.RawFeature
instance GHC.Show.Show Geography.VectorTile.Protobuf.Internal.RawFeature
instance GHC.Generics.Generic Geography.VectorTile.Protobuf.Internal.RawFeature
instance GHC.Classes.Eq Geography.VectorTile.Protobuf.Internal.GeomType
instance GHC.Show.Show Geography.VectorTile.Protobuf.Internal.GeomType
instance GHC.Enum.Enum Geography.VectorTile.Protobuf.Internal.GeomType
instance GHC.Generics.Generic Geography.VectorTile.Protobuf.Internal.GeomType
instance GHC.Classes.Eq Geography.VectorTile.Protobuf.Internal.RawVal
instance GHC.Show.Show Geography.VectorTile.Protobuf.Internal.RawVal
instance GHC.Generics.Generic Geography.VectorTile.Protobuf.Internal.RawVal
instance Geography.VectorTile.Protobuf.Internal.Protobuffable Geography.VectorTile.VectorTile.VectorTile
instance Geography.VectorTile.Protobuf.Internal.Protobuffable Geography.VectorTile.VectorTile.Layer
instance Geography.VectorTile.Protobuf.Internal.Protobuffable Geography.VectorTile.VectorTile.Val
instance Data.ProtocolBuffers.Encode.Encode Geography.VectorTile.Protobuf.Internal.RawVectorTile
instance Data.ProtocolBuffers.Decode.Decode Geography.VectorTile.Protobuf.Internal.RawVectorTile
instance Control.DeepSeq.NFData Geography.VectorTile.Protobuf.Internal.RawVectorTile
instance Data.ProtocolBuffers.Encode.Encode Geography.VectorTile.Protobuf.Internal.RawLayer
instance Data.ProtocolBuffers.Decode.Decode Geography.VectorTile.Protobuf.Internal.RawLayer
instance Control.DeepSeq.NFData Geography.VectorTile.Protobuf.Internal.RawLayer
instance Data.ProtocolBuffers.Encode.Encode Geography.VectorTile.Protobuf.Internal.RawVal
instance Data.ProtocolBuffers.Decode.Decode Geography.VectorTile.Protobuf.Internal.RawVal
instance Control.DeepSeq.NFData Geography.VectorTile.Protobuf.Internal.RawVal
instance Data.ProtocolBuffers.Encode.Encode Geography.VectorTile.Protobuf.Internal.RawFeature
instance Data.ProtocolBuffers.Decode.Decode Geography.VectorTile.Protobuf.Internal.RawFeature
instance Control.DeepSeq.NFData Geography.VectorTile.Protobuf.Internal.RawFeature
instance Data.ProtocolBuffers.Encode.Encode Geography.VectorTile.Protobuf.Internal.GeomType
instance Data.ProtocolBuffers.Decode.Decode Geography.VectorTile.Protobuf.Internal.GeomType
instance Control.DeepSeq.NFData Geography.VectorTile.Protobuf.Internal.GeomType
instance Geography.VectorTile.Protobuf.Internal.ProtobufGeom Geography.VectorTile.Geometry.Point
instance Geography.VectorTile.Protobuf.Internal.ProtobufGeom Geography.VectorTile.Geometry.LineString
instance Geography.VectorTile.Protobuf.Internal.ProtobufGeom Geography.VectorTile.Geometry.Polygon


-- | Most of the details of Protobuf conversion are kept in
--   <a>Geometry.VectorTile.Protobuf.Internal</a>, a module which is not
--   intended to be imported.
--   
--   A user's main concern here should be the <a>Protobuffable</a> class,
--   and its <tt>VectorTile</tt> instance. With it, one can do the
--   following:
--   
--   <pre>
--   import Geography.VectorTile.Protobuf
--   
--   decode bytes &gt;&gt;= fromProtobuf  -- Either Text VectorTile
--   </pre>
--   
--   which in fact is sugared in the top-level module of this library as:
--   
--   <pre>
--   decode bytes &gt;&gt;= tile
--   </pre>
module Geography.VectorTile.Protobuf

-- | A type which can be converted to and from an underlying Protobuf type,
--   according to the <a>Protobuf</a> type family.
class Protobuffable a
fromProtobuf :: Protobuffable a => Protobuf a -> Either Text a
toProtobuf :: Protobuffable a => a -> Protobuf a

-- | Attempt to decode a <a>ByteString</a> of raw protobuf data into a
--   mid-level representation of a <a>RawVectorTile</a>.
decode :: ByteString -> Either Text RawVectorTile

-- | Encode a mid-level representation of a <a>RawVectorTile</a> into raw
--   protobuf data.
encode :: RawVectorTile -> ByteString

-- | Given a filename, attempt to decode bytes read from that file.
decodeIO :: FilePath -> IO (Either Text RawVectorTile)

-- | Write a mid-level representation of a <a>RawVectorTile</a> to a file
--   as raw protobuf data.
encodeIO :: RawVectorTile -> FilePath -> IO ()


-- | GIS Vector Tiles, as defined by Mapbox.
--   
--   This library implements version 2.1 of the official Mapbox spec, as
--   defined here:
--   <a>https://github.com/mapbox/vector-tile-spec/tree/master/2.1</a>
--   
--   Note that currently this library ignores top-level protobuf
--   extensions, <i>Value</i> extensions, and <i>UNKNOWN</i> geometries.
--   
--   The order in which to explore the modules of this library is as
--   follows:
--   
--   <ol>
--   <li><a>Geography.VectorTile.VectorTile</a></li>
--   <li><a>Geography.VectorTile.Geometry</a></li>
--   <li><a>Geography.VectorTile.Protobuf</a></li>
--   </ol>
--   
--   <h2>Usage</h2>
--   
--   This library reads and writes strict <tt>ByteString</tt>s. By
--   importing this module, you use the default protobuf backend. Given
--   some legal VectorTile file called <tt>roads.mvt</tt>:
--   
--   <pre>
--   import qualified Data.ByteString as BS
--   import           Data.Text (Text)
--   import           Geography.VectorTile
--   
--   -- | Read in raw protobuf data and decode it into a high-level type.
--   roads :: IO (Either Text VectorTile)
--   roads = do
--     mvt &lt;- BS.readFile "roads.mvt"
--     pure $ decode mvt &gt;&gt;= tile
--   </pre>
--   
--   Or encode a <a>VectorTile</a> back into a <tt>ByteString</tt>:
--   
--   <pre>
--   roadsBytes :: VectorTile -&gt; BS.ByteString
--   roadsBytes = encode . untile
--   </pre>
module Geography.VectorTile
tile :: RawVectorTile -> Either Text VectorTile
untile :: VectorTile -> RawVectorTile

-- | Attempt to decode a <a>ByteString</a> of raw protobuf data into a
--   mid-level representation of a <a>RawVectorTile</a>.
decode :: ByteString -> Either Text RawVectorTile

-- | Encode a mid-level representation of a <a>RawVectorTile</a> into raw
--   protobuf data.
encode :: RawVectorTile -> ByteString
