-n, --dry-run option
[mob/metatag] / README
1 metatag 0.1
2
3 INSTALLATION
4   Metatag comes with install script, to install it use
5     sh metatag.install
6   
7   Everything gets installed under `/usr/local` but one can overide the following variables
8   
9    prefix
10     root of the installation
11     defaults to `/usr/local/`
12   
13    bindir
14     where to place the `metatag` executable
15     defaults to `$prefix/bin/`
16   
17    pkgdir
18     where the lua scripts are installed
19     defaults to `$prefix/share/metatag/`
20   
21   Dependencies:
22   
23   Metatag is written in lua, the install script checks that either luajit, lua5.1, lua, or lua5.2 is available.
24   Luarocks is optional and loaded when available, thus lua packages could be installed with the OS/Distribution
25   package manager or luarocks.
26   
27   Further it makes use of the lua-stdlib and nixio. Both are available through luarocks at least.
28   The installer checks the presence of these libs but not if the installed version is sufficient (TBD)
29   
30   The engines and exporters need some external programs , these external dependencies are always
31   somewhat in flux and engines will report at runtime when a programm is not found.
32   
33   currently the following programs are suggested:
34   
35    xdg-utils
36    file
37    coreutils
38    mplayer
39    exiftags
40    git-annex
41
42 MANUAL
43   Metadata extraction utility
44   
45   Usage: metatag [options..] [paths..]
46   
47   metatag extracts metadata from files, with an easy extensible framework.
48
49 OPTIONS SUMMARY
50   -l, --load=file                    load a lua file (additional engines, rules, exporters)
51   -e, --lua=code                     execute inline lua code
52   -v, --verbose                      verbose messages
53   -d, --debug                        debugging messages
54   -r, --recursive                    recurse into subdirs
55   -x, --exclude=pattern              exclude pattern from checking
56   -o, --export=exporter[:specs..]..  enable exporters
57   -O, --option=key[[-]=value],..     generic options
58   -q, --quiet                        be silent
59   -V, --version                      display version information, then exit
60   -h, --help                         display this help, then exit
61   -t, --help-topic=topic             display long help about topic
62       --help-list                    list available help topicss
63
64 DESCRIPTION
65   metatag is driven by rules reacting metadata disovered. Processing starts by
66   adding '/=path' for each path given as argument to the program. Which will
67   trigger the matching rule calling the 'stat' engine whose adds more metadata and in
68   turn matching more rules calling further engines and so on.
69   
70   Rules are defined with either the 'field=value' or 'field~=value' operator and provide
71   a list of engines to call upon a successful match. Rules are ordered in sequence of
72   their appearence which can be important because some rules may abort processing or rely
73   on metadata added earlier.
74   
75   Normally it is ensured that each engine is only called once per file, but each engine
76   can override this.
77   
78   When no more Rules match anymore and all engines are run then the given exporters are
79   called with the gathered metadata. The user may provide some filtering to each exporter
80   to control what metadata actually gets exported.
81
82 OPTIONS
83   -l, --load=file
84     Load a lua file (additional engines, rules, exporters). Loaded before configfiles and the rules, engines
85     and exporters shipped with the program to allow one to override rules by custom configuration.
86   
87   -e, --lua=code
88     Execute some inline lua code (additional engines, rules, exporters). Loaded before `--load`. configfiles and the
89     rules, engines and exporters shipped with the program to allow one to override rules by custom configuration.
90   
91   -v, --verbose
92     Enables verbose messages on which report about initialization (adding rules, engines and exporters)
93     and what tools are called when progressing.
94   
95   -q, --quiet
96     Disables all messages.
97   
98   -d, --debug
99     Enable debug messages on which give detailed messages about progress. Which rules match and
100     what engines and exporters are called.
101   
102   -O, --option=key[[-]=value][,..]
103     Generic options are stored in a global 'options' table and can be evaluated by any lua file
104     loaded at runtime (additional rules, engines, exporters). Default options can also be cleared.
105     Options are separated by commas, each one may assign (or clear) a value with the = (-=) operators.
106     when no operator and value is given then option is just set to 'true'. Generic options are
107     extensible custom rules, engines and exporters may query new ones and should document them.
108     Currently available are:
109   
110       gitexclude
111        exclude the '.git*' folders and files
112      
113       nobackup
114        exclude the backup files (by mime type)
115      
116       recursive
117        descend into subdirectories
118      
119       gitannex
120        only process files which are annexed in gitannex (symlink to .git/annex/objects)
121      
122       date_split
123        activate a rules which splits dates into single (".year=", ".month=", ".day=", ".hour=",
124        ".minute=",".second=") subcomponents.
125      
126       timetosecs
127        activate a rule which translates HH:MM:ss.sss time format into seconds.
128   
129   -r, --recursive
130     short for --option=recursive which activates the rule to descend into subdirectories
131   
132   -x, --exclude=patterns
133     The given patterns must be a comma separated list of rule patterns, for each of the given pattern an
134     exclude rule is added which aborts processing the matching file. See 'metatag -t lua_patterns' to learn
135     about the lua string pattern syntax.
136   
137   -o, --export=exporter[:specs..][,...]
138     Select one or more exporters separated by commas. When none is given then the 'print' exporter is selected.
139     Each exporter can have a colon separated list of specs in the field=value form to filter the exported
140     metadata. When a spec is prepended by a minus sign then the match is inverted. Filtering stops at the first
141     found match, when no match is found then the metadata is not included in the export. By default ':-^/$=:'
142     are appended to the specs list. That is the initial '/=filename' metadata is filtered out but anything
143     else is included.
144   
145   -V, --version
146     Display version information, then exit
147   
148   -h, --help
149     Display help, then exit
150   
151   -t, --help-topic=topic
152     Display long help about topic
153   
154   --help-list
155     List available help topics of the buildin help system. Each topic can be read with the -t option above.
156
157 CONFIGFILES
158   metatag tries to load "$HOME/.metatag.lua", "$HOME/.config/metatag.lua" and "./.metatag.lua". These files
159   can define extra rules, engines and exporters. This files are loaded before the rules, engines and exporters
160   shipped with the program to allow one to override rules by custom configuration.
161
162 DEFINED ENGINES CALLED BY RULES
163   The current `metatag` has following engines defined:
164
165    stop
166     Clears all found metadata, aborts processing the current file.
167     Called by exclude rules and for directories.
168   
169    recurse_directory
170     Iterates over all members of a directory and processes them.
171   
172    stat
173     calls the stat() function over the file add this data as `stat.<name>=value` metadata.
174     When the file is a symlink, then an additionall `stat.link=` will contain the resolved
175     filename (even over multiple symlinks). For symlinks which point to nothing (or in circles)
176     stat will return nothing.
177   
178     Called by the very first rule which matches the initial '/=file' metadata.
179     Further basic processing rules (regular files, recurse directories, ...) are triggered on
180     this stat data.
181   
182    mime_type
183     Find out the mime type of the given file, adds a `mime=<type>`.
184     Needs xdg-utils installed.
185   
186    mime_encoding
187     Find out the encoding of the given file, adds a `encoding=<type>` metadata.
188     Called on text files.
189   
190    wc
191     Runs the `wc` utility over the file. Adds `lines=`, `words=` and `characters=` metadata.
192     Called on text files.
193   
194    time_to_secs
195     converts time from "hour:minute:seconds.secondfaction" format into
196     "seconds.secondfaction"
197   
198    date_split
199    date_split_de
200     Split dates into subcomponents, one for international notation ("year/month/day hour:minute:second" or
201     "year:month:day hour:minute:second") and one for german notaton ("day.month.year hour:minute:second").
202   
203    event_by_date
204     Adds metadata according to date matches. The actual metadata to be added has to be configured with
205     the DateEvent(from, to, tag) function first. Dates must match the "year[:/]?month[:/]?day%s*hour:?minute"
206     pattern. For each date a begin and a end date can be specified. The month, day, hour and minute fields are
207     subsequently optional. The tag can be a metadata instruction in the "field[+-?:]=value" format or some
208     custom function with the same prototype as any engine to manipulate existng metadata.
209   
210     There is a default rule for `exif.image_created=` metadata.
211   
212     Example for adding dates:
213      DateEvent("2006/6/1", "2006/6/14", "vacation=summer2006")
214   
215     Will tag all images created in that timespan with the respective vacation metadata.
216   
217    exiftags
218     Calls the exiftags utility and adds all metadata it reports with a 'exif.' prefix to the file.
219   
220     By default invoked on all jpeg images.
221   
222    mplayer
223     Calls `mplayer` with options to query all kinds of metadata from a file.
224     Postprocesses this gathered metadata a bit (see source) and adds it to the file.
225
226 EXPORTERS
227    print
228     prints the found metadata to stdout. First the singlequoted filename and then one metadata
229     entry per line preceeded by a tab character.
230   
231    gitannex
232     uses the 'git-annex' metadata facilities to attach metadata to stored files.
233
234
235 EXTENDING
236   metatag can be extended by supplying extra rules, engines and exporters as lua scripts.
237   Either in the common config file locations (see above) or with the -l/--load option.
238
239   'Meta' is the only global exported object. It provids methods to construct Rules, Engines and Exporters.
240   
241    Meta:Rule(match, engines...)
242     Register a rule
243     parameters:
244   
245      match
246       must be a pattern matching against metadata in the 'field=value' or `field~=value` notation.
247       `field` and `value` are lua patterns. When the operator is `=` then field and value must match
248       some metadata to trigger the rule. When the operator is '~=' then
249       field must match and value must not match to trigger the rule
250   
251      engines
252       a list of names of engines to call
253   
254      Example:
255      invoke the 'mime_type' engine on every 'regular' file
256   
257       Meta:Rule (
258         "stat%.type=reg",
259         "mime_type"
260       )
261   
262    Meta:Exclude(match)
263     Abort processing of the current file when metadata maches.
264     Just a shortcut for `Meta:Rule(match, "stop")`, see above
265   
266    Meta:Engine(name, func)
267     Registers `func` as engine under `name`. When an engine is invoked its called with the following
268     parameters:
269      function (meta, file, key, value)
270   
271        meta
272         a Metadata object which provides the Metadata:Op(meta) and Metadata:Stop() methods.
273         the engine uses Op() to manipulate metadata and Stop() to abort processing on this file.
274   
275        file
276         the full filename of the current file
277   
278        key, value
279         the field and value which triggered the activation of this engine
280   
281    Meta:Export(namespec, func)
282     Registers a function as exporter.
283   
284      namespec
285       is the name of the exporter optionally followed by a colon separated list of filters what metadata
286       should be exported. See -o/--export option for details.
287   
288      func
289       is a function taking following parameters:
290        function (file, meta)
291   
292          file
293           the filename of the current file
294          meta
295           a associative table with field=values relations. Values are stored in a indexed table.
296           The metadata here is already filterd according to the filter specs
297
298 FUNCTIONS
299   metatag defines some global functions which can be used in custom rules, engines and exporters
300
301    sh(cmd)
302     execute a shell command, return all its output in one string.
303   
304    shexists(cmd)
305     checks if 'cmd' is in $PATH, returns true or false
306   
307    page(text)
308     lets the user interactively view the given text.
309     For that a pager (less, more) is invoked or if not available
310     the text is just written to the standard output.
311   
312    shquote(s)
313     returns 's' singlequoted and escaped for shell usage
314   
315    mktable (t)
316     returns a table, when t is a scalar type then it will be wraped as table {t},
317     when it is already a table, t is returned
318   
319    dofileonce(f)
320     ensures that file 'f' is loaded only once, even if symlinked or hardlinked
321   
322    msg(...)
323     prints varargs on stderr unless --quiet is selected
324   
325    vmsg(...)
326     prints varargs on stderr when --verbose or --debug is selected
327   
328    dmsg(...)
329     prints varargs on stderr when --debug is selected
330
331 CONTRIBUTING
332   Metatag is free software maintained in a git repository at
333   
334    git://git.pipapo.org/metatag
335   
336   You always find the newest version there.
337   
338   This project lives from the varity of engines and rules available. One can easily add new facilities.
339   To make it easy to get contributions into the mainline there is an open (untrusted) mob repository
340   where anyone can push changes to. When you do so please open your own branch on the mob repository
341   and notify the maintainer and users about your contribution. When acceptable things will be merged ASAP.
342   This mob repository is available as
343   
344    git://git.pipapo.org/mob/metatag
345   
346   Please note that anyone can push malicious code there, do NOT run the code without review.
347
348 LICENSE
349   metatag             Metadata extraction utility
350   Copyright (C) 2014  Christian Th├Ąter <ct@pipapo.org>
351   
352   This program is free software: you can redistribute it and/or modify
353   it under the terms of the GNU General Public License as published by
354   the Free Software Foundation, either version 3 of the License, or
355   (at your option) any later version.
356   
357   This program is distributed in the hope that it will be useful,
358   but WITHOUT ANY WARRANTY; without even the implied warranty of
359   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
360   GNU General Public License for more details.
361   
362   You should have received a copy of the GNU General Public License
363   along with this program.  If not, see <http://www.gnu.org/licenses/>.
364
365 SUPPORT
366   For question and bug reports contact <ct@pipapo.org>.
367
368   There is a mailinglist for the project, you can subscribe at
369    http://lists.pipapo.org/cgi-bin/mailman/listinfo/metatag
370   or by sending mail to
371    mailto:metatag-request@lists.pipapo.org?subject=subscribe