KiCS2
Exported names: Imported modules:

Module CPM.Package

This module contains the data types for a package specification and versions as well as functions for reading/showing/comparing package specs and package versions.

Summary of exported operations:

initialVersion :: (Int,Int,Int,Maybe String)   
The initial version of a new package.
nextMajor :: (Int,Int,Int,Maybe String) -> (Int,Int,Int,Maybe String)   
The next major version of a given version.
nextMinor :: (Int,Int,Int,Maybe String) -> (Int,Int,Int,Maybe String)   
The next minor version of a given version.
emptyPackage :: Package   
An empty package specification.
execOfPackage :: Package -> String   
Returns the name of the executable of the package.
packageSpecToJSON :: Package -> JValue   
Translates a package to a JSON object.
writePackageSpec :: Package -> String -> IO ()   
Writes a basic package specification to a JSON file.
loadPackageSpec :: String -> IO ([LogEntry],Either LogEntry Package)   
Loads a package specification from a package directory.
packageIdEq :: Package -> Package -> Bool   
Checks whether two package ids are equal, i.e.
showSourceOfPackage :: Package -> String   
Shows the package source in human-readable format.
replaceVersionInTag :: Package -> String -> String   
Replace the string $version$ in a tag string by the current version.
vlt :: (Int,Int,Int,Maybe String) -> (Int,Int,Int,Maybe String) -> Bool   
Less than operator for versions.
vlte :: (Int,Int,Int,Maybe String) -> (Int,Int,Int,Maybe String) -> Bool   
Less than or equal operator for versions.
vgt :: (Int,Int,Int,Maybe String) -> (Int,Int,Int,Maybe String) -> Bool   
Greater than operator for versions.
vgte :: (Int,Int,Int,Maybe String) -> (Int,Int,Int,Maybe String) -> Bool   
Greater than or equal operator for versions.
isPreRelease :: (Int,Int,Int,Maybe String) -> Bool   
Is the version a pre-release version?
sourceDirsOf :: Package -> [String]   
Gets the list of source directories of a package.
dependencyNames :: Package -> [String]   
Gets the package names of all dependencies of a package.
showDependency :: Dependency -> String   
Renders a dependency as a string, including all version constraints.
showCompilerDependency :: CompilerCompatibility -> String   
Renders a compiler dependency as a string, including all version constraints.
showVersionConstraints :: [[VersionConstraint]] -> String   
Renders a list of version constraints in disjunctive normal form.
packageId :: Package -> String   
Renders the id of a package as a string.
readPackageSpec :: String -> Either String Package   
Reads a package spec from a JSON string.
readVersionConstraints :: String -> Maybe [[VersionConstraint]]   
Reads a dependency constraint expression in disjunctive normal form into a list of lists of version constraints.
readVersionConstraint :: String -> Maybe VersionConstraint   
Parses a version constraint.
showVersion :: (Int,Int,Int,Maybe String) -> String   
Shows a version in dotted notation.
readVersion :: String -> Maybe (Int,Int,Int,Maybe String)   
Tries to parse a version string.

Exported datatypes:

Version

Data type representin a version number. It is a tuple where the components are major, minor, patch, prerelease, e.g., 3.1.1-rc5

Type synonym: Version = (Int,Int,Int,Maybe String)

Conjunction

Type synonym: Conjunction = [VersionConstraint]

Disjunction

Type synonym: Disjunction = [Conjunction]

Dependency

A dependency on another package. The disjunctive normal form of a boolean combination of version constraints is represented by a list of lists of version constraint. Each inner list of version constraints is a conjunction, the outer list is a disjunction.

Constructors:

VersionConstraint

A version constraint.

Constructors:

  • VExact :: Version -> VersionConstraint : versions must match exactly
  • VGt :: Version -> VersionConstraint : version must be strictly larger than specified version
  • VLt :: Version -> VersionConstraint : version must be strictly smaller than specified version
  • VGte :: Version -> VersionConstraint : version must be larger or equal to specified version
  • VLte :: Version -> VersionConstraint : version must be smaller or equal to specified version
  • VCompatible :: Version -> VersionConstraint : semver arrow, version must be larger or equal and within same minor version
CompilerCompatibility

Compiler compatibility constraint, takes the name of the compiler (kics2 or pakcs), as well as a disjunctive normal form combination of version constraints (see Dependency).

Constructors:

  • CompilerCompatibility :: String -> Disjunction -> CompilerCompatibility
