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


-- | Haskell bindings to ExifTool
--   
--   Haskell bindings to the <a>ExifTool</a> command-line application that
--   enable reading, writing and deleting metadata in various file formats.
@package exiftool
@version 0.1.1.0


-- | This module contains bindings to the <a>ExifTool</a> command-line
--   application that enable reading, writing and deleting metadata in
--   various file formats. Here's a short code example, the details are
--   explained below.
--   
--   <pre>
--   {-# LANGUAGE OverloadedLists #-}
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   import Data.HashMap.Strict ((!?))
--   import ExifTool
--   
--   example :: IO ()
--   example =
--     withExifTool $ \et -&gt; do
--       -- Read metadata, with exact (!?) and fuzzy (~~) tag lookup.
--       m &lt;- getMeta et "a.jpg"
--       print $ m !? Tag "EXIF" "ExifIFD" "DateTimeOriginal"
--       print $ m ~~ Tag "EXIF" "" "XResolution"
--       print $ m ~~ Tag "XMP" "" ""
--       -- Write and delete metadata.
--       setMeta et [(Tag "XMP" "XMP-dc" "Description", String "...")] "a.jpg"
--       deleteMeta et [Tag "XMP" "XMP-dc" "Description"] "a.jpg"
--   </pre>
--   
--   Note that this module expects the <tt>exiftool</tt> binary to be in
--   your PATH.
module ExifTool

-- | An ExifTool instance, initialized with <a>startExifTool</a> and
--   terminated with <a>stopExifTool</a>.
data ExifTool

-- | Start an ExifTool instance. Use <a>stopExifTool</a> when done, or
--   <a>withExifTool</a> to combine both steps.
startExifTool :: IO ExifTool

-- | Stop a running ExifTool instance.
stopExifTool :: ExifTool -> IO ()

-- | Start an ExifTool instance, do something with it, then stop it.
withExifTool :: (ExifTool -> IO a) -> IO a

-- | Read all metadata from a file, with ExifTool errors leading to runtime
--   errors. (Use <a>getMetaEither</a> instead if you would rather
--   intercept them.)
getMeta :: ExifTool -> Text -> IO Metadata

-- | Write metadata to a file, with ExifTool errors leading to runtime
--   errors. (Use <a>setMetaEither</a> instead if you would rather
--   intercept them.) The file is modified in place. Make sure you have the
--   necessary backups!
setMeta :: ExifTool -> Metadata -> Text -> IO ()

-- | Delete metadata from a file, with ExifTool errors leading to runtime
--   errors. (Use <a>deleteMetaEither</a> instead if you would rather
--   intercept them.) The file is modified in place. Make sure you have the
--   necessary backups!
deleteMeta :: ExifTool -> [Tag] -> Text -> IO ()

-- | Read all metadata from a file, with ExifTool errors returned as Left
--   values.
getMetaEither :: ExifTool -> Text -> IO (Either Text Metadata)

-- | Write metadata to a file, with ExifTool errors returned as Left
--   values. The file is modified in place. Make sure you have the
--   necessary backups!
setMetaEither :: ExifTool -> Metadata -> Text -> IO (Either Text ())

-- | Delete metadata from a file, with ExifTool errors returned as Left
--   values. The file is modified in place. Make sure you have the
--   necessary backups!
deleteMetaEither :: ExifTool -> [Tag] -> Text -> IO (Either Text ())

-- | A set of ExifTool tag/value pairs.
type Metadata = HashMap Tag Value

-- | An ExifTool tag name, consisting of three components:
--   
--   <ol>
--   <li>The family 0 tag group (information type) e.g., <tt>EXIF</tt> or
--   <tt>XMP</tt>.</li>
--   <li>The family 1 tag group (specific location) e.g., <tt>IFD0</tt> or
--   <tt>XMP-dc</tt>.</li>
--   <li>The actual tag name e.g., <tt>XResolution</tt> or
--   <tt>Description</tt>.</li>
--   </ol>
--   
--   Example: <tt>Tag "EXIF" "IFD0" "XResolution"</tt> corresponds to the
--   ExifTool tag name <tt>EXIF:IFD0:XResolution</tt>.
--   
--   During development, there are several ways to find the exact name of a
--   tag:
--   
--   <ul>
--   <li>See <a>https://exiftool.org/#groups</a> for a list of tag
--   groups.</li>
--   <li>Run something like <tt>exiftool -s -a -G:0:1</tt>.</li>
--   <li>Use the <a>~~</a> operator in ghci.</li>
--   </ul>
data Tag
Tag :: !Text -> !Text -> !Text -> Tag

-- | family 0 tag group
[tagFamily0] :: Tag -> !Text

-- | family 1 tag group
[tagFamily1] :: Tag -> !Text

-- | actual tag name
[tagName] :: Tag -> !Text

-- | An ExifTool tag value, enclosed in a type wrapper.
data Value
String :: !Text -> Value
Binary :: !ByteString -> Value
Number :: !Scientific -> Value
Bool :: !Bool -> Value
List :: ![Value] -> Value

-- | Filter metadata by tag name.
filterByTag :: (Tag -> Bool) -> Metadata -> Metadata

-- | Filter metadata by fuzzy tag name matching. Tag names are matched
--   ignoring case, and empty components of the given tag name are
--   considered wildcards. Examples:
--   
--   <ul>
--   <li><tt>m ~~ Tag "EXIF" "IFD0" "XResolution"</tt> matches exactly the
--   given tag name (ignoring case)</li>
--   <li><tt>m ~~ Tag "exif" "" "xresolution"</tt> matches all EXIF tags
--   with name xresolution (ignoring case), including
--   <tt>EXIF:IFD0:XResolution</tt> and <tt>EXIF:IFD1:XResolution</tt></li>
--   <li><tt>m ~~ Tag "XMP" "" ""</tt> matches all XMP tags</li>
--   </ul>
--   
--   Note that <tt>~~</tt> has higher precedence than <a>&lt;&gt;</a>, so
--   <tt>m ~~ t &lt;&gt; m ~~ t' == (m ~~ t) &lt;&gt; (m ~~ t')</tt> which
--   makes combining filters easy.
--   
--   Hint: This operator is useful to find exact tag names in ghci.
(~~) :: Metadata -> Tag -> Metadata
infixl 8 ~~
instance Data.Hashable.Class.Hashable ExifTool.Tag
instance GHC.Generics.Generic ExifTool.Tag
instance GHC.Classes.Eq ExifTool.Tag
instance GHC.Show.Show ExifTool.Tag
instance GHC.Classes.Eq ExifTool.Value
instance GHC.Show.Show ExifTool.Value
instance Data.Aeson.Types.FromJSON.FromJSON ExifTool.Value
instance Data.Aeson.Types.ToJSON.ToJSON ExifTool.Value
instance Data.Aeson.Types.FromJSON.FromJSON ExifTool.Tag
instance Data.Aeson.Types.FromJSON.FromJSONKey ExifTool.Tag
instance Data.Aeson.Types.ToJSON.ToJSON ExifTool.Tag
instance Data.Aeson.Types.ToJSON.ToJSONKey ExifTool.Tag