Gff - Perl Module to modify Gff datastructures in memory
This module includes functions to read, and modify gff objects. The objects are represented as hash table having other hash tables, arrays or values inside of it. The basic use is like multilevel hash tables: $$gff{'key'}[0]{'Text'}{0}.
You first need either to greate new Gff with Gff::new or read gff structure from disk using GffRead::read. Then you can modify the gff structure in memory with functions defined here (or simply reading values from hash table or assigning new values to them). When you are done you can write gff back to disk using GffWrite::write.
Gff::new is used to bless any other hash to be Gff hash or just to return new empty Gff hash.
\%gff = Gff->new();
\%gff = Gff->new(\%hash);
Gff::get_or_set is used either get old value of the field, or to set new value for the field. The field can be given as a path through the gff structure.
$value = $gff->get_or_set($field);
$value = $gff->get_or_set($field, $value);
The $field can be in the path format, meaning it can have structure names separated by slashes, and array names followed by index of the item in brackets. I.e. format like ``/Creature List[0]/ClassList[0]/MemorizedList8[1]/SpellMetaMagic'' or ``/AreaProperties/MusicDelay''. The returned value will be blessed as Gff structure if it is structure or array. Normally you do not use this low level function, but those upper level functions like Gff::value.
Gff::file_type is used either to set or get file type. This function can only be called on the top level gff structure.
$file_type = $gff->file_type();
$file_type = $gff->file_type($file_type);
Gff::file_version is used either to set or get file version number. This function can only be called on the top level gff structure.
$file_version = $gff->file_version();
$file_version = $gff->file_version($file_version);
Gff::copy_to_top can be used to take a copy of the gff so that the new returned Gff structure is on the top level, i.e. suitable for GffWrite::write. The returned Gff and the old Gff do share the lower level data structures, so modifying them will modify both of them.
$new_top_gff = $gff->copy_to_top($file_type, $file_version);
Gff::struct_keys returns a list of keys on the given structure level.
@keys = $gff->struct_keys();
Gff::value is used either get old value of the field, or to set new value for the field. The field can be given as a path through the gff structure. This can also be used to set the type of the field.
$gff_or_value = $gff->value($field);
$gff_or_value = $gff->value($field, $value);
$gff_or_value = $gff->value($field, $value, $type);
The $field can be in the path format, meaning it can have structure names separated by slashes, and array names followed by index of the item in brackets. I.e. format like ``/Creature List[0]/ClassList[0]/MemorizedList8[1]/SpellMetaMagic'' or ``/AreaProperties/MusicDelay''. The returned value will be blessed as Gff structure if it is structure or array. Normally you do not use this low level function, but those upper level functions like Gff::value. If $type is given then it must be a number matching the nwn type numbers.
Gff::type returns or sets the type of the field.
$type = $gff->type();
$type = $gff->type($type);
The $type is nwn internal type number.
Gff::language converts language id or name and optional gender to language code to be used as index in the localized strings.
$code = $Gff::language($lang, $gender);
$code = $Gff::language($lang);
The $code is number, and $lang is either language number or name ('English', 'French' etc). $gender is either number 0 (= male), or 1 (= female) or string 'Male', or 'Female'. All strings are case insensetive.
Gff::variable is used mostly to set local variables on the structures. It can also be used to fetch the internal gff structure of the variable so the name, value and type can be fetched from there. Those values match the GetLocalString/GetLocalInt etc and SetLocalString/SetLocalInt functions of the nwn-script.
$gff = $gff->variable($name);
$gff = $gff->variable($name, $value);
$gff = $gff->variable($name, $value, $type);
If value is given but undef, then variable is removed. If no type is given then the type is guessed based by the value. If value consists only numbers, then it is assumed to be integers, if value matches \d.\d regexp then it is assumed to be float, and string otherwise. If the type is given it can either be numeric variable type code (different than gff type codes), or 'int', 'float', 'string', 'object', or 'location'. In case 'object' and 'location' then the internal format of the value must be properly formatted for that type. This always return the internal gff structure of the variable.
To get the variable value, type or name use $gff->variable($name)->varvalue, $gff->variable($name)->vartype, and $gff->variable($name)->varname.
Gff::varname is used to get the name of the variable.
$name = $gff->varname();
Gff::varvalue is used to get the value of the variable.
$value = $gff->varvalue();
Gff::vartype is used to get the type of the variable.
$name = $gff->vartype();
Gff::print is used to print the Gff structure to the stdout.
$gff->print(%options);
Following options can be given to the Gff::print.
Gff::encode is used to encode the Gff structure as array of arrays, i.e it is array of all entries in the gff (as flat array), and each array entry has two items, first is the key and second is the value.
@@result = $gff->encode(%options);
Following options can be given to the Gff::encode.
Gff::find is used to find parts of the Gff structure and call given function for each instance of those structures matching.
$gff->find(%options);
Following options can be given to the Gff::find.
If multiple of find_label, find_field and find_type are set, then all of them are checked, and proc is only called if all match.
If multiple of find_label, find_field and find_type are set, then all of them are checked, and proc is only called if all match.
If multiple of find_label, find_field and find_type are set, then all of them are checked, and proc is only called if all match.
Gff::match is used to match two or more Gff structures, and return first difference between them. In case structures match undef is returned. If more than two structures are given, then all other structures are/usr/pkg/bin/pod2html: perllib/Gff.pm: unterminated list at =head in paragraph 249. ignoring. /usr/pkg/bin/pod2html: perllib/Gff.pm: unexpected =back directive in paragraph 252. ignoring. /usr/pkg/bin/pod2html: perllib/Gff.pm: unterminated list at =head in paragraph 256. ignoring. /usr/pkg/bin/pod2html: perllib/Gff.pm: unexpected =back directive in paragraph 259. ignoring. matched against the first one.
$difference = match($gff1, $gff2, ...);
$difference = $gff1->match($gff2, ...);
Gff::diff is used to get difference two or more Gff structures, and return all differences between them. In case structures match undef is returned. If more than two structures are given, then all other structures are matched against the first one, and an array of strings is returned, one for each structure after first one.
$difference = diff($gff1, $gff2, ...);
$difference = $gff1->diff($gff2, ...);
gffprint(1), gffmodify(1), GffRead(3), and GffWrite(3).
Tero Kivinen <kivinen@iki.fi>.
Created to do automated things for the cerea persistent world.