PackageId

A package id consisting of the package name and version.

Constructors:

  • PackageId :: String -> Version -> PackageId
PackageExecutable

The specification to generate an executable from the package. It consists of the name of the executable, the name of the main module (which must contain an operation main), and list of options for various compilers (i.e., pairs of compiler name and options for this compiler).

Constructors:

  • PackageExecutable :: String -> String -> [(String,String)] -> PackageExecutable
PackageTest

The specification of a single test suite for a package. It consists of a directory, a list of modules, options (for CurryCheck), and a name of a test script in this directory. The test script can be empty, but then a non-empty list of modules must be provided. This structure specifies a test which is performed in the given directory by running CurryCheck on the given list of modules where the option string is passed to CurryCheck.

Constructors:

  • PackageTest :: String -> [String] -> String -> String -> PackageTest
PackageDocumentation

The specification to generate the documentation of the package. It consists of the name of the directory containing the documentation, a main file (usually, a LaTeX file) containing the documentation, and a command to generate the documentation. If the command is missing and the main file has the suffix "tex", e.g., "manual.tex", the default command is "pdflatex manual.tex".

Constructors:

  • PackageDocumentation :: String -> String -> String -> PackageDocumentation
PackageSource

A source where the contents of a package can be acquired.

Constructors:

  • Http :: String -> PackageSource : URL to a ZIP file
  • Git :: String -> (Maybe GitRevision) -> PackageSource : URL to a Git repository and an optional revision spec to check out
  • FileSource :: String -> PackageSource : The path to a ZIP file to install. Cannot be specified in a package specification file, for internal use only.
GitRevision

A Git revision.

Constructors:

  • Tag :: String -> GitRevision : A tag which might contain the string $version$ which will be replaced by the package version
  • Ref :: String -> GitRevision : A Git commitish, i.e. a SHA, a branch name, a tag name etc.
  • VersionAsTag :: GitRevision : Use the package version prefixed with a v as the tag
Package

The data type for package specifications.

Constructors:

  • Package :: String -> Version -> [String] -> [String] -> String -> (Maybe String) -> [String] -> (Maybe String) -> (Maybe String) -> (Maybe String) -> (Maybe String) -> (Maybe String) -> (Maybe String) -> [Dependency] -> [CompilerCompatibility] -> (Maybe PackageSource) -> [String] -> [String] -> (Maybe String) -> (Maybe PackageExecutable) -> (Maybe [PackageTest]) -> (Maybe PackageDocumentation) -> Package

    Fields:

    • name :: String
    • version :: Version
    • author :: [String]
    • maintainer :: [String]
    • synopsis :: String
    • description :: (Maybe String)
    • category :: [String]
    • license :: (Maybe String)
    • licenseFile :: (Maybe String)
    • copyright :: (Maybe String)
    • homepage :: (Maybe String)
    • bugReports :: (Maybe String)
    • repository :: (Maybe String)
    • dependencies :: [Dependency]
    • compilerCompatibility :: [CompilerCompatibility]
    • source :: (Maybe PackageSource)
    • sourceDirs :: [String]
    • exportedModules :: [String]
    • configModule :: (Maybe String)
    • executableSpec :: (Maybe PackageExecutable)
    • testSuite :: (Maybe [PackageTest])
    • documentation :: (Maybe PackageDocumentation)

Exported operations:

initialVersion :: (Int,Int,Int,Maybe String)   

The initial version of a new package.

Further infos:
  • solution complete, i.e., able to compute all solutions

nextMajor :: (Int,Int,Int,Maybe String) -> (Int,Int,Int,Maybe String)   

The next major version of a given version.

nextMinor :: (Int,Int,Int,Maybe String) -> (Int,Int,Int,Maybe String)   

The next minor version of a given version.

emptyPackage :: Package   

An empty package specification.

Further infos:
  • solution complete, i.e., able to compute all solutions

execOfPackage :: Package -> String   

Returns the name of the executable of the package. Returns the empty string if the package has no executable to install.

packageSpecToJSON :: Package -> JValue   

Translates a package to a JSON object.

writePackageSpec :: Package -> String -> IO ()   

Writes a basic package specification to a JSON file.

Example call:
(writePackageSpec pkg file)
Parameters:
  • pkg : the package specification to write
  • file : the file name to write to

loadPackageSpec :: String -> IO ([LogEntry],Either LogEntry Package)   

Loads a package specification from a package directory.

