This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Gedcom/CGI, Next: Gedcom/Event, Prev: Gedcom, Up: Module List Basic CGI routines for Gedcom.pm ******************************** NAME ==== Gedcom::CGI - Basic CGI routines for Gedcom.pm Version 1.09 - 12th February 2001 SYNOPSIS ======== use Gedcom::CGI; DESCRIPTION =========== METHODS =======  File: pm.info, Node: Gedcom/Event, Next: Gedcom/Family, Prev: Gedcom/CGI, Up: Module List a module to manipulate Gedcom events ************************************ NAME ==== Gedcom::Event - a module to manipulate Gedcom events Version 1.09 - 12th February 2001 SYNOPSIS ======== use Gedcom::Event; DESCRIPTION =========== A selection of subroutines to handle events in a gedcom file. Derived from Gedcom::Record. HASH MEMBERS ============ None. METHODS ======= None yet. Individual functions --------------------  File: pm.info, Node: Gedcom/Family, Next: Gedcom/Grammar, Prev: Gedcom/Event, Up: Module List a module to manipulate Gedcom families ************************************** NAME ==== Gedcom::Family - a module to manipulate Gedcom families Version 1.09 - 12th February 2001 SYNOPSIS ======== use Gedcom::Family; my @rel = $f->husband; my @rel = $f->wife; my @rel = $f->parents; my $nch = $f->number_of_children; my @rel = $f->children; my @rel = $f->boys; my @rel = $f->girls; DESCRIPTION =========== A selection of subroutines to handle families in a gedcom file. Derived from Gedcom::Record. HASH MEMBERS ============ None. METHODS ======= None yet. Individual functions -------------------- my @rel = $f->husband; my @rel = $f->wife; my @rel = $f->parents; my @rel = $f->children; my @rel = $f->boys; my @rel = $f->girls; Return a list of individuals from family $f. Each function, even those with a singular name such as husband(), returns a list of individuals holding that releation in $f. number_of_children ------------------ my $nch = $f->number_of_children; Return the number of children in the family, as specified or from counting.  File: pm.info, Node: Gedcom/Grammar, Next: Gedcom/Individual, Prev: Gedcom/Family, Up: Module List a module to manipulate Gedcom grammars ************************************** NAME ==== Gedcom::Grammar - a module to manipulate Gedcom grammars Version 1.09 - 12th February 2001 SYNOPSIS ======== use Gedcom::Grammar; my $st = $grammar->structure("GEDCOM"); my $sgr = $grammar->item("DATE"); my @items = $grammar->valid_items; my $min = $grammar->min; my $max = $grammar->max; my @items = $grammar->items; DESCRIPTION =========== A selection of subroutines to handle the grammar of a gedcom file. Derived from Gedcom::Item. HASH MEMBERS ============ Some of the more important hash members are: $grammar->{top} --------------- The top of the grammar tree. $grammar->{top}{structures} --------------------------- A reference to a hash mapping the names of all structures to the grammar objects. METHODS ======= structures ---------- my $st = $grammar->structure("GEDCOM"); Return the grammar item of the specified structure, if it exists, or undef. item ---- my $sgr = $grammar->item("DATE"); Return the grammar item of the specified sub-item, if it exists, or undef. min --- my $min = $grammar->min; Return the minimum permissible number of $grammar items max --- my $max = $grammar->max; Return the maximum permissible number of $grammar items items ----- my @items = $grammar->items; Return a list of tags of the grammar's sub-items valid_items ----------- my @items = $grammar->valid_items; Return a hash detailing all the valid sub-items of the grammar item. The key is the tag of the sub-item and the value is another hash with three members: grammar => the sub-item grammar min => the minimum permissible number of these sub-items max => the maximum permissible number of these sub-items  File: pm.info, Node: Gedcom/Individual, Next: Gedcom/Item, Prev: Gedcom/Grammar, Up: Module List a module to manipulate Gedcom individuals ***************************************** NAME ==== Gedcom::Individual - a module to manipulate Gedcom individuals Version 1.09 - 12th February 2001 SYNOPSIS ======== use Gedcom::Individual; my $name = $i->name; my @rel = $i->father; my @rel = $i->mother; my @rel = $i->parents; my @rel = $i->husband; my @rel = $i->wife; my @rel = $i->spouse; my @rel = $i->siblings; my @rel = $i->brothers; my @rel = $i->sisters; my @rel = $i->children; my @rel = $i->sons; my @rel = $i->daughters; my @rel = $i->descendents; my @rel = $i->ancestors; my $ok = $i->delete; my @fam = $i->famc; my @fam = $i->fams; DESCRIPTION =========== A selection of subroutines to handle individuals in a gedcom file. Derived from Gedcom::Record. HASH MEMBERS ============ None. METHODS ======= name ---- my $name = $i->name; Return the name of the individual, with spaces normalised. cased_name ---------- my $cased_name = $i->cased_name; Return the name of the individual, with spaces normalised, and surname in upper case. surname ------- my $surname = $i->surname; Return the surname of the individual. given_names ----------- my $given_names = $i->given_names; Return the given names of the individual. soundex ------- my $soundex = $i->soundex; Return the soundex code of the individual. This function is only available if *Text::Soundex.pm* is available. sex --- my $sex = $i->sex; Return the sex of the individual, "M", "F" or "U". Individual functions -------------------- my @rel = $i->father; my @rel = $i->mother; my @rel = $i->parents; my @rel = $i->husband; my @rel = $i->wife; my @rel = $i->spouse; my @rel = $i->siblings; my @rel = $i->older_siblings; my @rel = $i->younger_siblings; my @rel = $i->brothers; my @rel = $i->sisters; my @rel = $i->children; my @rel = $i->sons; my @rel = $i->daughters; my @rel = $i->descendents; my @rel = $i->ancestors; Return a list of individuals related to $i. Each function, even those with a singular name such as father(), returns a list of individuals holding that relation to $i. More complex relationships can easily be found using the map function. eg: my @grandparents = map { $_->parents } $i->parents; delete ------ my $ok = $i->delete; Delete $i from the data structure. Returns true iff $i was successfully deleted. Family functions ---------------- my @fam = $i->famc; my @fam = $i->fams; Return a list of families to which $i belongs. famc() returns those families in which $i is a child. fams() returns those families in which $i is a spouse.  File: pm.info, Node: Gedcom/Item, Next: Gedcom/LifeLines, Prev: Gedcom/Individual, Up: Module List a base class for Gedcom::Grammar and Gedcom::Record *************************************************** NAME ==== Gedcom::Item - a base class for Gedcom::Grammar and Gedcom::Record Version 1.09 - 12th February 2001 SYNOPSIS ======== use Gedcom::Record; $item->{grammar} = Gedcom::Grammar->new(file => $item->{grammar_file}, callback => $item->{callback}); my $c = $item->copy; $item->read if $item->{file}; $item->add_items($rec); while (my $next = $item->next_item($item)) my $line = $item->next_line; my $line = $item->next_text_line; $item->write($fh, $level, $flush); $item->write_xml($fh, $level); $item->print; my $item = $item->get_item("CHIL", 2); my @items = $item->get_item("CHIL"); $item->delete_item($sub_item); my $v = $item->level; $item->level(1); my $v = $item->xref; my $v = $item->tag; my $v = $item->value; my $v = $item->min; my $v = $item->max; my $v = $item->gedcom; my $v = $item->file; my $v = $item->line; my $v = $item->full_value; my $sub_items = $item->_items; my @sub_items = $item->items; $item->delete_items; DESCRIPTION =========== A selection of subroutines to handle items in a gedcom file. HASH MEMBERS ============ Some of the more important hash members are: $item->{level} -------------- The level of the item. $item->{xref} ------------- The cross reference, either hard or soft. $item->{tag} ------------ The name of the tag. $item->{value} -------------- The value of the item. $item->{min} ------------ The minimum number of items allowed. $item->{max} ------------ The maximum number of items allowed. $item->{gedcom} --------------- The top level gedcom object. $item->{file} ------------- The file from which this object was read, if any. $item->{line} ------------- The line number from which this object was read, if any. $item->{items} -------------- Array of all sub-items of this item. It should not be necessary to access these hash members directly. METHODS ======= new --- $item->{grammar} = Gedcom::Grammar->new(file => $item->{grammar_file}, callback => $item->{callback}); Create a new object. If file is supplied, it is the name of a file to read. If callback is supplied, it is a subroutine reference which is called at various times while the file is being read. The subroutine takes five parameters: $title: A title $txt1: One text message $txt2: A secondary text message $current: A count of how far through the file we are $total: The extent of the file The subroutine should return true iff the file shuld continue to be read. copy ---- my $c = $item->copy; Make a copy of the object. The sub-items are copied too. read ---- $item->read if $item->{file}; Read a file into the object. Called by the constructor. add_items --------- $item->add_items($rec); Read in the sub-items of a item. next_item --------- while (my $next = $item->next_item($item)) Read the next item from a file. Return the item or false if it cannot be read. next_line --------- my $line = $item->next_line; Read the next line from the file, and return it or false. next_text_line -------------- my $line = $item->next_text_line; Read the next line of text from the file, and return it or false. write ----- $item->write($fh, $level, $flush); Write the item to a FileHandle. The subroutine takes three parameters: $fh: The FileHandle to which to write $level: The level of the item $flush: Whether or not to indent the gedcom output according to the level write_xml --------- $item->write_xml($fh, $level); Write the item to a FileHandle as XML. The subroutine takes two parameters: $fh: The FileHandle to which to write $level: The level of the item Note that this function is experimental. Please read the warnings for Gedcom::write_xml(). print ----- $item->print; Print the item. Used for debugging. (What? There are bugs?) get_item -------- my $item = $item->get_item("CHIL", 2); my @items = $item->get_items("CHIL"); Get specific sub-items from the item. The arguments are the name of the tag, and optionally the count. In scalar context, returns the sub-item, or undef if it doesn't exist. In array context, returns all sub-items matching the specified tag. get_child --------- NOTE - This function is deprecated - use get_item instead my $child = get_child("CHIL2"); Get a specific child item from the item. The argument contains the name of the tag, and optionally the count. The regular expression to generate the tag and the count is: my ($tag, $count) = $t =~ /^_?(\w+?)(\d*)$/ Returns the child item, or undef if it doesn't exist get_children ------------ NOTE - This function is deprecated - use get_item instead my @children = get_children("CHIL"); delete_item ----------- $item->delete_item($sub_item); Delete the specified sub-item from the item. Access functions ---------------- my $v = $item->level; $item->level(1); my $v = $item->xref; my $v = $item->tag; my $v = $item->value; my $v = $item->min; my $v = $item->max; my $v = $item->gedcom; my $v = $item->file; my $v = $item->line; Return the eponymous hash element. If a value if passed into the function, the element is first assigned that value. full_value ---------- my $v = $item->full_value; Return the value of the item including all CONT and CONC lines. This is probably what you want most of the time, and is the function called by default from other functions that return values. If, for some reason, you want to process CONT and CONC items yourself, you will need to use the value() function and probably the items() function. _items ------ my $sub_items = $item->_items; Return a reference to alist of all the sub-items, reading them from the Gedcom file if they have not already been read. It should not be necessary to use this function. See items(). items ----- my @sub_items = $item->items; Return a list of all the sub-items, reading them from the Gedcom file if they have not already been read. In general it should not be necessary to use this function. The sub-items will usually be accessed by name. This function is only necessary if the ordering of the different items is important. This is very rare, but is needed for example, when processing CONT and CONC items. delete_items ------------ $item->delete_items; Delete all the sub-items, allowing the memory to be reused. If the sub-items are required again, they will be reread. It should not be necessary to use this function.  File: pm.info, Node: Gedcom/LifeLines, Next: Gedcom/Record, Prev: Gedcom/Item, Up: Module List functions for lines2perl ************************ NAME ==== Gedcom::LifeLines - functions for lines2perl Version 1.09 - 12th February 2001 SYNOPSIS ======== use Gedcom::LifeLines; DESCRIPTION =========== A selection of subroutines to emulate Lifelines functions. For details about the functions, see the Lifelines documentation. I general, this module should only be used by the output of the lines2perl program. Anything in here that finds a more general use should probably be abstracted away to one of the more standard modules. Functions yet to be implemented include: parent() sibling() getindiset() choosechild() choosefam() chooseindi() choosesubset() menuchoose() card() ord() newfile() outfile() gengedcom() createnode() addnode() deletenode()  File: pm.info, Node: Gedcom/Record, Next: Geo/GNUPlot, Prev: Gedcom/LifeLines, Up: Module List a module to manipulate Gedcom records ************************************* NAME ==== Gedcom::Record - a module to manipulate Gedcom records Version 1.09 - 12th February 2001 SYNOPSIS ======== use Gedcom::Record; my $record = tag_record("CHIL", 2); my @records = tag_record("CHIL"); my @recs = $record->record("birth"); my @recs = $record->record("birth", "date"); my $rec = $record->record("birth date"); my $rec = $record->record(["birth", 2], "date"); my @recs = $record->get_record("birth"); my $val = $record->get_value; my @vals = $record->get_value("date"); my @vals = $record->get_value("birth", "date"); my $val = $record->get_value("birth date"); my $val = $record->get_value(["birth", 2], "date"); $self->parse($record, $grammar); $record->collect_xrefs($callback); my $xref = $record->resolve_xref($record->{value}); my @famc = $record->resolve $record->get_value("FAMC"); $record->resolve_xrefs($callback); $record->unresolve_xrefs($callback); return 0 unless $record->validate_semantics; $record->normalise_dates($format); $record->renumber($args); print $record->summary, "\n"; $record->delete_record($sub_record); DESCRIPTION =========== A selection of subroutines to handle records in a gedcom file. Derived from Gedcom::Item. HASH MEMBERS ============ Some of the more important hash members are: $record->{new_xref} ------------------- Used by renumber(). $record->{recursed} ------------------- Used by renumber(). METHODS ======= tag_record ---------- my $record = tag_record("CHIL", 2); my @records = tag_record("CHIL"); Get specific sub-records from the record. This function is identical to Gedcom::Item::get_item(). The arguments are the name of the tag, and optionally the count. In scalar context, returns the sub-record, or undef if it doesn't exist. In array context, returns all sub-records matching the specified tag. record ------ my @recs = $record->record("birth"); my @recs = $record->record("birth", "date"); my $rec = $record->record("birth date"); my $rec = $record->record(["birth", 2], "date"); my @recs = $record->get_record("birth"); Retrieve a record. The get_record() function is identical to the record() function. In scalar context, record() returns the specified record, or undef if there is none. In list context, record() returns all the specified records. Records may be specified by a list of strings. Each string is either a Gedcom tag or a description. Starting from the first string in the list, specified records are retrieved. Then from those records, records specified by the next string in the list are retrieved. This continues until all strings from the list have been used. In list context, all specified records are retrieved. In scalar context, only the first record is retrieved. If a record other than the first is wanted, then instead of passing a string, a reference to an array containing the string and a count may be passed. Instead of specifying a list of strings, it is possible to specify a single space separated string. This can make the interface nicer. get_value --------- my $val = $record->get_value; my @vals = $record->get_value("date"); my @vals = $record->get_value("birth", "date"); my $val = $record->get_value("birth date"); my $val = $record->get_value(["birth", 2], "date"); Retrieve a record's value. If arguments are specified, record() is first called with those arguments, and the values of those records are returned. parse ----- $self->parse($record, $grammar); Parse a Gedcom record. Match a Gedcom::Record against a Gedcom::Grammar. Warn of any mismatches, and associate the Gedcom::Grammar with the Gedcom::Record as $record->{grammar}. Do this recursively. collect_xrefs ------------- $record->collect_xrefs($callback); Recursively collect all the xrefs. Called by Gedcom::collect_xrefs. $callback is not used yet. resolve_xref ------------ my $xref = $record->resolve_xref($value); See Gedcom::resolve_xrefs() resolve ------- my @famc = $record->resolve $record->tag_value("FAMC"); For each argument, either return it or, if it an xref, return the referenced record. resolve_xrefs ------------- $record->resolve_xrefs($callback); See Gedcom::resolve_xrefs() unresolve_xrefs --------------- $record->unresolve_xrefs($callback); See Gedcom::unresolve_xrefs() validate_semantics ------------------ return 0 unless $record->validate_semantics; Validate the semantics of the Gedcom::Record. This performs a number of consistency checks, but could do even more. Returns true iff the Record is valid. normalise_dates --------------- $record->normalise_dates($format); Change the format of all dates in the record. See the documentation for Gedcom::normalise_dates renumber -------- $record->renumber($args); Renumber the record. See Gedcom::renumber(). child_value ----------- NOTE - This function is deprecated - use tag_value instead. my $child = $record->child_value("NAME"); child_values ------------ NOTE - This function is deprecated - use tag_value instead. my @children = $record->child_values("CHIL"); summary ------- print $record->summary, "\n"; Return a line of text summarising the record. delete_record ------------- $record->delete_record($sub_record); Delete the specified sub-record from the record. Access functions ---------------- All the Gedcom tag names can be used as function names. Depending on the context in which they are called, the functions return either an array of the specified sub-items, or the first specified sub-item. The descriptions of the tags, with spaces replaced by underscores, can also be used as function names. The function names can be of either, or mixed case. Unless you use the tag name, in either case, or the description in lower case, the function will not be pre-declared and you will need to qualify it or `use subs'. use as: my @items = @{$ged->{record}{items}}; my ($m, $w) = $ged->{record}->validate_structure($ged->{record}{grammar}, \@items, 1); warn $w if $w; sub validate_grammar { my $self = shift; my ($grammar, $items, $all) = @_; $I++; my $min = $grammar->min; my $max = $grammar->max; $all++ unless $max; my $matches = 0; my $warn = ""; my $value = $grammar->{tag}; print " " x $I, " looking for ", $all == 1 ? "all" : $max if $D; if ($value) { print " $value, $min -> $max\n" if $D; for (my $c = 0; $c <= $#$items && ($all == 1 || !$max || $matches < $max);) { if ($items->[$c]{tag} eq $value) { my $w = $items->[$c]->validate_syntax2; $warn .= $w; splice @$items, $c, 1; $matches++; } else { $c++; } } } else { # TODO - require Data::Dumper die "What's a " . Data::Dumper->new([$grammar], ["grammar"]) unless ($value) = $grammar->{value} =~ /<<(.*)>>/; die "Can't find $value in gedcom structures" unless my $s = $grammar->structure($value); $grammar->{structure} = $s; print " $value, $min -> $max\n" if $D; my ($m, $w); do { ($m, $w) = $self->validate_structure($s, $items, $all); if ($m) { $matches += $m; $warn .= $w; } } while $m && ($all == 1 || !$max || $matches < $max); } $I-; ($matches, $warn) } sub validate_structure { my $self = shift; my ($structure, $items, $all) = @_; $all = 0 unless defined $all; $I++; print " " x $I . "validate_structure($structure->{structure}, $all)\n" if $D; my $warn = ""; my $total_matches = 0; for my $item (@{$structure->{items}}) { my $min = $item->min; my $max = $item->max; my ($matches, $w) = $self->validate_grammar($item, $items, $all); $warn .= $w; my $file = $self->{gedcom}{record}{file}; my $value = $item->{tag} || $item->{structure}{structure}; my $msg = "$file:$self->{line}: $self->{tag}" . (defined $self->{xref} ? " $self->{xref} " : "") . " has $matches $value" . ($matches == 1 ? "" : "s"); print " " x $I . "$msg - minimum is $min maximum is $max\n" if $D; if ($structure->{selection}) { if ($matches) { $warn .= "$msg - minimum is $min\n" if $matches < $min; $warn .= "$msg - maximum is $max\n" if $matches > $max && $max; $total_matches += $matches; # only one item is allowed last; } } else { $warn .= "$msg - minimum is $min\n" if $matches < $min; $warn .= "$msg - maximum is $max\n" if $matches > $max && $max; $total_matches = 1 if $matches; # all items are required } } print " " x $I . "returning $total_matches matches\n" if $D; $I-; ($total_matches, $warn) } sub validate_syntax2 { my $self = shift; $self->{gedcom}{validate_callback}->($self) if defined $self->{gedcom}{validate_callback}; my $items = [ @{$self->{items}} ]; $I++; my $grammar = $self->{grammar}; print " " x $I . "validate_syntax2($grammar->{tag})\n" if $D; my $warn = ""; my $file = $self->{gedcom}{record}{file}; my $here = "$file:$self->{line}: $self->{tag}" . (defined $self->{xref} ? " $self->{xref}" : ""); for my $item (@$items) { print " " x $I . "level $item->{level} on $self->{level}\n" if $D; $warn .= "$here: Can't add level $item->{level} to $self->{level}\n" if $item->{level} > $self->{level} + 1; } for my $item (@{$grammar->{items}}) { my $min = $item->min; my $max = $item->max; my ($matches, $w) = $self->validate_grammar($item, $items, 1); $warn .= $w; my $value = $item->{tag} || $item->{structure}{structure}; my $msg = "$here has $matches $value" . ($matches == 1 ? "" : "s"); print " " x $I . "$msg - minimum is $min maximum is $max\n" if $D; $warn .= "$msg - minimum is $min\n" if $matches < $min; $warn .= "$msg - maximum is $max\n" if $matches > $max && $max; } if (@$items) { my %tags = map { $_ => 1 } $grammar->items; for my $c (@$items) { my $tag = $c->{tag}; my $msg = exists $tags{$tag} ? "an extra" : "not a"; $warn .= "$file:$c->{line}: $tag is $msg item of $self->{tag}\n" unless $tag eq "CONT" || $tag eq "CONC" || substr($tag, 0, 1) eq "_"; } } $I-; $warn } =end  File: pm.info, Node: Geo/GNUPlot, Next: Geo/METAR, Prev: Gedcom/Record, Up: Module List Perl extension for plotting position tracks onto a world map. ************************************************************* NAME ==== Geo::GNUPlot - Perl extension for plotting position tracks onto a world map. SYNOPSIS ======== use Geo::GNUPlot; $option_HR={ 'grid_file' => '/home/test/grid_file', 'map_file' => '/home/test/map_file', 'gnuplot' => '/usr/local/gnuplot', }; $plot_obj=Geo::GNUPlot->new($option_HR); $track_AR=[ [15, 50], #x,y pair [5.3, 10.2], [-2, -5] ]; or $track_AR=[ [50, N, 15, E], #latitude, lat. direction, longitude, long. direction [10.2, N, 5.3, E], [5, S, 2, W] ]; $output_file='/home/test/plot.gif'; $plot_option_HR={ 'x_pad' => 2, #default 0 'y_pad' => 3, #default 0 'x_scale' => 5, #default 1 'y_scale' => 4, #default 1 'title' => 'Example Plot', #default 'Storm Tracking Map' 'term' => 'gif', #default gif {any valid gnuplot term argument} 'temp_dir' => '/home/tmp/', #default '/tmp/' }; #Create the plot. ($success, $error)=$plot_obj->plot_track($track_AR, $output_file, $plot_option_HR); #### #For diagnostic purposes, create a contour and surface plot of the radius function. $contour_plot='/home/test/radius_contour.gif'; $surface_plot='/home/test/radius_surface.gif'; #Only the temp_dir, and term option values will be used. ($success,$error)=$plot_obj->plot_radius_function($contour_plot, $surface_plot, $plot_option_HR); #### #Determine the radius function value at a given position. $position_AR=[5.3, 10.2]; or $position_AR=[10.2, N, 5.3, E]; ($function_value, $error)=$plot_obj->radius_function($position_AR); DESCRIPTION =========== This program plots a set of latitude/longitude pairs as a track on a world map using gnuplot. The plot radius is determined by a user defined radius function. IMPLEMENTATION ============== This program utilizes gnuplot by generating temporary gnuplot configuration files and then running gnuplot on these files. The knowledge of what xrange and yrange to use in the gnuplot configuration files is determined by a user defined radius function, an x and y padding, and an x and y scaling of the radius function. The radius function is controlled by user defined node values on a user defined irregular grid. Values between the nodes are computed using two dimensional linear interpolation. I used Numerical Recipes in Fortran 77 page 117 equations 3.6.3, 3.6.4, and 3.6.5 as a reference. It is a simple formula and can be derived from scratch without too much effort. If you don't like this approach then simply override the radius_function method with your own. Better yet, provide your improved version to the current maintainer of this package. In the event Jimmy Carpenter (myself) is still the maintainer, offer to take over! The irregular grid and node values are set in the grid_file file. An example is shown below: #xtics must be numerically ascending xtics: -170, -70, -50, -30, -10, 30, 180 #ytics must be numerically descending ytics: 90, 80, 60, 40, 20, 0, -60, -90 # radius_grid: 5 4 5 5 8 8 9 5 4 5 5 8 8 9 5 4 5 5 8 8 2 5 6 5 5 6 3 9 5 4 8 5 8 8 2 5 3 5 5 7 8 9 5 4 5 5 8 8 6 5 4 5 5 8 8 9 To see what this looks like, just cut and paste this example into a file and generate a contour and surface plot using the plot_radius_function method. To see how this function affects the plot window try out the plot_track method for various positions. The objective of the radius function approach is to allow the user to correlate interest level to plot zoom level. In the event you live in Houston you probably don't care too much about how close a hurricane is to some small deserted island in the Atlantic Ocean. Your concern will be how close the hurricane is to your home in Houston. It is also possible to create a radius function that insures a plot of a hurricane in the middle of the Atlantic Ocean has a wide enough plot window to show some land that provides context. CONSTRUCTOR =========== new (HASH_REF) Creates and returns a new `Geo::GNUPlot' object. If unsuccessful it returns an undefined value. The mandatory hash reference argument should contain the following keys and associated values: grid_file: contains path to the grid file map_file: contains a 2D map of the world (provided with bundle) gnuplot: contains path to gnuplot executable METHODS ======= plot_track(TRACK_ARRAY_REF, OUTPUT_FILE, OPTION_HASH_REF) Creates a plot of the position track provided by the TRACK_ARRAY_REF and outputs it to the OUTPUT_FILE filename. The plot configuration options are contained in the OPTION_HASH_REF. The plot_track method returns an array of the form (SUCCESS, ERROR). SUCCESS indicates if the method successfully generated a plot. ERROR contains the reason for any failure. If the method was successful ERROR will be undefined. The TRACK_ARRAY_REF is an array of position arrays. The position arrays can be either x,y pairs, or an array of the form (LATTITUDE, LATTITUDE_DIR, LONGITUDE, LONGITUDE_DIR). The plot will be centered around the first position in the TRACK_ARRAY_REF. The OUTPUT_FILE is the full path of the filename to use as output. The OPTION_HASH_REF contains configuration options for the plot. The valid option keys, descriptions, and default values are given below. x_pad: Determines the additional X padding for the plot. Defaults to 1. y_pad: Determines the additional Y padding for the plot. Defaults to 1. x_scale: Scales the radius value returned by the radius_function method for use in determining the xrange of the plot. Defaults to 1. y_scale: Scales the radius value returned by the radius_function method for use in determining the yrange of the plot. Defaults to 1. title: Sets the plot title. Defaults to 'Storm Tracking Map'. term: Sets the gnuplot terminal type. See gnuplot documentation for more details. Defaults to 'gif'. temp_dir: Sets the directory to use for writing temporary configuration and data files. Defaults to '/tmp/'. plot_radius_function(CONTOUR_OUTPUT_FILE, SURFACE_OUTPUT_FILE, OPTION_HASH_REF) Creates a 2D contour and 3D surface plot of the radius function. This enables the user to better visualize the radius function and how it is being interpolated from the provided node values. The 2D contour plot overlays the world map provided by the map_file during construction of the `Geo::GNUPlot' object. The CONTOUR_OUTPUT_FILE is the full path of the filename to use for the contour plot. The SURFACE_OUTPUT_FILE is the full path of the filename to use for the surface plot. The OPTION_HASH_REF is identical in format to that used for the plot_track method, except only the temp_dir and term key value pairs are needed or required. The plot_radius_function method returns an array of the form (SUCCESS, ERROR). SUCCESS indicates if the method successfully generated the plots. ERROR contains the reason for any failure. If the method was successful ERROR will be undefined. radius_function(POSITION_ARRAY_REF) Provides direct access to the radius_function internally used to compute plot window sizes. This can be useful for things such as sorting positions by interest level or debugging changes to the radius function. The POSITION_ARRAY_REF has the same two possible forms as each element of the TRACK_ARRAY_REF argument of the plot_track method. AUTHOR ====== James Lee Carpenter, Jimmy.Carpenter@chron.com SEE ALSO ======== Geo::StormTracker gnuplot perl(1). ADDITIONAL REFERENCES ===================== gnuplot http://www.cs.dartmouth.edu/gnuplot_info.html http://members.theglobe.com/gnuplot/ http://www.geocities.com/SiliconValley/Foothills/6647/ linear interpolation Numerical Recipes in Fortran 77 Second Edition (The Art of Scientific Computing) Authors: William H. Press William T. Vettering Saul A. Teukolsky Brian P. Flannery Pub: Cambridge University Press ISBN: 0-521-43064-X Relevant Page: 117  File: pm.info, Node: Geo/METAR, Next: Geo/StormTracker, Prev: Geo/GNUPlot, Up: Module List Process aviation weather reports in the METAR format. ***************************************************** NAME ==== Geo::METAR - Process aviation weather reports in the METAR format. SYNOPSIS ======== use Geo::METAR; use strict; my $m = new Geo::METAR; $m->metar("KFDY 251450Z 21012G21KT 8SM OVC065 04/M01 A3010 RMK 57014"); print $m->dump; exit; DESCRIPTION =========== METAR reports are available on-line, thanks to the National Weather Service. Since reading the METAR format isn't easy for non-pilots, these reports are relatively useles to the common man who just wants a quick glace at the weather. USAGE ===== How you might use this ---------------------- Here is how you *might* use the Geo::METAR module. One use that I have had for this module is to query the NWS METAR page (using the LWP modules) at http://weather.noaa.gov/cgi-bin/mgetmetar.pl?cccc=KFDY to get an up-to-date METAR. Then, I scan thru the output, looking for what looks like a METAR string (that's not hard in Perl). Oh, KFDY can be any site location code where there is a reporting station. I then pass the METAR into this module and get the info I want. I can then update my home page with the current temperature, sky conditions, or whatnot. Functions --------- The following functions are defined in the AcctInfo module. Most of them are *public*, meaning that you're supposed to use them. Some are private, meaning that you're not supposed to use them - but I won't stop you. Assume that functions are *public* unless otherwise documented. metar() metar() is the function to whwich you should pass a METAR string. It will take care of decomposing it into its component parts converting the units and so on. Example: `$m->metar("KFDY 251450Z 21012G21KT 8SM OVC065 04/M01 A3010 RMK 57014");' debug() debug() toggles debugging messages. By default, debugging is turned *off*. Turn it on if you are developing METAR or having trouble with it. debug() understands all of the folloing: Enable Disable ------ ------- 1 0 'yes' 'no' 'on' 'off' If you contact me for help, I'll likely ask you for some debugging output. Example: `$m->debug(1);' dump() dump() will dump the internal data structure for the METAR in a semi-human readable format. Example: `$m->dump;' version() version() will print out the current version. Example: `print $m->version;' _tokenize() PRIVATE Called internally to break the METAR into its component tokens. _process() PRIVATE Used to make sense of the tokens found in _tokenize(). Variables --------- After you've called metar(), you'd probably like to get at the individual values for things like temperature, dew point, and so on. You do that by accessing individual variables via the METAR object. This section lists those variables and what they represent. If you call dump(), you'll find that it spits all of these out in roughly this order, too. VERSION The version of METAR.pm that you're using. METAR The actual, raw METAR. TYPE Report type: "METAR or SPECI". SITE 4-letter site code. DATE The date on which the report was issued. TIME The time at which the report was issued. MOD Modifier (AUTO/COR) if any. WIND_DIR_ENG The current wind direction in english (Southwest, East, North, etc.) WIND_DIR_DEG The current wind direction in degrees. WIND_KTS The current wind speed in Knots. WIND_MPH The current wind speed in Miles Per Hour. WIND_GUST_KTS The current wind gusting speed in Knots. WIND_GUST_MPH The current wind gusting speed in Miles Per Hour. VISIBILITY Visibility information. WIND Wind information. RUNWAY Runway information. WEATHER Current weather. SKY Current sky conditions. TEMP_C Temperature in Celsius. TEMP_F Temperature in Farenheit. C_DEW Dew point in Celsius. F_DEW Dew point in Farenheit. ALT Altimeter setting (barometric pressure). REMARKS Any remarks in the report. NOTES ===== Test suite is small and incomplete. Needs work yet. Older versions of this module were installed as "METAR" instaed of "Geo::METAR" Adding a find() method. ----------------------- I should add a function called find() which can be passed a big chunk of text (or a ref to one) and a site identifier. It will scan through the text and find the METAR. The result can be fed back into this module for processing. That'd be cool, I think. BUGS ==== There currently aren't any known BUGS (features which don't work as advetised). There are lacking features. See the TODO section for more on that. TODO ==== There is a TODO file included in the Geo::METAR distribution listing the outstanding tasks that I or others have devised. Please check that list before you submit a bug report or request a new feture. It might already be on the TODO list. AUTHOR AND COPYRIGHT ==================== Copyright 1997-2000, Jeremy D. Zawodny Geo::METAR is covered under the GNU Public License (GPL) version 2 or later. The Geo::METAR Web site is located at: http://www.wcnet.org/~jzawodn/perl/Geo-METAR/ CREDITS ======= In addition to my work on Geo::METAR, I've received ideas, help, and patches from the following folks: * Otterboy Random script fixes and initial debugging help * Remi Lefebvre Debian packaging as libgeo-metar-perl.deb. * Mike Engelhart Wind direction naming corrections. * Michael Starling Wind direction naming corrections. * Hans Einar Nielssen Wind direction naming corrections. * Nathan Neulinger Lots of enhancements and corrections. Too many to list here.  File: pm.info, Node: Geo/StormTracker, Next: Geo/StormTracker/Advisory, Prev: Geo/METAR, Up: Module List Perl bundle for working with national weather advisories ******************************************************** NAME ==== Geo::StormTracker - Perl bundle for working with national weather advisories SYNOPSIS ======== See documentation of each module of the bundle. This currently includes the following: Geo::StormTracker::Main Geo::StormTracker::Data Geo::StormTracker::Advisory Geo::StormTracker::Parser DESCRIPTION =========== The Storm-Tracker perl bundle is designed to track weather events using the national weather advisories. The original intent is to track tropical depressions, storms and hurricanes. AUTHOR ====== James Lee Carpenter, Jimmy.Carpenter@chron.com All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Thanks to Dr. Paul Ruscher for his assistance in helping me to understand the weather advisory formats. SEE ALSO ======== Geo::StormTracker::Advisory Geo::StormTracker::Parser Geo::StormTracker::Main Geo::StormTracker::Data perl(1).  File: pm.info, Node: Geo/StormTracker/Advisory, Next: Geo/StormTracker/Data, Prev: Geo/StormTracker, Up: Module List The weather advisory object of the perl Storm-Tracker bundle. ************************************************************* NAME ==== Geo::StormTracker::Advisory - The weather advisory object of the perl Storm-Tracker bundle. SYNOPSIS ======== use Geo::StormTracker::Advisory; #Create a new advisory object for holding #all the various elements of an advisory. $adv_obj=StormTracker::Advisory->new(); #Return the entire advisory as a string. #Internally calls stringify_header and #stringify_body and joins the result. $adv_obj->stringify(); All of the following methods can be used as both access and as assignment methods. The use and functionality of the methods should be obvious. It is important to realize that changes to a given attribute do not affect other attributes. It is the role of the caller to keep the content self consistent. #Obtain the header as a string. $header_string=$adv_obj->stringify_header(); #Change the contents of the header string. #Returns new header contents. $header_string=$adv_obj->stringify_header($header_string); #Obtain the body as a string. $body_string=$adv_obj->stringify_body(); #Change the contents of the body string. #Returns new body contents. $body_string=$adv_obj->stringify_body($body_string); #Obtain the name string. $name=$adv_obj->name(); #Change the name string. #Returns new name string. $name=$adv_obj->name($name); #Obtain the wmo header string. $wmo_header=$adv_obj->wmo_header(); #Change the wmo header string. #Returns new wmo header string. $wmo_header=$adv_obj->wmo_header($wmo_header); #Obtain the advisory number value. $advisory_number=$adv_obj->advisory_number(); #Change the advisory number value. #Returns the new advisory number. $advisory_number=$adv_obj->advisory_number($advisory_number); #Obtain the release time string. $release_time=$adv_obj->release_time(); #Change the release time string. #Returns the new release time string. $release_time=$adv_obj->release_time($release_time); #Obtain the epoch date in seconds. $epoch_date=$adv_obj->epoch_date(); #Change the epoch date. #Returns the new epoch date in seconds. $epoch_date=$adv_obj->epoch_date($epoch_date); #Obtain the weather service string. $weather_service=$adv_obj->weather_service(); #Change the weather service string. #Returns the new weather service string. $weather_service=$adv_obj->weather_service($weather_service); #Obtain the position array or array reference. @position=$adv_obj->position(); or $positon_AR=$adv_obj->position(); #Change the position array. #Returns the new position array or array reference. @position=$adv_obj->position($position_AR); or $position_AR=$adv_obj->position($position_AR); #Obtain the maximum wind value. $max_winds=$adv_obj->max_winds($max_winds); #Change the maximum wind value. #Returns the new maximum wind value. $max_winds=$adv_obj->max_winds($max_winds); #Obtain the minimum central pressure value. $min_central_pressure=$adv_obj->min_central_pressure(); #Change the minimum central pressure value. #Returns the new minimum central pressure value. $min_central_pressure=$adv_obj->min_central_pressure($min_central_pressure) #Determine whether or not the advisory says it is the last one. $is_final=$adv_obj->is_final(); #Change the is_final value. #Returns the new is_final value. $is_final=$adv_obj->min_central_pressure($is_final) DESCRIPTION =========== The Geo::StormTracker::Advisory module is a component of the Storm-Tracker perl bundle. The Storm-Tracker perl bundle is designed to track weather events using the national weather advisories. The original intent is to track tropical depressions, storms and hurricanes. A Geo::StormTracker::Advisory object is designed to contain everything about a single advisory. The Geo::StormTracker::Advisory objects are typically created and populated by the read methods of a Geo::StormTracker::Parser object. CONSTRUCTOR =========== new Creates a `Geo::StormTracker::Advisory' object and returns a blessed reference to it. METHODS ======= stringify Returns the entire advisory. Internally calls stringify_header and stringify_body and joins the result. The remaining methods function as both assignment and access methods. When called with an argument, they act as assignment methods and when called without an argument they act as access methods. When successfully called as assignment methods the return value is that of the newly assigned value. If the assignment is unsuccessful the return value will be undefined. The attribute set/retrieved is identical to the method name. stringify_header ([STRING]) Returns a string value. stringify_body ([STRING]) Returns a string value. wmo_header ([STRING]) Returns a string value. advisory_number ([VALUE]) Returns a string value. epoch_date ([STRING]) Returns a string value. weather_service ([STRING]) Returns a string value. position ([ARRAY_REF]) Returns an array value when called in array context and an array reference when called in a scalar context. max_winds ([VALUE]) Returns a string value. is_final ([BOOLEAN]) Returns a boolean value. AUTHOR ====== James Lee Carpenter, Jimmy.Carpenter@chron.com All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Thanks to Dr. Paul Ruscher for his assistance in helping me to understand the weather advisory formats. SEE ALSO ======== Geo::StormTracker::Main Geo::StormTracker::Data Geo::StormTracker::Parser perl(1).  File: pm.info, Node: Geo/StormTracker/Data, Next: Geo/StormTracker/Main, Prev: Geo/StormTracker/Advisory, Up: Module List The weather event object of the perl Storm-Tracker bundle. ********************************************************** NAME ==== Geo::StormTracker::Data - The weather event object of the perl Storm-Tracker bundle. SYNOPSIS ======== use Geo::StormTracker::Data; #The only argument is the path for the data files of #this new data object. #If the directory does not exist it will fail. ($data_object,$error)=Geo::StormTracker::Data->new('/data/1999/15'); #The shiny_new method expects to create the last directory level of the path. #If the full path already exists it will fail. #The 2nd, 3rd, and 4th arguments are the region code, year, and event number respectively. ($data_object,$error)=Geo::StormTracker::Data->shiny_new('/data/1999/15', 'NT', 1999, 15); #The insert_advisory method inserts an advisory object #into the data object. #Unless the second argument is true, inserting an #advisory with the same advisory number as a previously #inserted advisory will fail. #Second argument can be thought of as a force flag. ($success,$error)=$data_object->insert_advisory($adv_obj,[0|1]) #Determine the last known position for this weather event. $position_AR=$data_object->current_position() ($long,$long_dir,$lat,$lat_dir)=@{$position_AR}; #The postion_track method will return an #array of position array references. #sorted in advisory number order. #The position from the advisory with the smallest #advisory number will be in element 0 of @track. @track=$data_object->position_track(); #Alternatively. $track_AR=$data_object->position_track(); @track=@{$track_AR}; #Retrieve the most current advisory available #for this data object. $adv_obj=$data_object->current_advisory; #Is this weather event still occurring? #$set_to will contain true(1) or false(0) #if called without any arguments. #Can be used as an assignment operator #if given an argument. #When used as an assignment operator it #returns the value to which it was set #if successful and undef otherwise. ($set_to,$error)=$data_object->is_active([[0|1]); #The all_advisory_objects method returns an array of #every weather event advisory available in the referenced #data object. #The order is identical #to that returned by the position_track method. @all_advisory_objects=$data_object->all_advisories(); #Alternatively $all_advisory_objects_AR=$data_object->all_advisories(); #The advisory_by_number method returns an advisory #object for the advisory number given as an argument. #If the advisory doesn't exist the method returns undef. $adv_obj_15=$data_object->advisory_by_number(15); #Returns the path to the data file directory of #this object. $path=$data_object->get_path(); #Returns the region code corresponding to the data object. $region=$data_object->get_region(); #Returns the year corresponding to the data object. $year=$data_object->get_year(); #Returns the event number corresponding to the data object. $event_number=$data_object->get_event_number(); DESCRIPTION =========== The `Geo::StormTracker::Data' module is a component of the Storm-Tracker perl bundle. The Storm-Tracker perl bundle is designed to track weather events using the national weather advisories. The original intent is to track tropical depressions, storms and hurricanes. There should be a `Geo::StormTracker::Data' object for each weather event being stored and/or tracked. The `Geo::StormTracker::Data' objects are managed by `Geo::StormTracker::Main'. CONSTRUCTOR =========== new (PATHNAME) Creates a Geo::StormTracker::Data object. This constructor method returns an array of the form (OBJECT,ERROR). OBJECT being the newly created object if successful, and ERROR being any errors encountered during the attempt. The data set for this object is assumed to be contained within the directory specified by the mandatory PATHNAME argument. In the event that a directory with the given PATHNAME does not exist, the method will fail. Check to see if the OBJECT returned is defined. The motivation for having two constructor methods instead of one, is to help the caller maintain data integrity. shiny_new (PATHNAME, REGION, YEAR, EVENT_NUMBER) Creates a Geo::StormTracker::Data object. This constructor method returns an array of the form (OBJECT,ERROR). OBJECT being the newly created object if successful, and ERROR being any errors encountered during the attempt. The data set for this object will be placed within the directory specified by the mandatory PATHNAME argument. The method will only succeed if the directory with the given PATHNAME does not already exist. The shiny_new method only knows how to create the last level directory. The constructor does not attempt to recursively create a new directory and therefore will never succeed unless every directory in the path except the last one already exists. Even then the creation of a new directory can fail due to permission problems. It is wise to always check to insure that the OBJECT returned is defined. The motivation for having two constructor methods instead of one, is to help the caller maintain data integrity. The mandatory REGION, YEAR, and EVENT_NUMBER will be persistently stored within the Geo::StormTracker::Data object. Their values can be accessed via the get_region, get_year, and get_event_number methods of Geo::StormTracker::Data objects. The REGION, YEAR, and EVENT_NUMBER are not implicitly related to the PATH in any way. METHODS ======= insert_advisory (ADVISORY_OBJECT) Attempts to insert a `Geo::StormTracker::Advisory' object into the `Geo::StormTracker::Data' object being referenced. The method returns an array of the form (SUCCESS,ERROR). SUCCESS being a boolean value indicating whether or not the operation was successful and ERROR being a scalar string reporting what error was encountered if any. current_position When called in scalar context current_position returns a reference to a position array. When called in array context current_position returns a position array. The position array specifies the longitude and latitude of the most recent weather advisory available for this `Geo::StormTracker::Data' object. The position array is of the form (LONGITUDE,N or S,LATITUDE, W or E). If the `Geo::StormTracker::Data' object being referenced contains no advisories at all the return value will be undefined. position_track When called in scalar context position_track returns a reference to an array of position array references. When called in array context position_track returns an array of position array references. There is a position returned for each advisory within the `Geo::StormTracker::Data' object being referenced. The position arrays returned are sorted by advisory number with the smallest advisory number first. The position arrays are identical in format to that returned by the current_position method. current_advisory Returns a reference to the `Geo::StormTracker::Advisory' object within the `Geo::StormTracker::Data' object that has the greatest advisory number. If the `Geo::StormTracker::Data' object being referenced contains no advisories at all the return value will be undefined. all_advisories When called in scalar context all_advisories returns a reference to an array of advisory objects. When called in array context all_advisories returns an array of advisory objects. The array of advisories is sorted by advisory number in the same order as that used by the position_track method. The advisory with the smallest advisory number will be given first. If the `Geo::StormTracker::Data' object being referenced contains no advisories at all the return value will be undefined. advisory_by_number (NUM) Returns a reference to the advisory object with the same advisory number as given by the mandatory NUM argument. If the `Geo::StormTracker::Data' object being referenced does not contain an advisory with the requested advisory number the return value will be undefined. get_path Returns the path passed to the new method upon creation of the referenced `Geo::StormTracker::Data' object. get_region Returns the region passed to the shiny_new method during the first creation of the referenced `Geo::StormTracker::Data' object. get_year Returns the 4 digit year passed to the shiny_new method during the first creation of the referenced `Geo::StormTracker::Data' object. get_event_number Returns the event number passed to the shiny_new method during the first creation of the referenced `Geo::StormTracker::Data' object. is_active ([BOOLEAN]) When called with a boolean argument is_active attempts to define the referenced `Geo::StormTracker::Data' object as active or inactive. is_active returns the array (SET_TO,ERROR). If successful the SET_TO string indicates the value the state to which the data_object was set. If unsuccessful SET_TO will be undefined and ERROR will contain the reason for the failure. When is_active is called without an argument it will return the current state of the `Geo::StormTracker::Data' object being referenced. AUTHOR ====== Jimmy Carpenter, Jimmy.Carpenter@chron.com All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Thanks to Dr. Paul Ruscher for his assistance in helping me to understand the weather advisory formats. =head1 SEE ALSO Geo::StormTracker::Main Geo::StormTracker::Parser Geo::StormTracker::Advisory perl(1).