-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Inclusion of files in executables at compile-time.
--   
--   Inclusion of files in source code via Template Haskell.
--   
--   When distributing executables, sometimes it is required to attach some
--   other resources in files. Using this library (together with the
--   TemplateHaskell extension) you avoid this problem by including those
--   files inside the executable at compile time.
@package include-file
@version 0.1.0.3


-- | Inclusion of files in source code via Template Haskell.
--   
--   When distributing executables, sometimes it is required to attach some
--   other resources in files. Using <a>includeFileInSource</a> you avoid
--   this problem by including those files inside the executable at compile
--   time.
--   
--   <h1>Example</h1>
--   
--   A quick example. I want to include a small image (<tt>foo.png</tt>) in
--   the executable. I would do:
--   
--   <pre>
--   {-# LANGUAGE TemplateHaskell #-}
--   
--   import Development.IncludeFile
--   
--   $(includeFileInSource "foo.png" "myImage")
--   </pre>
--   
--   This defines the <tt>myImage</tt> value with type <a>ByteString</a>
--   and with the content of the file <tt>foo.png</tt>.
--   
--   <h1>Using <a>includeFileInSource</a></h1>
--   
--   The following entities must be in scope when calling
--   <a>includeFileInSource</a>:
--   
--   <ul>
--   <li>A <tt>ByteString</tt> type.</li>
--   <li>A <tt>Word8</tt> type, instance of the <a>Num</a> class (at least
--   with the <a>fromInteger</a> method implemented).</li>
--   <li>A <tt>pack :: [Word8] -&gt; ByteString</tt> function.</li>
--   </ul>
--   
--   This module re-export these for convenience, but you can use your own
--   types (for example, using <i>lazy</i> bytestrings instead of
--   <i>strict</i> bytestrings).
--   
--   <h1>Using lazy bytestrings</h1>
--   
--   To use lazy bytestrings, instead of importing this full module, import
--   it like this:
--   
--   <pre>
--   import Data.ByteString.Lazy (ByteString,pack)
--   import Development.IncludeFile (includeFileInSource,Word8)
--   </pre>
--   
--   Needless to say, if you have already imported any of those entities,
--   you don't have to do it again.
--   
--   <h1>Performance impact</h1>
--   
--   Benchmarks confirm that it is <i>much</i> faster to use an included
--   bytestring than reading it from a file.
--   
--   <pre>
--   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)
--   </pre>
--   
--   <h1>Large files</h1>
--   
--   Do not use <a>includeFileInSource</a> with large files. The limit
--   between what <i>is</i> and what is <i>not</i> a large file remains
--   uncertain.
module Development.IncludeFile

-- | Define a value of type <tt>ByteString</tt> (where <tt>ByteString</tt>
--   is whatever <tt>ByteString</tt> type is in scope) with the content of
--   a file.
includeFileInSource :: FilePath -> String -> Q [Dec]

-- | A space-efficient representation of a <a>Word8</a> vector, supporting
--   many efficient operations.
--   
--   A <a>ByteString</a> contains 8-bit bytes, or by using the operations
--   from <a>Data.ByteString.Char8</a> it can be interpreted as containing
--   8-bit characters.
data ByteString :: *

-- | 8-bit unsigned integer type
data Word8 :: *

-- | <i>O(n)</i> Convert a '[Word8]' into a <a>ByteString</a>.
--   
--   For applications with large numbers of string literals, pack can be a
--   bottleneck. In such cases, consider using packAddress (GHC only).
pack :: [Word8] -> ByteString