txt: ## dist_cpan-FRITH-Image-Libexif.md
  ## Image::Libexif
  
  Image::Libexif - An interface to libexif.
  
  ## Build Status
  
  | Operating System | Build Status | CI Provider |
  | --- | --- | --- |
  | Linux | [Build Status](https://travis-ci.org/frithnanth/perl6-Image-Libexif) | Travis CI |
  
  ## Example
  
  High-level interface:
  
  ```
  use v6;
  
  use Image::Libexif :tagnames;
  use Image::Libexif::Constants;
  
  #| Prints all the EXIF tags
  sub MAIN($file! where { .IO.f // die "file $file not found" })
  {
    my Image::Libexif $e .= new: :$file;
    my @tags := $e.alltags: :tagdesc;
    say @tags».keys.flat.elems ~ ' tags found';
    for ^EXIF_IFD_COUNT -> $group {
      say "Group $group: " ~ «'Image info' 'Camera info' 'Shoot info' 'GPS info' 'Interoperability info'»[$group];
      for %(@tags[$group]).kv -> $k, @v {
        say "%tagnames{$k.Int}: @v[1] => @v[0]";
      }
    }
  }
  
  ```
  
  ```
  use v6;
  
  use Concurrent::File::Find;
  use Image::Libexif;
  use Image::Libexif::Constants;
  
  #| This program displays the EXIF date and time for every file in a directory tree
  sub MAIN($dir where {.IO.d // die "$dir not found"})
  {
    my @files := find $dir, :extension('jpg'), :exclude-dir('thumbnails') :file, :!directory;
    @files.race.map: -> $file {
        my Image::Libexif $e .= new: :file($file);
        try say "$file " ~ $e.lookup(EXIF_TAG_DATE_TIME_ORIGINAL); # don't die if no EXIF is present
        $e.close;
      }
  }
  
  ```
  
  Raw interface:
  
  ```
  use v6;
  
  use Image::Libexif::Raw;
  use Image::Libexif::Constants;
  use NativeHelpers::Blob;
  
  #| This program extracts an EXIF thumbnail from an image and saves it into a new file (in the same directory as the original).
  sub MAIN($file! where { .IO.f // die "file '$file' not found" })
  {
    my $l = exif_loader_new() // die ’Can't create an exif loader‘;
    # Load the EXIF data from the image file
    exif_loader_write_file($l, $file);
    # Get the EXIF data
    my $ed = exif_loader_get_data($l) // die ’Can't get the exif data‘;
    # The loader is no longer needed--free it
    exif_loader_unref($l);
    $l = Nil;
    if $ed.data && $ed.size {
      my $thumb-name = $file;
      $thumb-name ~~ s/\.jpg/_thumb.jpg/;
      my $data = blob-from-pointer($ed.data, :elems($ed.size), :type(Blob));
      spurt $thumb-name, $data, :bin;
    } else {
      say "No EXIF thumbnail in file $file";
    }
    # Free the EXIF data
    exif_data_unref($ed);
  }
  
  ```
  
  For more examples see the `example` directory.
  
  ## Description
  
  Image::Libexif provides an interface to libexif and allows you to access the EXIF records of an image.
  
  For more details on libexif see L<https://github.com/libexif> and L<https://libexif.github.io/docs.html>.
  
  ## Documentation
  
  #### use Image::Libexif;
  
  #### use Image::Libexif :tagnames;
  
  If asked to import the additional symbol `tagnames`, Image::Libexif will make available the Hash %tagnames, which
  has tag numbers as keys and a short description as values.
  
  #### new()
  
  Creates an Image::Libexif object.
  
  If the optional argument `$file` is provided, then it will be opened and read; if not provided
  during the initialization, the program may call the `open` method later.
  If the optional argument `data` is provided, then the object will be initialized from the provided data; if not
  provided during the initialization, the program may call the `load` method later.
  
  #### open(Str $file!)
  
  Opens a file and reads it into an initialiazed object (when no file or data has been provided during initialization).
  
  #### load(Buf $data!)
  
  Reads the data into an initialiazed object (when no file or data has been provided during initialization).
  
  #### close
  
  Closes the internal libexif object, frees the memory and cleans up.
  
  #### info(--> Hash)
  
  Gathers some info:
  
  * `ordercode`: the byte order as a code
  * `orderstr`: the byte order as a string
  * `datatype`: the data type
  * `tagcount`: the number of tags
  
  #### lookup(Int $tag!, Int $group! --> Str)
  
  #### lookup(Int $tag! --> Str)
  
  Looks up a tag in a specific group or in all groups. A tag may be present in more than one group.
  Group names are available as constants:
  
  * `IMAGE_INFO`
  * `CAMERA_INFO`
  * `SHOOT_INFO`
  * `GPS_INFO`
  * `INTEROPERABILITY_INFO`
  
  #### tags(Int $group! where 0 <= \* < 5, :$tagdesc? --> Hash)
  
  Delivers all the tags in a specific group into a hash; the keys are the tag numbers.
  If the tag description is requested, the hash values are presented as an array [value, tag description].
  
  #### alltags(:$tagdesc? --> Array)
  
  Delivers an array of hashes, one for each group.
  If the tag description is requested, the hash values are presented as an array [value, tag description].
  
  #### notes(--> Array)
  
  Reads the Maker Note data as an array of strings.
  Each string is a concatenation of the note description, name, title, and value.
  
  #### method thumbnail($file where { .IO.f // fail X::Libexif.new: errno => 1, error => "File $\_ not found" } --> Blob)
  
  #### sub thumbnail($file where { .IO.f // fail X::Libexif.new: errno => 1, error => "File $\_ not found" } --> Blob) is export(:thumbnail)
  
  Returns the thumbnail found in the original file, if any, as a Blob.
  This functionality is available as a method and a sub, since the library doesn't really need a fully initialized
  exif object.
  To use the sub import it explicitly: `use Image::Libexif :thumbnail;`.
  
  #### Errors
  
  There one case when an error may be returned: trying to open a non-existent file.
  This can happen while initializing an object with .new() and calling the .open() method.
  In both cases the method will return a Failure object, which can
  be trapped and the exception can be analyzed and acted upon.
  
  ## Prerequisites
  
  This module requires the libexif library to be installed. Please follow the instructions below based on your platform:
  
  ### Debian Linux
  
  ```
  sudo apt-get install libexif12
  
  ```
  
  The module looks for a library called libexif.so.
  
  ## Installation
  
  To install it using zef (a module management tool):
  
  ```
  $ zef update
  $ zef install Image::Libexif
  
  ```
  
  ## Testing
  
  To run the tests:
  
  ```
  $ prove -e "perl6 -Ilib"
  
  ```
  
  ## Note
  
  Image::Libexif relies on a C library which might not be present in one's
  installation, so it's not a substitute for a pure Perl6 module.
  
  ## Author
  
  Fernando Santagata
  
  ## Copyright and license
  
  The Artistic License 2.0
  