Debian Codegraph @

README.grammar

raw
1 About general function
2 ======================
3
4 The checkit-tool validates TIFF-files against a set of rules (see below). The
5 set of rules works as a whitelist. This means that TIFF tags that are used in
6 the file but not explicitly checked by a specific rule (not considering if
7 successful or not) are not allowed. In cases where a rule is executed only
8 if a predicate is set, the tag is only allowed if the predicate check succeeded.
9
10
11 Developers
12 ==========
13 to configure the grammar you could use the PEG-extension for gvim from
14 https://github.com/gf3/peg.vim
15
16 To visualize the grammar, checkout this tools:
17
18 * http://bottlecaps.de/convert/
19 * http://bottlecaps.de/rr/ui
20
21 The actual grammar is visualized in grammar.xhtml
22
23 Users
24 =====
25 To define your own config-file for checking TIFFs, please use this simplified syntax:
26
27
28 * Each line is either a "modeline", an "include" line, a "tag" line, a comment or empty
29 * TODO: a modeline uses "mode(MODE)", MODE could be:
30 ** "baseline", if no modeline is defined, it defaults to "mode(baseline)", too
31 ** "extended"
32 * To include a configfile, use "include(FILENAME)", where FILENAME is a correct path
33 * Comments starts with '# '. They are only allowed to start right at the beginning of a new line.
34 * A tagline is built as "TAG; REQUIREMENTS; VALUES", where
35 * a TAG is an increasing number similar to TIFF-Tag numbers (see TIFF specification)
36 * REQUIREMENTS could be
37 ** 'mandatory' - a tag must exist in TIFF
38 ** 'optional' - a tag may exist in TIFF, if it does, it will be checked
39 ** 'depends(REFERENCE)' - a tag must exist in TIFF if reference exists
40 ** 'optdepends(REFERENCE)' - a tag may exists in TIFF if reference exists. If it exists it will be checked
41 * The syntax for a REFERENCE is TAGREFERENCE.VALUEREFERENCE
42 ** TAGREFERENCE points to a tag number which must be exist,
43 ** VALUEREFERENCE can be one of:
44 *** 'any' (which means any match) or
45 *** a decimal value or
46 *** 'range(START, END)', where START and END are decimal values
47 *** 'only(VALUE)', where VALUE is a decimal value
48 *** 'ntupel(VALUE, ..), decimal values as n-tupel enclosed in brackets
49 *** 'regex("REGEX")', where REGEX is a Perl compatible regular expression (PCRE) with escaped '"' and '\', it only works with tags of type ascii
50 ** only if REFERENCE exists in TIFF the REQUIREMENTS rule will be checked
51 ** The REQUIREMENTS rule will only be checked if REFERENCE exists in the TIF
52 file.
53 * VALUES can be one of:
54 ** 'range(START, END)', where START and END are decimal values
55 ** 'logical_or( VALUELIST)', where VALUELIST are comma-separated decimale values or ntupels
56 ** 'any', which means any match
57 ** 'only(VALUE)', where VALUE is a decimal value
58 ** 'ntupel(VALUE, ..), decimal values as n-tupel enclosed in brackets
59 ** 'regex("REGEX")', where REGEX is a Perl compatible regular expression (PCRE) with escaped '"' and '\', it only works with tags of type ascii
60 * each tagline or comment must be closed with a new line
61
62 If multiple rules are defined per tag, they will be combined.
63
64 For examples, please check the 'example_configs/' - directory.
65
66 Values
67 ======
68
69 At the moment, the parser only supports a limited type of values. To make
70 handling easier, it uses only the value/offset part of an IFD entry.
71
72 Test if grammar parser works correctly
73 ======================================
74
75 You could use the program '/checkit_check_config < your.cfg', this would print
76 a reversed stack output, how each rule will be applied.
77
78 For example, if your rule is
79
80 ----
81 258; optdepends(262.1); logical_or(1, 4, 8)'
82 ----
83
84 it will print:
85
86 ----
87 ((( parse config file )))
88 ((( execute execution plan )))
89 ((( clean execution plan )))
90 ((( print internal execution plan )))
91
92 /* the rules are in stack order, the top comes first */
93
94 /* lineno=001 */ PRECOND: fc_tag_quiet tag=258 top i stack=(0)
95 /* lineno=001 */ PRECOND: fc_tag_has_value_quiet tag=262 top i stack=(1)
96 /* lineno=001 */ EXEC: fc_internal_logic_combine_open tag=258 top i stack=(1)
97
98 /* lineno=001 */ EXEC: fc_tag_has_value tag=258 top i stack=(1)
99
100 /* lineno=001 */ EXEC: fc_tag_has_value tag=258 top i stack=(4)
101
102 /* lineno=001 */ EXEC: fc_tag_has_value tag=258 top i stack=(8)
103
104 ----
105