Ports(3)

NAME
FreeBSD::Ports - Class for parsing FreeBSD's Ports INDEX

WARNING!
This is a very early version of this module. The interface to the class may be changed in the future. The documentation needs improving.

Consequently, suggestions, comments and patches are extremely welcome! I believe the correct place to discuss this module is the freebsd-doc mailing list at freebsd-doc@freebsd.org.

SYNOPSIS
  # Describe ports maintained by tom@FreeBSD.org, sorted alphabetically
  use FreeBSD::Ports;
  my $ports = tie my %port, 'FreeBSD::Ports', '/usr/ports/INDEX';
  $ports->maintainer('tom@FreeBSD.org');
  $ports->sort('alpha');
  foreach my $p (values %port) {
      print $p->as_ascii,"\n";
  }
  # How many ports are there currently?
  use FreeBSD::Ports;
  my $ports = tie my %port, 'FreeBSD::Ports', '/usr/ports/INDEX';
  my $count = scalar keys %port;
  print "There are $count ports\n";
  # List ports containing 'MPEG' in their comment and present in the
  # 'audio' category?
  use FreeBSD::Ports;
  my $ports = tie my %port, 'FreeBSD::Ports', '/usr/ports/INDEX';
  $ports->category('audio');
  $ports->match('mpeg', 'COMMENT', 1);
  foreach my $name (keys %port) {
      print "$name\n";
  }
  # Any ports which are under the 'www' or 'net' category
  use FreeBSD::Ports;
  my $all_ports = tie my %port, 'FreeBSD::Ports';
  my $www_ports = tie my(%www_port), $all_ports;
  $www_ports->category('www');
  my $net_ports = tie my(%net_port), $all_ports;
  $net_ports->category('net');
  my %www_or_net_port;
  while ( my($key, $value) = (each(%www_port), each(%net_port)) ) {
      $www_or_net_port{$key} = $value;
  }

DESCRIPTION
`FreeBSD::Ports' is a simple interface to the INDEX file used in FreeBSD's ports collection.

This class uses Perl's tie interface. See the perltie manpage for more information.

For further information, or to obtain the latest version of this module, see <URL:http://people.FreeBSD.org/~tom/portpm/>.

METHODS
Read and parse an INDEX file. `$filename' is the name of the file containing the index. If undefined, /usr/ports/INDEX is used.

`$class' should be the name of the class (`FreeBSD::Ports') or another `FreeBSD::Ports' object to be cloned.

`%port' is a hash whose keys are the names of the ports within the index. The value of each key is a FreeBSD::Ports::Port object.

`$ports' is an object which can be accessed using the methods within this class. Returns the FreeBSD::Ports::Port object whose name is `$port_name' if that object exists. Selects only those ports whose maintainer's e-mail address is `$email'. Addresses are matched case insensitively. Selects only those ports whose primary category is `$category_name'. The primary category is the first category in which a port is listed. This represents the directory under /usr/ports in which a port is stored. Category names are matched case insensitively. Selects only those ports which are present in the category named `$category_name'. In this case, category names are matched case sensitively. Selects only those ports which have a run dependency on the port represented by `$port'.

`$port' is either the name of a port or a FreeBSD::Ports::Port object. Selects only those ports which have a build dependency on `$port'. Selects those ports which have any type of dependency on `$port'. Sorts the selected ports. `$method' specifies how the ports should be sorted. alpha means the ports should be sorted alphabetically, from A to Z. rev_alpha means the ports should be sorted alphabetically in reverse, from Z to A. Sorting is performed case sensitively.

`$field' specifies which property of the ports should be used to sort by. DISTRIBUTION_NAME is used if this value is undefined. One of the following properties is usually selected:
Selects only those ports where `$field' matches `$term'. The values which can be used for `$field' are the same as those used for the `sort' method. However, for this method `COMMENT' is used if `$field' is undefined.

`$term' is evaluated as a regular expression. If `$insensitive' is defined, the expression is evaluated case insensitively. If undefined, case sensitive evalutaion is used.

CREDITS
This module is written by Tom Hukins <tom@FreeBSD.org>.

Thanks to Nik Clayton for encouragement and assistance.

COPYRIGHT
This module is distributed under the same license as FreeBSD <http://www.FreeBSD.org/copyright/freebsd-license.html>.