NAME

gffmatch - Find matching items from the gff structures

SYNOPSIS

gffmatch --help

DESCRIPTION

gffmatch first finds the structure specified with the -s option (or use root if it is not set). Then it starts matching the list of -f options in the order of all of them match then it will print out requested information. All -f options are anded together, and multiple set of -f options can be given separated with -o which are then ored together (i.e. if any of the sets ored together matches then print out information).

Information printed out is specified with the -p option, which gives the regexp of items from the matched structure which are printed out. If --print-fields-recursive is given then those fields are printed out completely.

If information needs to be printed out from different parts of the tree, then named parameters can be used to do that. Named parameters are created by using --parameter, --global-parameter, --area-parameter or --variable-parameter. Each of those options takes a name of the parameter and the path to use when getting the parameter value. The --parameter takes the parameters from the given structure, i.e. the path is relative to the current matched structure. The --global-parameter takes the parameters from the toplevel structure, and --area-parameter takes them from the area file instead of this git file (it is useful when getting for example Name or Tag of the area). As area name and tag are so commonly used there is always automatic paramters @areaname@ and @areatag@ which are set to match the area name and tag.

The --variable-parameter takes the parameter value from the variables. It can take 3 different types of input. If the varname is simply normal variable then it is taken from the current structure. If it is /varname then it is taken from the toplevel structure, and if it is ..varname then it is is taken from the matching structure, and if not set there then from the parent structure etc.

OPTIONS

--help -h: Prints out the usage information.
--version -V: Prints out the version information.
--verbose -v: Enables the verbose prints. This option can be given multiple times, and each time it enables more verbose prints.
--config config-file: All options given by the command line can also be given in the configuration file. This option is used to read another configuration file in addition to the default configuration file.
--print-filename: Prefix the output with the full file name.
--print-basename -b: Prefix the output with the base filename, i.e. the file name where the path component is removed.
--print-fields-recursive: When printing out values, print them recursively, meaning that if it is a gff structure, print that structure and all values contained in. The default operation is to simply print the information that it is complex structure.
--exclude -e exclude-regexp: Exclude the given regexp when reading the data in. This will skip the whole structure behind the given structure, meaning that --include cannot be used to get parts of that back. This can be used to speed up the processing if only specific parts of the tree is required. Normally this should be something like ^/Creature List meaning that all creature list information is skipped when reading gff.
--include -i include-regexp: Only include the given regexp when reading the data in. This will skip all other structures which do not match the regexp. This can be used to speed up the processing if only specific parts of the tree is required. Normally this should be something like ^/Creature List meaning that only creature list information is read in.
--find-structure -s structure-regexp: The given regexp is used to match against all full paths inside the structure when it is processed, and if the regexp match, then this structure is given to the actual matcher. This should specify the structure where you want to do the matching using -f options. It should be something like ^/Creature List\\[\\d+\\]/\$.
--print-fields -p fields-to-print-regexp: When the matching structure has been found, then print out fields matching this regexp. This regexp gets the full path to the object, but you can only print items which are inside the matched structure. You cannot print values from the substructure of the selected one. If this list contains @name@ it is replaced with the named paramter name. For areas there is automatic parameters named @areaname@, and @areatag@. For all items there is always the @path@. Those items can appear anywhere on the regexp and if they are there, the values of them are printed out. So use them inside the regexp like this: Name|Tag|@areaname@.
--proc struct|full|field|value|path|label|csv: Select the format how to print out the information.
--find -f label-regexp:=:value-regexp>: Match the value from field matching the given label-regexp (full path) to the value-regexp. If the values match then print out information. If there is multiple -f options they are anded together, or if they are separated with -o then the two (or more) sets of find options are ored together.
--find -f label-regexp:!:value-regexp>: Match the value from field matching the given label-regexp (full path) to the value-regexp. If the values do not match then print out information. If there is multiple -f options they are anded together, or if they are separated with -o then the two (or more) sets of find options are ored together.
--or -o: Used to or two (or more) sets of find options together. I.e. if any of them match then print out information.
--parameter -P name=relative-path: Define named parameter name to have value taken from reading the value from the item specified by the relative-path. The relative-path is relative to the current matched structure. This name can then be used in the -p structure in format @name@. It can also be used when modifying field or setting variables. It cannot be used when matching the structure.
--global-parameter -g name=absolute-path: Define named parameter name to have value taken from reading the value from the item specified by the absolute-path. The absolute-path is relative to the top structure. This name can then be used in the -p structure in format @name@. It can also be used when modifying field or setting variables. It cannot be used when matching the structure.
--area-parameter -a name=absolute-path: Define named parameter name to have value taken from reading the value from the item specified by the absolute-path. The absolute-path is relative to the top structure of the matching area file (.are). This name can then be used in the -p structure in format @name@. It can also be used when modifying field or setting variables. It cannot be used when matching the structure.
--variable-parameter name=varname: Define named parameter name to have value taken from reading the value from the variable specified by the varname. If the varname starts withe / then then variable read from the top structure. If it starts with .. then the variable is read first from mathing structure, and if not found there, the parent structure, etc until it is read from the top structure. In other cases the variable is read directly from the matching structure.; This name can then be used in the -p structure in format @name@. It can also be used when modifying field or setting variables. It cannot be used when matching the structure.
--dialog -d filename.tlk: Pointer to the tlk file. If given then it is used to convert string references to strings in case there is no strings in the item item itself.

