diff --git a/README.markdown b/README.markdown --- a/README.markdown +++ b/README.markdown @@ -4,5 +4,8 @@ Salve provides semantic version numbers and constraints for Haskell. +Salve has extensive documentation available on Hackage: +. + [Build badge]: https://travis-ci.org/tfausak/salve.svg?branch=master [build status]: https://travis-ci.org/tfausak/salve diff --git a/library/Salve.hs b/library/Salve.hs --- a/library/Salve.hs +++ b/library/Salve.hs @@ -24,11 +24,74 @@ -- >>> renderConstraint <$> parseConstraint ">1.2.0" -- Just ">1.2.0" -- --- Use 'satisfies' to see if a version satisfies a constraint. +-- Use 'satisfiesConstraint' to see if a version satisfiesConstraint a +-- constraint. -- --- >>> satisfies <$> parseVersion "1.2.3" <*> parseConstraint ">1.2.0" +-- >>> satisfiesConstraint <$> parseConstraint ">1.2.0" <*> parseVersion "1.2.3" -- Just True +-- * Rationale +-- | There are already a few modules that provide version numbers. Why do we +-- need another one? Let's take a look at the options. +-- +-- - +-- from the @base@ package: +-- +-- - Exposes constructors, which allows creating versions that cannot be +-- parsed. +-- - Allows any number of components, from zero to inifinity. +-- - Deprecated tags on versions. +-- - Does not support build metadata on versions. +-- - Does not support constraints. +-- +-- - +-- from the @Cabal@ package: +-- +-- - Has the same problems as Data.Version because it re-uses that +-- version type. +-- - Depends on the @array@, @binary@, @bytestring@, @containers@, +-- @deepseq@, @directory@, @filepath@, @pretty@, @process@, @time@, and +-- @unix@ packages. +-- +-- - +-- from the @semver@ package: +-- +-- - Depends on the @attoparsec@, @deepseq@, and @text@ packages. +-- - Does not support version constraints. +-- +-- - +-- from the @semver-range@ package: +-- +-- - Depends on the @classy-prelude@, @parsec@, @text@, and +-- @unordered-containers@ packages. +-- - Module name collides with the @semver@ package. +-- - Supports constraints, but does not provide a way to render them. +-- +-- - +-- from the @versions@ package: +-- +-- - Depends on the @deepseq@, @hashable@, @megaparsec@, and @text@ +-- packages. +-- - Intentially allows weird versions. +-- - Does not support constraints. +-- +-- By comparison, Salve: +-- +-- - Does not expose constructors. Any version you create can be rendered and +-- parsed without issue. +-- - Requires exactly three components. You won't have to wonder if version +-- @1.2.0@ is greater than @1.2@. +-- - Allows pre-release identifiers on versions. Go ahead and release version +-- @1.0.0-alpha@ for early adopters. +-- - Allows build metadata on versions. Show when a release was made with +-- versions like @1.0.0+2001-02-03@. +-- - Supports version constraints. Just like versions, rendering and parsing +-- constraints is no problem. +-- - Only depends on the @base@ package. You can use all the functionality +-- without installing any other packages. +-- - Has a unique module name. You won't have to use the @PackageImports@ +-- extension simply to deal with version numbers. + -- * Types Version, PreRelease, @@ -68,7 +131,7 @@ bumpMajor, bumpMinor, bumpPatch, -satisfies, +satisfiesConstraint, -- * Lenses -- | These lenses can be used to access and modify specific parts of a @@ -86,6 +149,9 @@ buildsLens, -- * Examples +-- | These examples are provided to showcase functionality and explain weird +-- behavior. If something isn't clear, please open a pull request adding an +-- example! -- ** Versions -- | Leading zeros are not allowed. @@ -152,6 +218,11 @@ -- >>> renderConstraint <$> parseConstraint "1.2.*" -- Just "1.2.x" -- +-- An optional equals sign can be included with wildcard constraints. +-- +-- >>> renderConstraint <$> parseConstraint "=1.2.x" +-- Just "1.2.x" +-- -- Wildcards can be combined with other constraints. -- -- >>> renderConstraint <$> parseConstraint "1.2.x 2.3.4" @@ -185,8 +256,6 @@ -- Nothing -- >>> parseConstraint "<=1.2.x" -- Nothing --- >>> parseConstraint "=1.2.x" --- Nothing -- >>> parseConstraint ">=1.2.x" -- Nothing -- >>> parseConstraint ">1.2.x" @@ -280,13 +349,13 @@ -- Just "<1.2.0 || <=1.2.1 || 1.2.2 || >=1.2.3 || >1.2.4 || 1.2.5 || 1.2.6 - 1.2.7 || ~1.2.8 || ^1.2.9 || 1.2.x" -- ** Satisfying constraints --- | Although in general you should use 'satisfies', 'parseVersion', and --- 'parseConstraint', doing that here makes it hard to tell what the examples --- are doing. An operator makes things clearer. +-- | Although in general you should use 'satisfiesConstraint', 'parseVersion', +-- and 'parseConstraint', doing that here makes it hard to tell what the +-- examples are doing. An operator makes things clearer. -- --- >>> satisfies <$> parseVersion "1.2.3" <*> parseConstraint "=1.2.3" +-- >>> satisfiesConstraint <$> parseConstraint "=1.2.3" <*> parseVersion "1.2.3" -- Just True --- >>> let version ? constraint = satisfies (unsafeParseVersion version) (unsafeParseConstraint constraint) +-- >>> let version ? constraint = satisfiesConstraint (unsafeParseConstraint constraint) (unsafeParseVersion version) -- >>> "1.2.3" ? "=1.2.3" -- True -- diff --git a/library/Salve/Internal.hs b/library/Salve/Internal.hs --- a/library/Salve/Internal.hs +++ b/library/Salve/Internal.hs @@ -131,8 +131,8 @@ -- | Constrains allowable version numbers. -- --- Use 'parseConstraint' to create constraints and 'satisfies' to see if a --- version number satisfies a constraint. +-- Use 'parseConstraint' to create constraints and 'satisfiesConstraint' to see +-- if a version number satisfiesConstraint a constraint. data Constraint = ConstraintOperator Operator Version | ConstraintHyphen Version Version @@ -449,10 +449,10 @@ -- | Returns 'True' if the version satisfies the constraint, 'False' otherwise. -- --- >>> satisfies <$> parseVersion "1.2.3" <*> parseConstraint ">1.2.0" +-- >>> satisfiesConstraint <$> parseConstraint ">1.2.0" <*> parseVersion "1.2.3" -- Just True -satisfies :: Version -> Constraint -> Bool -satisfies v c = case c of +satisfiesConstraint :: Constraint -> Version -> Bool +satisfiesConstraint c v = case c of ConstraintOperator o w -> case o of OperatorLT -> v < w OperatorLE -> v <= w @@ -473,8 +473,8 @@ WildcardMajor -> True WildcardMinor m -> (makeVersion m 0 0 [] [] <= v) && (v < makeVersion (m + 1) 0 0 [] []) WildcardPatch m n -> (makeVersion m n 0 [] [] <= v) && (v < makeVersion m (n + 1) 0 [] []) - ConstraintAnd l r -> satisfies v l && satisfies v r - ConstraintOr l r -> satisfies v l || satisfies v r + ConstraintAnd l r -> satisfiesConstraint l v && satisfiesConstraint r v + ConstraintOr l r -> satisfiesConstraint l v || satisfiesConstraint r v -- | Focuses on the major version number. -- @@ -729,6 +729,7 @@ wildcardConstraintP :: ReadP.ReadP Constraint wildcardConstraintP = do + ReadP.optional (ReadP.char '=') w <- wildcardP pure (ConstraintWildcard w) diff --git a/salve.cabal b/salve.cabal --- a/salve.cabal +++ b/salve.cabal @@ -3,9 +3,9 @@ -- see: https://github.com/sol/hpack name: salve -version: 0.0.4 +version: 0.0.5 synopsis: Semantic version numbers and constraints. -description: Salve provides semantic version numbers and constraints. +description: Salve provides semantic version (SemVer) numbers and constraints (ranges). category: Distribution homepage: https://github.com/tfausak/salve#readme bug-reports: https://github.com/tfausak/salve/issues