[[tags: egg]]

== magic

[[toc:]]

=== Description

libmagic bindings.

Two modules are included, {{(magic)}} and {{(magic libmagic)}}:

* {{(magic)}} is a high-level wrapper providing a single procedure
  called {{identify}}.
* {{(magic libmagic)}} is a one-to-one binding to {{libmagic.h}}, used
  exactly like the C library.

The following documentation applies to the {{(magic)}} module.

The source for this egg is available [[https://git.foldling.org/chicken-magic.git|here]].

=== API

One procedure is provided, {{identify}}, that tries to do what you mean.

Whenever libmagic returns an error, an exception of type {{(exn magic)}}
is raised.

Note that the {{magic}} module loads libmagic's magic numbers database
as soon as it's {{require}}d (a.k.a. {{use}}d). If you're not OK with
this, use the low-level module.

<procedure>(identify [object [flags]]) => string</procedure>

{{identify}} returns a textual description of the file indicated by
{{object}}, or the contents of {{(current-input-port)}} if no {{object}}
is specified.

If {{object}} is given, it may be any of the following object types,
with {{identify}} returning a description of:

* {{blob}}: the contents of the blob.
* {{string}}: the contents of the file indicated by the given filename.
* {{integer}}: the contents of that file descriptor.
* {{input-port}}: the contents of the given port. This port must be
  backed by a file descriptor; if not, an error of type {{(exn type)}}
  will be raised.

If {{flags}} is given, it must be a symbol or list of symbols indicating
the type of description to return. These correspond to the {{MAGIC_*}}
constants in {{libmagic.h}}, and can be any combination of the following
(though not all combinations make sense):

* {{apple}}
* {{compress}}
* {{device}}
* {{mime}}
* {{mime-encoding encoding}}
* {{mime-type type}}
* {{no-apptype}}
* {{no-cdf}}
* {{no-compress}}
* {{no-elf}}
* {{no-encoding}}
* {{no-soft}}
* {{no-tar}}
* {{no-text}}
* {{no-tokens}}
* {{none}}
* {{preserve-atime}}
* {{raw}}
* {{symlink}}

For example:

<enscript highlight="scheme">
(identify "/usr/include/magic.h") ; => "C source, ASCII text"
(identify "/usr/include/magic.h" 'mime) ; => "text/x-c; charset=us-ascii"
(identify "/usr/include/magic.h" '(preserve-atime no-text)) ; => "data"
</enscript>

An unrecognized flag will raise an exception of type {{(exn magic)}}.

=== Author

[[/users/evan-hanson|Evan Hanson]]

=== License

Copyright (c) 2013-2018, 3-Clause BSD.