diff --git a/Changelog.md b/Changelog.md --- a/Changelog.md +++ b/Changelog.md @@ -1,5 +1,10 @@ # Change log for esqueleto-postgis project +## Version 2.0.0 +* Hide irrelevant modules +* delete hex module, use base16 hex approach instead. +* Much better docs that explain what's going on. + ## Version 1.2.0 + re-export point, less annoying to use. + adopt wkt-geom package and put it in as a submodule, diff --git a/esqueleto-postgis.cabal b/esqueleto-postgis.cabal --- a/esqueleto-postgis.cabal +++ b/esqueleto-postgis.cabal @@ -5,7 +5,7 @@ -- see: https://github.com/sol/hpack name: esqueleto-postgis -version: 1.2.0 +version: 2.0.0 homepage: https://github.com/jappeace/esqueleto-postgis#readme bug-reports: https://github.com/jappeace/esqueleto-postgis/issues author: Jappie Klooster @@ -64,7 +64,7 @@ esqueleto >= 3.5.10 && < 3.7, text >= 1.2.5 && < 2.2, persistent >= 2.13.3 && < 2.19, - geojson >= 4.1.0 && < 4.2, + geojson >= 4.1.1 && < 4.2, bytestring < 2, base16 >= 1.0 && < 1.1, binary < 1, @@ -77,16 +77,16 @@ exposed-modules: Database.Esqueleto.Postgis Database.Esqueleto.Postgis.Ewkb - Database.Esqueleto.Postgis.Hex - Database.Esqueleto.Postgis.Ewkb.Geometry + Database.Esqueleto.Postgis.Wkb + other-modules: Database.Esqueleto.Postgis.Wkb.Endian + Database.Esqueleto.Postgis.Wkb.Point Database.Esqueleto.Postgis.Wkb.Geometry + Database.Esqueleto.Postgis.Ewkb.Geometry Database.Esqueleto.Postgis.Wkb.GeometryCollection - Database.Esqueleto.Postgis.Wkb.Geospatial Database.Esqueleto.Postgis.Wkb.Line - Database.Esqueleto.Postgis.Wkb.Point Database.Esqueleto.Postgis.Wkb.Polygon - Database.Esqueleto.Postgis.Wkb + Database.Esqueleto.Postgis.Wkb.Geospatial hs-source-dirs: src @@ -104,7 +104,6 @@ Wkb.EndianSpec Wkb.GeometryCollectionSpec Wkb.GeometrySpec - Wkb.HexParsingSpec Wkb.LineSpec Wkb.PointSpec Wkb.PolygonSpec diff --git a/src/Database/Esqueleto/Postgis.hs b/src/Database/Esqueleto/Postgis.hs --- a/src/Database/Esqueleto/Postgis.hs +++ b/src/Database/Esqueleto/Postgis.hs @@ -32,7 +32,6 @@ import Data.Foldable (Foldable (toList), fold) import Data.Geospatial (GeoPoint (..), GeoPositionWithoutCRS (..), GeospatialGeometry, PointXY (..), PointXYZ (..), PointXYZM (..)) import Data.Geospatial qualified as Geospatial -import Database.Esqueleto.Postgis.Hex (Hex (..)) import Data.LineString (LineString, fromLineString, lineStringHead) import Data.LinearRing (LinearRing, fromLinearRing, makeLinearRing, ringHead, toSeq) import Data.List qualified as List @@ -49,6 +48,8 @@ import Database.Esqueleto.Experimental (SqlExpr, Value) import Database.Esqueleto.Internal.Internal (unsafeSqlFunction) import Database.Persist.Sql +import Data.Base16.Types(assertBase16) +import Data.ByteString(fromStrict) -- | unwrap postgis geometry so you can for example return it from an API getPoints :: PostgisGeometry point -> NonEmpty point @@ -205,7 +206,7 @@ toPersistValue geom = PersistText $ toStrict $ toLazyText $ renderGeometry $ renderPair <$> geom fromPersistValue (PersistLiteral_ Escaped bs) = do - result <- first pack $ parseHexByteString (Hex bs) + result <- first pack $ parseHexByteString $ assertBase16 $ fromStrict bs first tshow $ (from2dGeospatialGeometry from2dGeoPositionWithoutCRSToPoint) result fromPersistValue other = Left ("PersistField.Polygon: invalid persist value:" <> tshow other) @@ -213,7 +214,7 @@ toPersistValue geom = PersistText $ toStrict $ toLazyText $ renderGeometry $ renderXYZ <$> geom fromPersistValue (PersistLiteral_ Escaped bs) = do - result <- first pack $ parseHexByteString (Hex bs) + result <- first pack $ parseHexByteString $ assertBase16 $ fromStrict bs first tshow $ (from2dGeospatialGeometry from3dGeoPositionWithoutCRSToPoint) result fromPersistValue other = Left ("PersistField.Polygon: invalid persist value:" <> tshow other) @@ -221,7 +222,7 @@ toPersistValue geom = PersistText $ toStrict $ toLazyText $ renderGeometry $ renderXYZM <$> geom fromPersistValue (PersistLiteral_ Escaped bs) = do - result <- first pack $ parseHexByteString (Hex bs) + result <- first pack $ parseHexByteString $ assertBase16 $ fromStrict bs first tshow $ (from2dGeospatialGeometry from4dGeoPositionWithoutCRSToPoint) result fromPersistValue other = Left ("PersistField.Polygon: invalid persist value:" <> tshow other) diff --git a/src/Database/Esqueleto/Postgis/Ewkb.hs b/src/Database/Esqueleto/Postgis/Ewkb.hs --- a/src/Database/Esqueleto/Postgis/Ewkb.hs +++ b/src/Database/Esqueleto/Postgis/Ewkb.hs @@ -1,4 +1,4 @@ --- | I copied these because the original libraryy doesn't +-- I copied these because the original libraryy doesn't -- appear to be maintained. -- I'm only interested in this parseHexBytestring function. -- @@ -7,27 +7,33 @@ -- Apache license -- -- --- Refer to the eWKB Postgis Documentation +-- | Ewkb is the basis for postgis in postgres. +-- This module Allows parsing of ByteString into a Geospatial Object. -- --- Allows parsing of ByteString into a Geospatial Object. +-- These functions are used in the instance 'Database.Persist.Class.PersistField' instance +-- to parse the database base16 output into types we can use. -- -------------------------------------------------------------------- +-- Refer to the eWKB Postgis Documentation +-- module Database.Esqueleto.Postgis.Ewkb ( parseByteString , parseHexByteString , toByteString + -- * Core + -- | the greasy gears inside for experienced users or the brave! + , module EwkbGeometry ) where import qualified Data.Binary.Get as BinaryGet import qualified Data.ByteString.Builder as ByteStringBuilder import qualified Data.ByteString.Lazy as LazyByteString import qualified Data.Geospatial as Geospatial -import qualified Database.Esqueleto.Postgis.Hex as Hex -import qualified Database.Esqueleto.Postgis.Ewkb.Geometry as EwkbGeometry +import Database.Esqueleto.Postgis.Ewkb.Geometry as EwkbGeometry import qualified Database.Esqueleto.Postgis.Wkb.Endian as Endian import qualified Database.Esqueleto.Postgis.Wkb.Geospatial as WkbGeospatial - +import Data.ByteString.Lazy.Base16(decodeBase16) +import Data.Base16.Types(Base16) -- | -- Representation of EWKB as Binary parseByteString :: LazyByteString.ByteString -> Either String Geospatial.GeospatialGeometry @@ -40,8 +46,8 @@ -- | -- Representation of EWKB as a String in Base16/Hex form i.e. "0101000000000000000000f03f0000000000000040" is POINT 1.0 2.0 -parseHexByteString :: Hex.Hex -> Either String Geospatial.GeospatialGeometry -parseHexByteString = Hex.safeConvert parseByteString +parseHexByteString :: Base16 LazyByteString.ByteString -> Either String Geospatial.GeospatialGeometry +parseHexByteString = parseByteString . decodeBase16 -- | -- Produce the binary representation of EWKB given its EndianType (Little or Big - Intel is Little) and SRID (4326 for example). diff --git a/src/Database/Esqueleto/Postgis/Hex.hs b/src/Database/Esqueleto/Postgis/Hex.hs deleted file mode 100644 --- a/src/Database/Esqueleto/Postgis/Hex.hs +++ /dev/null @@ -1,23 +0,0 @@ - --- | friendly copied from github.com/zellige/wkt-geom.git --- Copyright 2017-2018 wkt-geom Project --- Apache license -module Database.Esqueleto.Postgis.Hex - ( safeConvert - , Hex(..) - ) where - -import qualified Data.ByteString as ByteString -import qualified Data.ByteString.Base16 as ByteStringBase16 -import qualified Data.ByteString.Char8 as ByteStringChar8 -import qualified Data.ByteString.Lazy as LazyByteString -import qualified Data.Geospatial as Geospatial - -newtype Hex = Hex ByteString.ByteString - -safeConvert :: (LazyByteString.ByteString -> Either String Geospatial.GeospatialGeometry) -> Hex -> Either String Geospatial.GeospatialGeometry -safeConvert f (Hex byteString) = - case ByteStringBase16.decodeBase16Untyped byteString of - Left _ -> Left $ "Invalid hex representation: " <> ByteStringChar8.unpack byteString - Right decoded -> f $ LazyByteString.fromStrict decoded - diff --git a/src/Database/Esqueleto/Postgis/Wkb.hs b/src/Database/Esqueleto/Postgis/Wkb.hs --- a/src/Database/Esqueleto/Postgis/Wkb.hs +++ b/src/Database/Esqueleto/Postgis/Wkb.hs @@ -1,23 +1,36 @@ --- Refer to the WKB Wikipedia page +-- | Ewkb is deeply integrated into Wkb, which is why we kept this around. +-- For postgis we mostly want Ewkb. -- --- Allows parsing of ByteString into a Geospatial Object. +-- This module Allows parsing of ByteString into a Geospatial Object, +-- and provides foundational elements for constructing an Ewkb. -- -------------------------------------------------------------------- +-- Refer to the WKB Wikipedia page module Database.Esqueleto.Postgis.Wkb ( parseByteString , parseHexByteString , toByteString + -- * Core + -- | the greasy gears inside for experienced users or the brave! + + -- ** Geometry + , module Geometry + -- ** Endian + , module Endian + -- ** Point + , module Point ) where import qualified Data.Binary.Get as BinaryGet import qualified Data.ByteString.Builder as ByteStringBuilder import qualified Data.ByteString.Lazy as LazyByteString import qualified Data.Geospatial as Geospatial -import qualified Database.Esqueleto.Postgis.Hex as Hex -import qualified Database.Esqueleto.Postgis.Wkb.Endian as Endian -import qualified Database.Esqueleto.Postgis.Wkb.Geometry as Geometry +import Database.Esqueleto.Postgis.Wkb.Endian as Endian +import Database.Esqueleto.Postgis.Wkb.Geometry as Geometry +import Database.Esqueleto.Postgis.Wkb.Point as Point import qualified Database.Esqueleto.Postgis.Wkb.Geospatial as WkbGeospatial +import Data.ByteString.Lazy.Base16(decodeBase16) +import Data.Base16.Types(Base16) -- | -- Representation of WKB as Binary @@ -31,8 +44,8 @@ -- | -- Representation of WKB as a String in Base16/Hex form i.e. "0101000000000000000000f03f0000000000000040" is POINT 1.0 2.0 -parseHexByteString :: Hex.Hex -> Either String Geospatial.GeospatialGeometry -parseHexByteString = Hex.safeConvert parseByteString +parseHexByteString :: Base16 LazyByteString.ByteString -> Either String Geospatial.GeospatialGeometry +parseHexByteString = parseByteString . decodeBase16 -- | -- Produce the binary representation of WKB given its EndianType (Little or Big - Intel is Little). Use EWKB when you know the SRID. diff --git a/test/Data/SpecHelper.hs b/test/Data/SpecHelper.hs --- a/test/Data/SpecHelper.hs +++ b/test/Data/SpecHelper.hs @@ -12,9 +12,8 @@ import Test.Hspec (Spec, it) import qualified Database.Esqueleto.Postgis.Ewkb as Ewkb -import qualified Database.Esqueleto.Postgis.Ewkb.Geometry as EwkbGeometry -import qualified Database.Esqueleto.Postgis.Wkb.Endian as Endian -import qualified Database.Esqueleto.Postgis.Wkb.Geometry as Geometry +import qualified Database.Esqueleto.Postgis.Wkb as Endian +import qualified Database.Esqueleto.Postgis.Wkb as Geometry import qualified Database.Esqueleto.Postgis.Wkb as Wkb -- Helpers @@ -47,7 +46,7 @@ roundTripEwkb :: MonadTest m => Endian.EndianType -> Geospatial.GeospatialGeometry -> m () roundTripEwkb endianType geometry = let - p = Ewkb.parseByteString . Ewkb.toByteString endianType (EwkbGeometry.Srid (4326 :: Word.Word32)) + p = Ewkb.parseByteString . Ewkb.toByteString endianType (Ewkb.Srid (4326 :: Word.Word32)) in p geometry === Right geometry diff --git a/test/Ewkb/GeometrySpec.hs b/test/Ewkb/GeometrySpec.hs --- a/test/Ewkb/GeometrySpec.hs +++ b/test/Ewkb/GeometrySpec.hs @@ -7,9 +7,9 @@ import qualified Data.Word as Word import Test.Hspec (Spec, describe, it, shouldBe) -import qualified Database.Esqueleto.Postgis.Ewkb.Geometry as Ewkb -import qualified Database.Esqueleto.Postgis.Wkb.Endian as Endian -import qualified Database.Esqueleto.Postgis.Wkb.Geometry as Wkb +import qualified Database.Esqueleto.Postgis.Ewkb as Ewkb +import qualified Database.Esqueleto.Postgis.Wkb as Endian +import qualified Database.Esqueleto.Postgis.Wkb as Wkb spec :: Spec spec = diff --git a/test/Test.hs b/test/Test.hs --- a/test/Test.hs +++ b/test/Test.hs @@ -55,7 +55,6 @@ import qualified Wkb.EndianSpec import qualified Wkb.GeometryCollectionSpec import qualified Wkb.GeometrySpec -import qualified Wkb.HexParsingSpec import qualified Wkb.LineSpec import qualified Wkb.PointSpec import qualified Wkb.PolygonSpec @@ -114,7 +113,6 @@ testSpec "Wkb.EndianSpec" Wkb.EndianSpec.spec, testSpec "Wkb.GeometryCollectionSpec" Wkb.GeometryCollectionSpec.spec, testSpec "Wkb.GeometrySpec" Wkb.GeometrySpec.spec, - testSpec "Wkb.HexParsingSpec" Wkb.HexParsingSpec.spec, testSpec "Wkb.LineSpec" Wkb.LineSpec.spec, testSpec "Wkb.PointSpec" Wkb.PointSpec.spec, testSpec "Wkb.PolygonSpec" Wkb.PolygonSpec.spec diff --git a/test/Wkb/EndianSpec.hs b/test/Wkb/EndianSpec.hs --- a/test/Wkb/EndianSpec.hs +++ b/test/Wkb/EndianSpec.hs @@ -6,7 +6,7 @@ import qualified Data.ByteString.Builder as ByteStringBuilder import Test.Hspec (Spec, describe, it, shouldBe) -import qualified Database.Esqueleto.Postgis.Wkb.Endian as Endian +import qualified Database.Esqueleto.Postgis.Wkb as Endian spec :: Spec spec = diff --git a/test/Wkb/GeometrySpec.hs b/test/Wkb/GeometrySpec.hs --- a/test/Wkb/GeometrySpec.hs +++ b/test/Wkb/GeometrySpec.hs @@ -6,8 +6,8 @@ import qualified Data.ByteString.Builder as ByteStringBuilder import Test.Hspec (Spec, describe, it, shouldBe) -import qualified Database.Esqueleto.Postgis.Wkb.Endian as Endian -import qualified Database.Esqueleto.Postgis.Wkb.Geometry as Geometry +import qualified Database.Esqueleto.Postgis.Wkb as Endian +import qualified Database.Esqueleto.Postgis.Wkb as Geometry spec :: Spec spec = diff --git a/test/Wkb/HexParsingSpec.hs b/test/Wkb/HexParsingSpec.hs deleted file mode 100644 --- a/test/Wkb/HexParsingSpec.hs +++ /dev/null @@ -1,31 +0,0 @@ -{-# LANGUAGE OverloadedStrings #-} - -module Wkb.HexParsingSpec where - -import qualified Data.Geospatial as Geospatial -import Test.Hspec (Spec, describe, it, shouldBe) - -import qualified Database.Esqueleto.Postgis.Hex as Hex -import qualified Database.Esqueleto.Postgis.Wkb as Wkb - -spec :: Spec -spec = - testWkbHexParsing - -testWkbHexParsing :: Spec -testWkbHexParsing = - describe "Test hex encoded wkb point" $ do - it "Parse valid hex wkb" $ - Wkb.parseHexByteString exampleHexPoint `shouldBe` Right expectedPoint - it "Not parse valid hex but invalid wkb" $ - Wkb.parseHexByteString (Hex.Hex "deadbeef") `shouldBe` Left "Could not parse wkb: Invalid EndianType" - it "Some valid, some invalid hex" $ - Wkb.parseHexByteString (Hex.Hex "deadfish") `shouldBe` Left "Invalid hex representation: deadfish" - it "All bad" $ - Wkb.parseHexByteString (Hex.Hex "cowboyx") `shouldBe` Left "Invalid hex representation: cowboyx" - -exampleHexPoint :: Hex.Hex -exampleHexPoint = Hex.Hex "0101000000000000000000f03f0000000000000040" - -expectedPoint :: Geospatial.GeospatialGeometry -expectedPoint = Geospatial.Point (Geospatial.GeoPoint (Geospatial.GeoPointXY (Geospatial.PointXY 1.0 2.0))) diff --git a/test/Wkb/PointSpec.hs b/test/Wkb/PointSpec.hs --- a/test/Wkb/PointSpec.hs +++ b/test/Wkb/PointSpec.hs @@ -9,8 +9,8 @@ import Hedgehog import Test.Hspec (Spec, describe, it) -import qualified Database.Esqueleto.Postgis.Wkb.Geometry as Geometry -import qualified Database.Esqueleto.Postgis.Wkb.Point as Point +import qualified Database.Esqueleto.Postgis.Wkb as Geometry +import qualified Database.Esqueleto.Postgis.Wkb as Point import qualified Data.SpecHelper as SpecHelper spec :: Spec