hakyll-4.16.2.0: A static website compiler library

Safe Haskell | Safe-Inferred
Language | Haskell2010

Hakyll.Core.Identifier

Description

An identifier is a type used to uniquely name an item. An identifier is similar to a file path, but can contain additional details (e.g. item's version). Examples of identifiers are:

-     posts/foo.markdown

-     index

-     error/404

See `Identifier` for details.

Synopsis

- data Identifier
- fromFilePath :: FilePath -> Identifier
- toFilePath :: Identifier -> FilePath
- identifierVersion :: Identifier -> Maybe String
- setVersion :: Maybe String -> Identifier -> Identifier

# Documentation

data Identifier Source #

A key data type to identify a compiled `Item` in the `Store`. Conceptually, it's a combination of a file path and a version name. The version is used only when a file is compiled within a rule using the `version` wrapper function (the same source file can be compiled into several items in the store, so the version exists to distinguish them). Use functions like `fromFilePath`, `setVersion`, `getMatches` to build an `Identifier`.

### Usage Examples

Expand

Normally, compiled items are saved to the store by `Rules` with an automatic, implicit identifier and loaded from the store by the user in another rule with a manual, explicit identifier.

Identifiers when using match. Using `match` builds an implicit identifier that corresponds to the expanded, relative path of the source file on disk (relative to the project directory configured with `providerDirectory`):

    -- e.g. file on disk: 'posts/hakyll.md'
    match "posts/*" $ do                                          -- saved with implicit identifier 'posts/hakyll.md'
        compile pandocCompiler

    match "about/*" $ do
        compile $ do
            compiledPost <- load (fromFilePath "posts/hakyll.md") -- load with explicit identifier
            ...

Normally, the identifier is only explicitly created to pass to one of the `load` functions.

Identifiers when using create. Using `create` (thereby inventing a file path with no underlying file on disk) builds an implicit identifier that corresponds to the invented file path:

    create ["index.html"] $ do                                -- saved with implicit identifier 'index.html'
        compile $ makeItem ("Hello world" :: String)

    match "about/*" $ do
        compile $ do
            compiledIndex <- load (fromFilePath "index.html") -- load with an explicit identifier
            ...

Identifiers when using versions. With `version` the same file can be compiled into several items in the store. A version name is needed to distinguish them:

    -- e.g. file on disk: 'posts/hakyll.md'
    match "posts/*" $ do                              -- saved with implicit identifier ('posts/hakyll.md', no-version)
        compile pandocCompiler

    match "posts/*" $ version "raw" $ do              -- saved with implicit identifier ('posts/hakyll.md', version raw)
        compile getResourceBody

    match "about/*" $ do
        compile $ do
            compiledPost <- load (fromFilePath "posts/hakyll.md")                      -- load no-version version
            rawPost <- load . setVersion (Just "raw") $ fromFilePath "posts/hakyll.md" -- load version raw
        ...

Use `setVersion` to set (or replace) the version of an identifier like `fromFilePath "posts/hakyll.md"`.

#### Instances

Instances details

IsString Identifier Source # |
Instance details Defined in Hakyll.Core.Identifier Methods fromString :: String -> Identifier Source #
Show Identifier Source # |
Instance details Defined in Hakyll.Core.Identifier Methods showsPrec :: Int -> Identifier -> ShowS Source # show :: Identifier -> String Source # showList :: [Identifier] -> ShowS Source #
Binary Identifier Source # |
Instance details Defined in Hakyll.Core.Identifier Methods put :: Identifier -> Put Source # get :: Get Identifier Source # putList :: [Identifier] -> Put Source #
NFData Identifier Source # |
Instance details Defined in Hakyll.Core.Identifier Methods rnf :: Identifier -> () Source #
Eq Identifier Source # |
Instance details Defined in Hakyll.Core.Identifier Methods (==) :: Identifier -> Identifier -> Bool Source # (/=) :: Identifier -> Identifier -> Bool Source #
Ord Identifier Source # |

Instance details

Defined in Hakyll.Core.Identifier

Methods

compare :: Identifier -> Identifier -> Ordering Source #

(<) :: Identifier -> Identifier -> Bool Source #

(<=) :: Identifier -> Identifier -> Bool Source #

(>) :: Identifier -> Identifier -> Bool Source #

(>=) :: Identifier -> Identifier -> Bool Source #

max :: Identifier -> Identifier -> Identifier Source #

min :: Identifier -> Identifier -> Identifier Source #

fromFilePath :: FilePath -> Identifier Source #

Parse an identifier from a file path string. For example,

    -- e.g. file on disk: 'posts/hakyll.md'
    match "posts/*" $ do                                          -- saved with implicit identifier 'posts/hakyll.md'
        compile pandocCompiler

    match "about/*" $ do
        compile $ do
            compiledPost <- load (fromFilePath "posts/hakyll.md") -- load with explicit identifier
            ...

toFilePath :: Identifier -> FilePath Source #

Convert an identifier back to a relative `FilePath`.

identifierVersion :: Identifier -> Maybe String Source #

setVersion :: Maybe String -> Identifier -> Identifier Source #

Set or override the version of an identifier in order to specify which version of an `Item` to `load` from the `Store`. For example,

    match "posts/*" $ version "raw" $ do              -- saved with implicit identifier ('posts/hakyll.md', version raw)
        compile getResourceBody

    match "about/*" $ do
        compile $ do
            rawPost <- load . setVersion (Just "raw") $ fromFilePath "posts/hakyll.md" -- load version raw
            ...