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 perltie for more information.

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

METHODS

$ports = tie my %port, $class, $filename

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.

$ports->maintainer($email)

Selects only those ports whose maintainer's e-mail address is $email. Addresses are matched case insensitively.

$ports->primary_category($category_name)

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.

$ports->category($category_name)

Selects only those ports which are present in the category named $category_name. In this case, category names are matched case sensitively.

$ports->run_depends($port)

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.

$ports->build_depends($port)

Selects only those ports which have a build dependency on $port.

$ports->depends($port)

Selects those ports which have any type of dependency on $port.

$ports->sort($method, $field)

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:

$ports->match($term, $field, $insensitive)

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, Martin Heinen and Lars Thegler for encouragement, assistance and patches.

COPYRIGHT

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

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 367:

You forgot a '=back' before '=head1'