source: project/wiki/eggref/5/magic @ 36445

Last change on this file since 36445 was 36445, checked in by evhan, 10 months ago

wiki/eggref/5: Add docs for recently ported eggs

File size: 2.4 KB
Line 
1[[tags: egg]]
2
3== magic
4
5[[toc:]]
6
7=== Description
8
9Bindings to the magic file recognition library.
10
11Two modules are included, {{(magic)}} and {{(magic libmagic)}}:
12
13* {{(magic)}} is a high-level wrapper providing a single procedure called {{identify}}.
14* {{(magic libmagic)}} is a one-to-one binding to {{libmagic.h}}, used exactly like the C library.
15
16The following documentation applies to the {{(magic)}} module.
17
18The source for this egg is available [[https://git.foldling.org/chicken-magic.git|here]].
19
20=== API
21
22One procedure is provided, {{identify}}, that tries to do what you mean.
23
24Whenever libmagic returns an error, an exception of type {{(exn magic)}} is raised.
25
26Note that the {{magic}} module loads libmagic's magic numbers database as soon as it's loaded. If you're not OK with this, use the low-level module.
27
28<procedure>(identify [object [flags]]) => string</procedure>
29
30{{identify}} returns a textual description of the file indicated by {{object}}, or the contents of {{(current-input-port)}} if no {{object}} is specified.
31
32If {{object}} is given, it may be any of the following object types, with {{identify}} returning a description of:
33
34* {{blob}}: the contents of the blob.
35* {{string}}: the contents of the file indicated by the given filename.
36* {{integer}}: the contents of that file descriptor.
37* {{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.
38
39If {{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):
40
41* {{apple}}
42* {{compress}}
43* {{device}}
44* {{mime}}
45* {{mime-encoding encoding}}
46* {{mime-type type}}
47* {{no-apptype}}
48* {{no-cdf}}
49* {{no-compress}}
50* {{no-elf}}
51* {{no-encoding}}
52* {{no-soft}}
53* {{no-tar}}
54* {{no-text}}
55* {{no-tokens}}
56* {{none}}
57* {{preserve-atime}}
58* {{raw}}
59* {{symlink}}
60
61For example:
62
63<enscript highlight="scheme">
64(identify "/usr/include/magic.h") ; => "C source, ASCII text"
65(identify "/usr/include/magic.h" 'mime) ; => "text/x-c; charset=us-ascii"
66(identify "/usr/include/magic.h" '(preserve-atime no-text)) ; => "data"
67</enscript>
68
69An unrecognized flag will raise an exception of type {{(exn magic)}}.
70
71=== Author
72
73[[/users/evan-hanson|Evan Hanson]]
74
75=== License
76
77Copyright (c) 2013-2018, 3-Clause BSD.
Note: See TracBrowser for help on using the repository browser.