Development.IncludeFile
Description
Inclusion of files in source code via Template Haskell.
When distributing executables, sometimes it is required to attach some other resources in
files. Using
includeFileInSource you avoid this problem by including those files inside
the executable at compile time.
Example
A quick example. I want to include a small image (
foo.png) in the executable. I would do:
{-# LANGUAGE TemplateHaskell #-} import Development.IncludeFile $(includeFileInSource "foo.png" "myImage")
This defines the
myImage value with type
ByteString and with the content of the file
foo.png.
Using
includeFileInSource
The following entities must be in scope when calling
includeFileInSource:
- A
ByteStringtype.
- A
Word8type, instance of the
Numclass (at least with the
fromIntegermethod implemented).
- A
pack :: [Word8] -> ByteStringfunction.
This module re-export these for convenience, but you can use your own types (for example, using lazy bytestrings instead of strict bytestrings).
Using lazy bytestrings
To use lazy bytestrings, instead of importing this full module, import it like this:
import Data.ByteString.Lazy (ByteString,pack) import Development.IncludeFile (includeFileInSource,Word8)
Needless to say, if you have already imported any of those entities, you don't have to do it again.
Performance impact
Benchmarks confirm that it is much faster to use an included bytestring than reading it from a file.
benchmarking include-file time 1.814 ns (1.799 ns .. 1.826 ns) 1.000 R² (0.999 R² .. 1.000 R²) mean 1.808 ns (1.797 ns .. 1.819 ns) std dev 37.48 ps (31.27 ps .. 46.78 ps) benchmarking read-file time 4.869 μs (4.798 μs .. 4.938 μs) 0.998 R² (0.998 R² .. 0.999 R²) mean 4.911 μs (4.857 μs .. 4.968 μs) std dev 178.8 ns (150.1 ns .. 212.5 ns)
Large files
Do not use
includeFileInSource with large files. The limit between what is and what is not a large
file remains uncertain.
Synopsis
- includeFileInSource :: FilePath -> String -> Q [Dec]
- data ByteString :: *
- data Word8 :: *
- pack :: [Word8] -> ByteString
Including files
includeFileInSource Source
Arguments
Define a value of type
ByteString (where
ByteString is whatever
ByteString type is in scope)
with the content of a file.
Convenient re-exports
data ByteString :: *
A space-efficient representation of a
Word8 vector, supporting many
efficient operations.
A
ByteString contains 8-bit bytes, or by using the operations from
Data.ByteString.Char8 it can be interpreted as containing 8-bit
characters.
Instances
pack :: [Word8] -> ByteString
O(n) Convert a '[Word8]' into a
ByteString.
For applications with large numbers of string literals, pack can be a bottleneck. In such cases, consider using packAddress (GHC only).