Documentation

An associative binary operation

When you want to acquire a resource, do some work with it, and then release the resource, it is a good idea to use bracket, because bracket will install the necessary exception handler to release the resource in the event that an exception is raised during the computation. If an exception is raised, then bracket will re-raise the exception (after performing the release).

A common example is opening a file:

bracket
  (openFile "filename" ReadMode)
  (hClose)
  (\fileHandle -> do { ... })

The arguments to bracket are in this order so that we can partially apply it, e.g.:

withFile name mode = bracket (openFile name mode) hClose

Bracket wraps the release action with mask, which is sufficient to ensure that the release action executes to completion when it does not invoke any interruptible actions, even in the presence of asynchronous exceptions. For example, hClose is uninterruptible when it is not racing other uses of the handle. Similarly, closing a socket (from "network" package) is also uninterruptible under similar conditions. An example of an interruptible action is killThread. Completion of interruptible release actions can be ensured by wrapping them in in uninterruptibleMask_, but this risks making the program non-responsive to Control-C, or timeouts. Another option is to run the release action asynchronously in its own thread:

void $ uninterruptibleMask_ $ forkIO $ do { ... }

The resource will be released as soon as possible, but the thread that invoked bracket will not block in an uninterruptible state.

The join function is the conventional monad join operator. It is used to remove one level of monadic structure, projecting its bound argument into the outer level.

'join bss' can be understood as the do expression

do bs <- bss
   bs

Examples

atomically :: STM a -> IO a

atomically :: STM (IO b) -> IO (IO b)
join       :: IO (IO b)  -> IO b

join . atomically :: STM (IO b) -> IO b

void value discards or ignores the result of evaluation, such as the return value of an IO action.

Examples

>>> void Nothing
Nothing
>>> void (Just 3)
Just ()

>>> void (Left 8675309)
Left 8675309
>>> void (Right 8675309)
Right ()

>>> void [1,2,3]
[(),(),()]

>>> void (1,2)
(1,())

>>> mapM print [1,2]
1
2
[(),()]
>>> void $ mapM print [1,2]
1
2

Left-to-right composition of Kleisli arrows.

'(bs >=> cs) a' can be understood as the do expression

do b <- bs a
   cs b

Right-to-left composition of Kleisli arrows. (>=>), with the arguments flipped.

Note how this operator resembles function composition (.):

