First commit

syntax.txt

@@ -0,0 +1,90 @@
+bagheera [options] query [--recursive [query]] [options]
+
+options:
+  -a | --date                                   Date filter. Format year[-month[-day]]
+  -d | --directory                              Base directory to execute main query.
+  -h | --help [help]                            Print help. Optional help parameter can be 'attributes', 'dates', 'examples', 'having', 'query', 'recursive' or 'types'.
+  -g | --having <expression>                    Results not matching expression are ignored.
+  -i | --ids                                    Add file ID prior to file name.
+  -l | --limit                                  Maximum number of results to print.
+  -o | --offset                                 Offset to first result to print.
+  -r | --recursive [query]                      Enable directory results recursion. An optional query for recursive results could be used.
+  -e | --recursive-depth                        Maximun directory recursion depth.
+  -c | --recursive-having <expression>          Recursive results not matching expression are ignored.
+  -y | --recursive-type <type>                  File type filter for recursive results, use --help types to obtain information about available types.
+  -t | --silent                                 Print basic info only, aka only print summary.
+  -s | --sort < sort [ < ASC | DES > ] >        Sort obtained results, by default results are not sorted. Sort types available are: automatic, date, default and name.
+  -t | --type <type>                            File type filter for results, use --help types to obtain information about available types.
+  -v | --verbose								More verbosity.
+       --version                                Print version information.
+
+Remarks:
+  · query searchs only for independent words with size greather than 3, even if phrase is quoted or double quoted.
+  · having filters only in results obtained by queries, but supports quoted or double quoted phrases and is not limited by word size.
+  · the NOT logical operator has a high processing and memory cost, so it is preferable to limit its use.
+  · compare two attributes is possible but is more expensive than compare a constant value. The same remark with NOT applies here.
+  · recursive mode recurse over all directories found, but without a recursive query, or recursive-depth param, could obtain many results if there are many trees and leafs in directory arborescence.
+  · when there are duplicate parameters only last parameter value is used and previous parameter values are ignored.
+  · sort parameter must process all results first, so there is a performance impact that depends on the size of the result set.
+      
+Syntax reference:
+
+query :== <expression> | [ NOT <sep> ] ( <expression> )
+
+expression :== [ NOT <sep> ] <term> [ <sep> [ < AND | OR > <sep> ] [ NOT <sep> ] <term> ]
+
+<sep> ::= <space> | <tab>
+
+<term> ::= <simple_term> | <quoted_term> | <double_quoted_term>
+
+<simple_term> ::= <value> | [ <attribute> <logop> [ comp_value ] ] | <date_expr> | <image_orientation_expr> 
+
+<quoted_term> ::= <quote> <simple_term> <quote>
+
+<double_quoted_term> ::= <double_quote> <simple_term> <double_quote>
+
+<comp_value> ::= <attribute> | <value>
+
+<value> ::= <date> | <integer> | <number> | <rating> | <string>
+
+<attribute> ::= album | albumartist | artist | author | composer | lyricist | height | person | title | width | ...
+
+<date> ::= aaaammdd | aaaa-mm-dd | dd-mm-aaaa | dd/mm/aaaa | [ + | - ] <number> [ d | m | w | y ]
+
+<integer> ::= <unsigned integer>
+
+<number> ::= <integer> [ . <integer> ]
+
+<rating> ::= <1..10>
+
+<string> ::= < <char> | <quote> [ <char_without_quote> ] <quote> | <double_quote> [ <char_without_double_quote> ] <double_quote> >...
+
+<char> ::= < any utf-8 character except <quote> or <double_quote> >
+
+<char_without_quote> ::= < any utf-8 character except <quote> >
+
+<char_without_double_quote> ::= < any utf-8 character except <double_quote> >
+
+<space> ::= < >
+
+<tab> ::= <	>
+
+<quote> ::= <'>
+
+<double_quote> ::= <">
+
+<logop> ::= = | : | != | <> | >= | <= | > | <
+
+<date_expr> ::= MODIFIED < TODAY | YESTERDAY | LAST [date_length] <date_period> | [date_length] <date_period> AGO >
+
+<date_length> ::= <number> | ONE | TWO | THREE | ...
+
+<date_period> ::== DAYS | DAY | MONTHS | MONTH | WEEKS | WEEK | YEARS | YEAR
+
+<image_orientation_expr> ::= LANDSCAPE | PORTRAID | SQUARE
+
+<having_expr> ::=  <having_term> | [ NOT <sep> ] ( <having_term> )
+
+<having_term> ::= [ NOT <sep> ] <having_simple_term> [ <sep> [ < AND | OR > <sep> ] [ NOT <sep> ] <having_simple_term> ]
+
+<having_simple_term> ::= <string> | <quoted_string> | <double_quoted_string>