EXPRESSIONS

The named parameter can also do simple expressions. I.e. instead of only @name@ they can have @random(12)@ or similar functions which are replaced with the output of the given function.


Supported functions are:

@random@ | @random(number)@



Generates random number from 1 to number (number included). The
default of 1000000 is used as max if no number is given.


@random0(number)@



Generates random number from 0 to number (number excluded).


@frandom(number)@



Generates floating point random number from 1 to number (up to
number + 1 - epsilon).


@frandom0(number)@



Generates floating point random number from 0 to number (up to
number - epsilon).


@counter@ | @counter(number)@ | @counter(number, mod)@



Generates counter that is incremented every time it is used. If
number is given then start from that value, otherwise start from
zero. If mod is given then return numbers from number to
number + mod - 1.


@substr(str, start)@ | @substr(str, start, len)@



Takes a substring of the str starting from offset start and with
length of len. offset starts from 0, and if offset is
negative then it is calculated from the end of the string. If len
is omitted then it assumed to be rest of the string, and if it is
negative, then it will remove that many characters from the end of
string.





EXAMPLES
    gffmatch.pl --include Creature \
        --find-struct '^/Creature List\[\d+\]/$' \
        --find '/Plot:=:^1$' \
        --print-fields '/Creature List\[\d+\]/Tag$' \
        *.git
    gffmatch.pl \
        -s '^/List\[\d+\]/$' \
        -p 'LocalizedName' \
        -f 'Plot$:=:.*' \
        *.git
    gffmatch.pl \
        -s '^/Creature List\[\d+\]/$' \
        -p 'FirstName|LastName|Tag' \
        -f '/Conversation$:=:^$' \
        *.git
    gffmatch.pl \
        -s '^/[a-zA-Z0-9 ]+\[\d+\]/$' \
        -p 'Tag|CloseLockDC|Locked|Lockable|OpenLockDC|KeyName' \
        --proc full \
            -f "/OpenLockDC$:=:^([6789][0-9]|...)$" \
            -f "/KeyRequired$:=:^0$" \
            -f "/Locked$:=:^1$" \
        -o \
            -f "/OpenLockDC$:=:^([6789][0-9]|...)$" \
            -f "/KeyRequired$:=:^0$" \
            -f "/Locked$:=:^0$" \
            -f "/Lockable$:=:^1$" \
        *.git
    gffmatch.pl \
        --proc csv \
        -b \
        -s '^/Creature List\[\d+\]/$' \
        -p 'ScriptSpawn,Tag,TemplateResRef,FirstName,LastName' \
        -f '/ScriptSpawn$:=:.' \
        *.git > list.csv
    gffmatch.pl \
        --proc csv \
        -b \
        -s '^/$' \
        -p 'ScriptSpawn,Tag,TemplateResRef,FirstName,LastName' \
        -f '/ScriptSpawn$:=:.' \
        *.utc >> list.csv



FILES

~/.gffmatchrc



Default configuration file.





SEE ALSO
gffencode(1), gffmodify(1), gffprint(1), Gff(3), and GffRead(3).



AUTHOR
Tero Kivinen <kivinen@iki.fi>.



HISTORY
This program evolved later to gffmodify(1), and because of that
gffmodify(1) knows even more tricks than this program.