(.)   ::            (b ->   c) -> (a ->   b) -> a ->   c
(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c

forM is mapM with its arguments flipped. For a version that ignores the results see forM_.

The strategy of combining computations that can throw exceptions by bypassing bound functions from the point an exception is thrown to the point that it is handled.

Is parameterized over the type of error information and the monad type constructor. It is common to use Either String as the monad type constructor for an error monad in which error descriptions take the form of strings. In that case and many other common cases the resulting monad is already defined as an instance of the MonadError class. You can also define your own error type and/or use a monad type constructor other than Either String or Either IOError. In these cases you will have to explicitly define instances of the MonadError class. (If you are using the deprecated Control.Monad.Error or Control.Monad.Trans.Error, you may also have to define an Error instance.)

Lift a computation from the argument monad to the constructed monad.

Map covariantly over the second argument.

second ≡ bimap id

Examples

>>> second (+1) ('j', 3)
('j',4)

>>> second (+1) (Right 3)
Right 4

Map over both arguments at the same time.

bimap f g ≡ first f . second g

Examples

>>> bimap toUpper (+1) ('j', 3)
('J',4)

>>> bimap toUpper (+1) (Left 'j')
Left 'J'

>>> bimap toUpper (+1) (Right 3)
Right 4

Map covariantly over the first argument.

first f ≡ bimap f id

Examples

>>> first toUpper ('j', 3)
('J',3)

>>> first toUpper (Left 'j')
Left 'J'

Case analysis for the Bool type. bool x y p evaluates to x when p is False, and evaluates to y when p is True.

This is equivalent to if p then y else x; that is, one can think of it as an if-then-else construct with its arguments reordered.

Examples

>>> bool "foo" "bar" True
"bar"
>>> bool "foo" "bar" False
"foo"

>>> let p = True; x = "bar"; y = "foo"
>>> bool x y p == if p then y else x
True
>>> let p = False
>>> bool x y p == if p then y else x
True

Since: base-4.7.0.0

Evaluate each action in the structure from left to right, and ignore the results. For a version that doesn't ignore the results see sequenceA.

sequenceA_ is just like sequence_, but generalised to Applicative actions.

Examples

>>> sequenceA_ [print "Hello", print "world", print "!"]
"Hello"
"world"
"!"

Flipped version of <$>.

(<&>) = flip fmap

Examples

>>> Just 2 <&> (+1)
Just 3

>>> [1,2,3] <&> (+1)
[2,3,4]

>>> Right 3 <&> (+1)
Right 4

Since: base-4.11.0.0

intercalate xs xss is equivalent to (concat (intersperse xs xss)). It inserts the list xs in between the lists in xss and concatenates the result.

>>> intercalate ", " ["Lorem", "ipsum", "dolor"]
"Lorem, ipsum, dolor"

The isSuffixOf function takes two lists and returns True iff the first list is a suffix of the second. The second list must be finite.

>>> "ld!" `isSuffixOf` "Hello World!"
True

>>> "World" `isSuffixOf` "Hello World!"
False

\(\mathcal{O}(\min(m,n))\). The isPrefixOf function takes two lists and returns True iff the first list is a prefix of the second.

>>> "Hello" `isPrefixOf` "Hello World!"
True

>>> "Hello" `isPrefixOf` "Wello Horld!"
False

The fromJust function extracts the element out of a Just and throws an error if its argument is Nothing.

Examples

>>> fromJust (Just 1)
1

>>> 2 * (fromJust (Just 10))
20

>>> 2 * (fromJust Nothing)
*** Exception: Maybe.fromJust: Nothing
...

The fromMaybe function takes a default value and a Maybe value. If the Maybe is Nothing, it returns the default value; otherwise, it returns the value contained in the Maybe.

Examples

>>> fromMaybe "" (Just "Hello, World!")
"Hello, World!"

>>> fromMaybe "" Nothing
""

>>> import Text.Read ( readMaybe )
>>> fromMaybe 0 (readMaybe "5")
5
>>> fromMaybe 0 (readMaybe "")
0

The maybeToList function returns an empty list when given Nothing or a singleton list when given Just.

Examples

>>> maybeToList (Just 7)
[7]

>>> maybeToList Nothing
[]

>>> import Text.Read ( readMaybe )
>>> sum $ maybeToList (readMaybe "3")
3
>>> sum $ maybeToList (readMaybe "")
0

The maybe function takes a default value, a function, and a Maybe value. If the Maybe value is Nothing, the function returns the default value. Otherwise, it applies the function to the value inside the Just and returns the result.

Examples

>>> maybe False odd (Just 3)
True

>>> maybe False odd Nothing
False

>>> import Text.Read ( readMaybe )
>>> maybe 0 (*2) (readMaybe "5")
10
>>> maybe 0 (*2) (readMaybe "")
0

>>> maybe "" show (Just 5)
"5"
>>> maybe "" show Nothing
""

The isNothing function returns True iff its argument is Nothing.

Examples

>>> isNothing (Just 3)
False

>>> isNothing (Just ())
False

>>> isNothing Nothing
True

>>> isNothing (Just Nothing)
False

The isJust function returns True iff its argument is of the form Just _.

Examples

>>> isJust (Just 3)
True

>>> isJust (Just ())
True

>>> isJust Nothing
False

>>> isJust (Just Nothing)
True

A local time together with a time zone.

There is no Eq instance for ZonedTime. If you want to compare local times, use zonedTimeToLocalTime. If you want to compare absolute times, use zonedTimeToUTC.

Substitute various time-related information for each %-code in the string, as per formatCharacter.

The general form is %<modifier><width><alternate><specifier>, where <modifier>, <width>, and <alternate> are optional.

<modifier>

glibc-style modifiers can be used before the specifier (here marked as z):

%-z

no padding

%_z

pad with spaces

%0z

pad with zeros

%^z

convert to upper case

%#z

convert to lower case (consistently, unlike glibc)

<width>

Width digits can also be used after any modifiers and before the specifier (here marked as z), for example:

%4z

pad to 4 characters (with default padding character)

%_12z

pad with spaces to 12 characters

<alternate>

An optional E character indicates an alternate formatting. Currently this only affects %Z and %z.

%Ez

alternate formatting

<specifier>

For all types (note these three are done by formatTime, not by formatCharacter):

%%

%

%t

tab

%n

newline

TimeZone

For TimeZone (and ZonedTime and UTCTime):

%z

timezone offset in the format ±HHMM

%Ez

timezone offset in the format ±HH:MM

%Z

timezone name (or else offset in the format ±HHMM)

%EZ

timezone name (or else offset in the format ±HH:MM)

LocalTime

For LocalTime (and ZonedTime and UTCTime and UniversalTime):

%c

as dateTimeFmt locale (e.g. %a %b %e %H:%M:%S %Z %Y)

TimeOfDay

For TimeOfDay (and LocalTime and ZonedTime and UTCTime and UniversalTime):

%R

same as %H:%M

%T

same as %H:%M:%S

%X

as timeFmt locale (e.g. %H:%M:%S)

%r

as time12Fmt locale (e.g. %I:%M:%S %p)

%P

day-half of day from (amPm locale), converted to lowercase, am, pm

%p

day-half of day from (amPm locale), AM, PM

%H

hour of day (24-hour), 0-padded to two chars, 00 - 23

%k

hour of day (24-hour), space-padded to two chars, 0 - 23

%I

hour of day-half (12-hour), 0-padded to two chars, 01 - 12

%l

hour of day-half (12-hour), space-padded to two chars, 1 - 12

%M

minute of hour, 0-padded to two chars, 00 - 59

%S

second of minute (without decimal part), 0-padded to two chars, 00 - 60

%q

picosecond of second, 0-padded to twelve chars, 000000000000 - 999999999999.

%Q

decimal point and fraction of second, up to 12 second decimals, without trailing zeros. For a whole number of seconds, %Q omits the decimal point unless padding is specified.

UTCTime and ZonedTime

For UTCTime and ZonedTime:

%s

number of whole seconds since the Unix epoch. For times before the Unix epoch, this is a negative number. Note that in %s.%q and %s%Q the decimals are positive, not negative. For example, 0.9 seconds before the Unix epoch is formatted as -1.1 with %s%Q.

DayOfWeek

For DayOfWeek (and Day and LocalTime and ZonedTime and UTCTime and UniversalTime):

%u

day of week number for Week Date format, 1 (= Monday) - 7 (= Sunday)

%w

day of week number, 0 (= Sunday) - 6 (= Saturday)

%a

day of week, short form (snd from wDays locale), Sun - Sat

%A

day of week, long form (fst from wDays locale), Sunday - Saturday

Month

For Month (and Day and LocalTime and ZonedTime and UTCTime and UniversalTime):

%Y

year, no padding. Note %0Y and %_Y pad to four chars

%y

year of century, 0-padded to two chars, 00 - 99

%C

century, no padding. Note %0C and %_C pad to two chars

%B

month name, long form (fst from months locale), January - December

%b, %h

month name, short form (snd from months locale), Jan - Dec

%m

month of year, 0-padded to two chars, 01 - 12

Day

For Day (and LocalTime and ZonedTime and UTCTime and UniversalTime):

%D

same as %m/%d/%y

%F

same as %Y-%m-%d

%x

as dateFmt locale (e.g. %m/%d/%y)

%d

day of month, 0-padded to two chars, 01 - 31

%e

day of month, space-padded to two chars, 1 - 31

%j

day of year, 0-padded to three chars, 001 - 366

%f

century for Week Date format, no padding. Note %0f and %_f pad to two chars

%V

week of year for Week Date format, 0-padded to two chars, 01 - 53

%U

week of year where weeks start on Sunday (as sundayStartWeek), 0-padded to two chars, 00 - 53

%W

week of year where weeks start on Monday (as mondayStartWeek), 0-padded to two chars, 00 - 53

Duration types

The specifiers for DiffTime, NominalDiffTime, CalendarDiffDays, and CalendarDiffTime are semantically separate from the other types. Specifiers on negative time differences will generally be negative (think rem rather than mod).

NominalDiffTime and DiffTime

Note that a "minute" of DiffTime is simply 60 SI seconds, rather than a minute of civil time. Use NominalDiffTime to work with civil time, ignoring any leap seconds.

For NominalDiffTime and DiffTime:

%w

total whole weeks

%d

total whole days

%D

whole days of week

%h

total whole hours

%H

whole hours of day

%m

total whole minutes

%M

whole minutes of hour

%s

total whole seconds

%Es

total seconds, with decimal point and up to <width> (default 12) decimal places, without trailing zeros. For a whole number of seconds, %Es omits the decimal point unless padding is specified.

%0Es

total seconds, with decimal point and <width> (default 12) decimal places.

%S

whole seconds of minute

%ES

seconds of minute, with decimal point and up to <width> (default 12) decimal places, without trailing zeros. For a whole number of seconds, %ES omits the decimal point unless padding is specified.

%0ES

seconds of minute as two digits, with decimal point and <width> (default 12) decimal places.

CalendarDiffDays

For CalendarDiffDays (and CalendarDiffTime):

%y

total years

%b

total months

%B

months of year

%w

total weeks, not including months

%d

total days, not including months

%D

days of week

CalendarDiffTime

For CalendarDiffTime:

%h

total hours, not including months

%H

hours of day

%m

total minutes, not including months

%M

minutes of hour

%s

total whole seconds, not including months

%Es

total seconds, not including months, with decimal point and up to <width> (default 12) decimal places, without trailing zeros. For a whole number of seconds, %Es omits the decimal point unless padding is specified.

%0Es

total seconds, not including months, with decimal point and <width> (default 12) decimal places.

%S

whole seconds of minute

%ES

seconds of minute, with decimal point and up to <width> (default 12) decimal places, without trailing zeros. For a whole number of seconds, %ES omits the decimal point unless padding is specified.

%0ES

seconds of minute as two digits, with decimal point and <width> (default 12) decimal places.

Parses a time value given a format string. Missing information will be derived from 1970-01-01 00:00 UTC (which was a Thursday). Supports the same %-codes as formatTime, including %-, %_ and %0 modifiers, however padding widths are not supported. Case is not significant in the input string. Some variations in the input are accepted:

%z %Ez

accepts any of ±HHMM or ±HH:MM.

%Z %EZ

accepts any string of letters, or any of the formats accepted by %z.

%0Y

accepts exactly four digits.

%0G

accepts exactly four digits.

%0C

accepts exactly two digits.

%0f

accepts exactly two digits.

For example, to parse a date in YYYY-MM-DD format, while allowing the month and date to have optional leading zeros (notice the - modifier used for %m and %d):

Prelude Data.Time> parseTimeM True defaultTimeLocale "%Y-%-m-%-d" "2010-3-04" :: Maybe Day
Just 2010-03-04

This is a data structure to keep the configuration of a feed.

This datatype can be used directly if you want a lower-level interface to generate redirects. For example, if you want to redirect foo.html to bar.jpg, you can use:

create ["foo.html"] $ do
    route idRoute
    compile $ makeItem $ Redirect "bar.jpg"

Compiler form of relativizeUrls which automatically picks the right root path

HTML-escape a string

Example:

escapeHtml "Me & Dean"

Result:

"Me & Dean"

Convert a filepath to an URL starting from the site root

Example:

toUrl "foo/bar.html"

Result:

"/foo/bar.html"

This also sanitizes the URL, e.g. converting spaces into '%20'

Advanced usage: add extra dependencies to compilers. Basically this is needed when you're doing unsafe tricky stuff in the rules monad, but you still want correct builds.

A useful utility for this purpose is makePatternDependency.

Add (or replace) routing in the current Rules value. This functions controls IF and WHERE the compiled results are written out (use one of the match functions to control WHAT content is processed and compile to control HOW). See Routes and Identifier for details on how output filepaths are computed.

Hint: If there's no route attached to a rule, the compilation result is not written out. However, the compilation result is saved to the Store and can be loaded and used within another rule. This behavior is needed, for example, for templates.

Examples

-- e.g. file on disk: 'templates/post.html'

-- Rule 1 (without routing)
match "templates/*" $ do
    -- compilation result saved to store with implicit identifier, e.g. 'templates/post.html'
    compile templateCompiler

-- Rule 2 (with routing)
match "posts/**.md" $ do
    route $ setExtension "html"
    compile $ do
       -- load compiled result of other rule with explicit identifier.
       postTemplate <- loadBody "templates/post.html"
       pandocCompiler >>= applyTemplate postTemplate defaultContext

Add (or replace) the given compilation steps within the given Compiler value to the current Rules value. This functions controls HOW the content within a rule is processed (use one of the match functions to control WHAT content is processed).

The compilation result is saved to the Store under an implicit identifier. See Identifier for details.

If there's routing attached to the rule where this function is used, the compilation result is also written out to a file according to that route. See route and Routes for details.

Examples

-- Select all Markdown files in 'posts' directory
match "posts/**.md" $ do

    route $ setExtension "html"

    -- use pandoc to transform Markdown to HTML in a single step
    compile pandocCompiler

-- Select all Markdown files in 'posts' directory
match "posts/**.md" $ do
    route $ setExtension "html"
    compile $
        pandocCompiler >>=
          loadAndApplyTemplate "templates/post.html" defaultContext

-- To Hakyll templates are just plain files that have to be processed
-- and placed into the store like any other file (but without routing).
-- e.g. file on disk: 'templates/post.html'
match "templates/*" $ compile templateBodyCompiler

<h1>$title$</h1>
$body$

Add the given version name to the implicit identifier(s) under which the compilation result of the given remaining Rules value is saved to the Store. See Identifier for details.

Use this wrapper function for example when you need to compile the same source file into two or more different results, each with a different version name. The version is needed to distinguish between these different compilation results in the store, otherwise they would get the same conflicting identifier in the store.

Warning: If you add a version name with this function, you need to supply the same name when you load the content from the store from within another rule.

Examples

-- e.g. file on disk: 'posts/hakyll.md'

-- saved with implicit identifier ('posts/hakyll.md', no-version)
match "posts/*" $ do
    route $ setExtension "html"
    compile pandocCompiler

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

-- use compilation results from rules above
create ["index.html"] $ do
    route idRoute
    compile $ do
        -- load no-version version
        compiledPost <- load (fromFilePath "posts/hakyll.md")
        -- load version 'raw'
        rawPost <- load . setVersion (Just "raw") $ fromFilePath "posts/hakyll.md"
        ...

Assign (and thereby create) the given identifier(s) to content that has no underlying source file on disk. That content must be created within the compile part of the given remaining Rules value. The given identifier is the id under which the compilation is saved to the Store (in case you want to load it within another rule). See Identifier for details.

Use this function for example to create an overview page that doesn't have or need its content prepared in a file (unlike blog posts which normally have a corresponding Markdown source file on disk).

Examples

-- saved with implicit identifier 'index.html' to Store
create ["index.html"] $ do

    -- compilation result is written to '<destination-directory>/index.html'
    route idRoute

    -- create content without a source file from disk
    compile $ makeItem ("<h1>Hello World</h1>" :: String)

Add a selection of which source files to process (using the given glob pattern) to the given remaining Rules value.

The expanded, relative path of the matched source file on disk (relative to the project directory configured with providerDirectory) becomes the identifier under which the compilation result is saved to the Store (in case you want to load it within another rule). See Identifier for details.

Examples

-- Match all Markdown files in the immediate 'posts' directory
-- e.g. '<project-directory>/posts/hakyll.md'
-- but NOT  '<project-directory>/posts/haskell/monad.md'
match "posts/*.md" $ do
    route $ setExtension "html"
    compile pandocCompiler

-- Match all Markdown files in the 'posts' directory and any subdirectory
-- e.g. '<project-directory>/posts/hakyll.md'
-- and  '<project-directory>/posts/haskell/monad.md'
match "posts/**.md" $ do
    route $ setExtension "html"
    compile pandocCompiler

The monad used to compose rules

Describes an item that can be saved to the disk

Compiler for debugging purposes. Passes a message to the debug logger that is printed in verbose mode.

Prepend an error line to the error, if there is one. This allows you to add helpful context to error messages.

Since: hakyll-4.13.0

Fail so that it is treated as non-defined in an $if()$ branching Hakyll.Web.Template macro, and alternative Contexts are tried

Since: hakyll-4.13.0

Run an IO computation without dependencies in a Compiler. You probably want recompilingUnsafeCompiler instead.

Turn on caching for a compilation value to avoid recomputing it on subsequent Hakyll runs. The storage key consists of the underlying identifier of the compiled ressource and the given name.

Save a snapshot of the item. This function returns the same item, which convenient for building >>= chains.

Get the full contents of the matched source file as a string.

Get the full contents of the matched source file as a string, but without metadata preamble, if there was one.

Get the route for a specified item

Create an item from the underlying identifier and a given value.

A shortcut for only requiring the body for a specific snapshot of an item

A shortcut for only requiring the body of an item.

loadBody = fmap itemBody . load

Require a specific snapshot of an item.

Load an item compiled elsewhere. If the required item is not yet compiled, the build system will take care of that automatically.

Perform a compiler action on the item body. This is the same as traverse, but looks less intimidating.

withItemBody = traverse

Whilst compiling an item, it possible to save multiple snapshots of it, and not just the final result.

A monad which lets you compile items and takes care of dependency tracking for you.

Compose two routes where the first route is applied before the second. So f `composeRoutes` g is more or less equivalent with g . f.

Warning: If the first route fails (e.g. when using matchRoute), Hakyll will not apply the second route (if you need Hakyll to try the second route, use <> on Routes instead).

Examples

-- e.g. file on disk: '<project-directory>/posts/hakyll.md'

-- 'hakyll.md' source file implicitly gets filepath as identifier:
-- 'posts/hakyll.md'
match "posts/*" $ do

    -- compilation result is written to '<destination-directory>/hakyll.html'
    route $ gsubRoute "posts/" (const "") `composeRoutes` setExtension "html"

    compile pandocCompiler

Wrapper function around other route construction functions to get access to the metadata (of the underlying item being processed) and use that for the destination filepath construction. Warning: you have to __ensure that the accessed metadata fields actually exists__.

Examples

---
title: Hakyll Post
slug: awesome-post
...
---
In this blog post we learn about Hakyll ...

match "posts/*" $ do

    -- compilation result is written to '<destination-directory>/awesome-post.html'
    route $ metadataRoute $ \meta ->
        constRoute $ fromJust (lookupString "slug" meta) <> ".html"

    compile pandocCompiler

Create a "substituting" route that searches for substrings (in the underlying identifier) that match the given pattern and transforms them according to the given replacement function. The identifier here is that of the underlying item being processed and is interpreted as an destination filepath. It's normally the filepath of the source file being processed. See Identifier for details.

Hint: The name "gsub" comes from a similar function in [R](https://www.r-project.org) and can be read as "globally substituting" (globally in the Unix sense of repeated, not just once).

Examples

-- e.g. file on disk: '<project-directory>/posts/hakyll.md'

-- 'hakyll.md' source file implicitly gets filepath as identifier:
-- 'posts/hakyll.md'
match "posts/*" $ do

    -- compilation result is written to '<destination-directory>/haskell/hakyll.md'
    route $ gsubRoute "posts/" (const "haskell/")

    compile getResourceBody

-- implicitly gets identifier: 'tags/rss/bar.xml'
create ["tags/rss/bar.xml"] $ do

    -- compilation result is written to '<destination-directory>/tags/bar.xml'
    route $ gsubRoute "rss/" (const "")

    compile ...

Create a route that writes the compiled item to the given destination filepath (ignoring any identifier or other data about the item being processed). Warning: you should __use a specific destination path only for a single file in a single compilation rule__. Otherwise it's unclear which of the contents should be written to that route.

Examples

-- implicitly gets identifier: 'main' (ignored on next line)
create ["main"] $ do

    -- compilation result is written to '<destination-directory>/index.html'
    route $ constRoute "index.html"

    compile $ makeItem ("<h1>Hello World</h1>" :: String)

Create a route where the destination filepath is built with the given construction function. The provided identifier for that function is normally the filepath of the source file being processed. See Identifier for details.

Examples

-- e.g. file on disk: '<project-directory>/posts/hakyll.md'

-- 'hakyll.md' source file implicitly gets filepath as identifier:
-- 'posts/hakyll.md'
match "posts/*" $ do

    -- compilation result is written to '<destination-directory>/posts/hakyll.md.html'
    route $ customRoute ((<> ".html") . toFilePath)

    compile pandocCompiler

Apply the route if the identifier matches the given pattern, fail otherwise

Create a route like idRoute that interprets the identifier (of the item being processed) as the destination filepath but also sets (or replaces) the extension suffix of that path. This identifier is normally the filepath of the source file being processed. See Identifier for details.

Examples

-- e.g. file on disk: '<project-directory>/posts/hakyll.md'

-- 'hakyll.md' source file implicitly gets filepath as identifier:
-- 'posts/hakyll.md'
match "posts/*" $ do

    -- compilation result is written to '<destination-directory>/posts/hakyll.html'
    route (setExtension "html")

    compile pandocCompiler

-- implicitly gets identifier: 'about'
create ["about"] $ do

    -- compilation result is written to '<destination-directory>/about.html'
    route (setExtension "html")

    compile $ makeItem ("Hello world" :: String)

An "identity" route that interprets the identifier (of the item being processed) as the destination filepath. This identifier is normally the filepath of the source file being processed. See Identifier for details.

Examples

-- e.g. file on disk: '<project-directory>/posts/hakyll.md'

-- 'hakyll.md' source file implicitly gets filepath as identifier:
-- 'posts/hakyll.md'
match "posts/*" $ do

    -- compilation result is written to '<destination-directory>/posts/hakyll.md'
    route idRoute

    compile getResourceBody

Type used for a route

|| for patterns: the given identifier must match any subterm

&& for patterns: the given identifier must match both subterms

Match only if the identifier has no version set, e.g.

"foo/*.markdown" .&&. hasNoVersion

Specify a version, e.g.

"foo/*.markdown" .&&. hasVersion "pdf"

Create a Pattern from a regex

Example:

regex "^foo/[^x]*$

Create a Pattern from a list of Identifiers it should match.

Warning: use this carefully with hasNoVersion and hasVersion. The Identifiers in the list already have versions assigned, and the pattern will then only match the intersection of both versions.

A more concrete example,

fromList ["foo.markdown"] .&&. hasVersion "pdf"

will not match anything! The "foo.markdown" Identifier has no version assigned, so the LHS of .&&. will only match this Identifier with no version. The RHS only matches Identifiers with version set to "pdf" -- hence, this pattern matches nothing.

The correct way to use this is:

fromList $ map (setVersion $ Just "pdf") ["foo.markdown"]

Type that allows matching on identifiers

Convert an identifier back to a relative FilePath.

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
        ...

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

-- 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
        ...

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
        ...

-- 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
    ...

The operation doesFileExist returns True if the argument file exists and is not a directory, and False otherwise.

Copy a file with its permissions. If the destination file already exists, it is replaced atomically. Neither path may refer to an existing directory. No exceptions are thrown if the permissions could not be copied.

createDirectoryIfMissing parents dir creates a new directory dir if it doesn't exist. If the first argument is True the function will also create all parent directories if they are missing.

Just as splitPath, but don't add the trailing slashes to each element.

         splitDirectories "/directory/file.ext" == ["/","directory","file.ext"]
         splitDirectories "test/file" == ["test","file"]
         splitDirectories "/test/file" == ["/","test","file"]
Windows: splitDirectories "C:\\test\\file" == ["C:\\", "test", "file"]
         Valid x => joinPath (splitDirectories x) `equalFilePath` x
         splitDirectories "" == []
Windows: splitDirectories "C:\\test\\\\\\file" == ["C:\\", "test", "file"]
         splitDirectories "/test///file" == ["/","test","file"]

Combine two paths with a path separator. If the second path starts with a path separator or a drive letter, then it returns the second. The intention is that readFile (dir </> file) will access the same file as setCurrentDirectory dir; readFile file.

Posix:   "/directory" </> "file.ext" == "/directory/file.ext"
Windows: "/directory" </> "file.ext" == "/directory\\file.ext"
         "directory" </> "/file.ext" == "/file.ext"
Valid x => (takeDirectory x </> takeFileName x) `equalFilePath` x

Combined:

Posix:   "/" </> "test" == "/test"
Posix:   "home" </> "bob" == "home/bob"
Posix:   "x:" </> "foo" == "x:/foo"
Windows: "C:\\foo" </> "bar" == "C:\\foo\\bar"
Windows: "home" </> "bob" == "home\\bob"

Not combined:

Posix:   "home" </> "/bob" == "/bob"
Windows: "home" </> "C:\\bob" == "C:\\bob"

Not combined (tricky):

On Windows, if a filepath starts with a single slash, it is relative to the root of the current drive. In [1], this is (confusingly) referred to as an absolute path. The current behavior of </> is to never combine these forms.

Windows: "home" </> "/bob" == "/bob"
Windows: "home" </> "\\bob" == "\\bob"
Windows: "C:\\home" </> "\\bob" == "\\bob"

On Windows, from [1]: "If a file name begins with only a disk designator but not the backslash after the colon, it is interpreted as a relative path to the current directory on the drive with the specified letter." The current behavior of </> is to never combine these forms.

Windows: "D:\\foo" </> "C:bar" == "C:bar"
Windows: "C:\\foo" </> "C:bar" == "C:bar"

Get the directory name, move up one level.

          takeDirectory "/directory/other.ext" == "/directory"
          isPrefixOf (takeDirectory x) x || takeDirectory x == "."
          takeDirectory "foo" == "."
          takeDirectory "/" == "/"
          takeDirectory "/foo" == "/"
          takeDirectory "/foo/bar/baz" == "/foo/bar"
          takeDirectory "/foo/bar/baz/" == "/foo/bar/baz"
          takeDirectory "foo/bar/baz" == "foo/bar"
Windows:  takeDirectory "foo\\bar" == "foo"
Windows:  takeDirectory "foo\\bar\\\\" == "foo\\bar"
Windows:  takeDirectory "C:\\" == "C:\\"

Get the file name.

takeFileName "/directory/file.ext" == "file.ext"
takeFileName "test/" == ""
isSuffixOf (takeFileName x) x
takeFileName x == snd (splitFileName x)
Valid x => takeFileName (replaceFileName x "fred") == "fred"
Valid x => takeFileName (x </> "fred") == "fred"
Valid x => isRelative (takeFileName x)

Split a filename into directory and file. </> is the inverse. The first component will often end with a trailing slash.

splitFileName "/directory/file.ext" == ("/directory/","file.ext")
Valid x => uncurry (</>) (splitFileName x) == x || fst (splitFileName x) == "./"
Valid x => isValid (fst (splitFileName x))
splitFileName "file/bob.txt" == ("file/", "bob.txt")
splitFileName "file/" == ("file/", "")
splitFileName "bob" == ("./", "bob")
Posix:   splitFileName "/" == ("/","")
Windows: splitFileName "c:" == ("c:","")
Windows: splitFileName "\\\\?\\A:\\fred" == ("\\\\?\\A:\\","fred")

Remove last extension, and the "." preceding it.

dropExtension "/directory/path.ext" == "/directory/path"
dropExtension x == fst (splitExtension x)