git.iko.soy/hakyll
on 877cb21 help sign in
hakyll/src/Hakyll/Core/Identifier.hs
104 lines 3.8 kB history raw
1--------------------------------------------------------------------------------
2-- | An identifier is a type used to uniquely identify a resource, target...
3--
4-- One can think of an identifier as something similar to a file path. An
5-- identifier is a path as well, with the different elements in the path
6-- separated by @/@ characters. Examples of identifiers are:
7--
8-- * @posts/foo.markdown@
9--
10-- * @index@
11--
12-- * @error/404@
13--
14-- The most important difference between an 'Identifier' and a file path is that
15-- the identifier for an item is not necesserily the file path.
16--
17-- For example, we could have an @index@ identifier, generated by Hakyll. The
18-- actual file path would be @index.html@, but we identify it using @index@.
19--
20-- @posts/foo.markdown@ could be an identifier of an item that is rendered to
21-- @posts/foo.html@. In this case, the identifier is the name of the source
22-- file of the page.
23--
24-- An `Identifier` carries the type of the value it identifies. This basically
25-- means that an @Identifier (Page String)@ refers to a page.
26--
27-- It is a phantom type parameter, meaning you can safely change this if you
28-- know what you are doing. You can change the type using the 'castIdentifier'
29-- function.
30--
31-- If the @a@ type is not known, Hakyll traditionally uses @Identifier ()@.
32{-# LANGUAGE DeriveDataTypeable #-}
33{-# LANGUAGE GeneralizedNewtypeDeriving #-}
34module Hakyll.Core.Identifier
35 ( Identifier
36 , fromFilePath
37 , toFilePath
38 , identifierVersion
39 , setVersion
40 ) where
43--------------------------------------------------------------------------------
44import Control.Applicative ((<$>), (<*>))
45import Control.DeepSeq (NFData (..))
46import Data.List (intercalate)
47import System.FilePath (dropTrailingPathSeparator, splitPath)
50--------------------------------------------------------------------------------
51import Data.Binary (Binary (..))
52import Data.Typeable (Typeable)
53import GHC.Exts (IsString, fromString)
56--------------------------------------------------------------------------------
57-- | An identifier used to uniquely identify a value
58data Identifier = Identifier
59 { identifierVersion :: Maybe String
60 , identifierPath :: String
61 } deriving (Eq, Ord, Typeable)
64--------------------------------------------------------------------------------
65instance Binary Identifier where
66 put (Identifier v p) = put v >> put p
67 get = Identifier <$> get <*> get
70--------------------------------------------------------------------------------
71instance IsString Identifier where
72 fromString = fromFilePath
75--------------------------------------------------------------------------------
76instance NFData Identifier where
77 rnf (Identifier v p) = rnf v `seq` rnf p `seq` ()
80--------------------------------------------------------------------------------
81instance Show Identifier where
82 show i = case identifierVersion i of
83 Nothing -> toFilePath i
84 Just v -> toFilePath i ++ " (" ++ v ++ ")"
87--------------------------------------------------------------------------------
88-- | Parse an identifier from a string
89fromFilePath :: String -> Identifier
90fromFilePath = Identifier Nothing .
91 intercalate "/" . filter (not . null) . split'
92 where
93 split' = map dropTrailingPathSeparator . splitPath
96--------------------------------------------------------------------------------
97-- | Convert an identifier to a relative 'FilePath'
98toFilePath :: Identifier -> FilePath
99toFilePath = identifierPath
102--------------------------------------------------------------------------------
103setVersion :: Maybe String -> Identifier -> Identifier
104setVersion v i = i {identifierVersion = v}