Example call:
(loadPackageSpec the)
Parameters:
  • the : directory containing the package.json file

packageIdEq :: Package -> Package -> Bool   

Checks whether two package ids are equal, i.e. if their names and versions match.

Example call:
(packageIdEq p1 p2)
Parameters:
  • p1 : the first package
  • p2 : the second package

showSourceOfPackage :: Package -> String   

Shows the package source in human-readable format.

replaceVersionInTag :: Package -> String -> String   

Replace the string $version$ in a tag string by the current version.

vlt :: (Int,Int,Int,Maybe String) -> (Int,Int,Int,Maybe String) -> Bool   

Less than operator for versions.

vlte :: (Int,Int,Int,Maybe String) -> (Int,Int,Int,Maybe String) -> Bool   

Less than or equal operator for versions.

vgt :: (Int,Int,Int,Maybe String) -> (Int,Int,Int,Maybe String) -> Bool   

Greater than operator for versions.

vgte :: (Int,Int,Int,Maybe String) -> (Int,Int,Int,Maybe String) -> Bool   

Greater than or equal operator for versions.

isPreRelease :: (Int,Int,Int,Maybe String) -> Bool   

Is the version a pre-release version?

Further infos:
  • solution complete, i.e., able to compute all solutions

sourceDirsOf :: Package -> [String]   

Gets the list of source directories of a package. It is either the field sourceDirs (if non-empty) or ["src"].

dependencyNames :: Package -> [String]   

Gets the package names of all dependencies of a package.

showDependency :: Dependency -> String   

Renders a dependency as a string, including all version constraints.

showCompilerDependency :: CompilerCompatibility -> String   

Renders a compiler dependency as a string, including all version constraints.

showVersionConstraints :: [[VersionConstraint]] -> String   

Renders a list of version constraints in disjunctive normal form.

packageId :: Package -> String   

Renders the id of a package as a string. Package name and version separated by a dash.

readPackageSpec :: String -> Either String Package   

Reads a package spec from a JSON string.

readVersionConstraints :: String -> Maybe [[VersionConstraint]]   

Reads a dependency constraint expression in disjunctive normal form into a list of lists of version constraints. The inner lists are conjunctions of version constraints, the outer list is a disjunction of conjunctions.

Properties:

readVersionConstraints "=1.2.3" -=- Just [[VExact (1,2,3,Nothing)]] (test_readVersionConstraints_single)
readVersionConstraints "> 1.0.0, < 2.3.0" -=- Just [[VGt (1,0,0,Nothing),VLt (2,3,0,Nothing)]] (test_readVersionConstraints_multi)
readVersionConstraints ">= 4.0.0 || < 3.0.0, > 2.0.0" -=- Just [[VGte (4,0,0,Nothing)],[VLt (3,0,0,Nothing),VGt (2,0,0,Nothing)]] (test_readVersionConstraints_disjunction)

readVersionConstraint :: String -> Maybe VersionConstraint   

Parses a version constraint.

Properties:

readVersionConstraint "=1.2.3" -=- (Just $ VExact (1,2,3,Nothing)) (test_readVersionConstraint_exact)
readVersionConstraint "1.2.3" -=- (Just $ VExact (1,2,3,Nothing)) (test_readVersionConstraint_without)
readVersionConstraint "=4.a.3" -=- Nothing (test_readVersionConstraint_invalidVersion)
readVersionConstraint "x1.2.3" -=- Nothing (test_readVersionConstraint_invalidConstraint)
readVersionConstraint "> 1.2.3" -=- (Just $ VGt (1,2,3,Nothing)) (test_readVersionConstraint_greaterThan)
readVersionConstraint ">= 1.2.3" -=- (Just $ VGte (1,2,3,Nothing)) (test_readVersionConstraint_greaterThanEqual)
readVersionConstraint "<1.2.3" -=- (Just $ VLt (1,2,3,Nothing)) (test_readVersionConstraint_lessThan)
readVersionConstraint "<= 1.2.3" -=- (Just $ VLte (1,2,3,Nothing)) (test_readVersionConstraint_lessThanEqual)
readVersionConstraint "~>1.2.3" -=- (Just $ VCompatible (1,2,3,Nothing)) (test_readVersionConstraint_compatible)

showVersion :: (Int,Int,Int,Maybe String) -> String   

Shows a version in dotted notation.

readVersion :: String -> Maybe (Int,Int,Int,Maybe String)   

Tries to parse a version string.