New script (and it's README) for searching the ports tree. Add this script

to the main README.

This was originally submitted as a port but was added to Tools/scripts
instead at alex's suggestion.

PR:		20863
Approved by:	alex

Tools/scripts/README

@@ -19,6 +19,9 @@ prpatch - just does `patch $1 < pr-patch' (pr-patch is created by getpr)
 prdone  - checks in the port, attempting to fill out the commit message using
           information from the problem report and then takes you into edit-pr
           so you don't forget to close the PR.
+portsearch - A utility for searching the ports tree. It allows more detailed
+             search criteria than ``make search key=<string>'' and accepts
+             all perl(1) regular expressions.
 
 ----------------------------------------------------------------------
 
@@ -94,6 +97,45 @@ Please be warned, that the this only means that the ports listed by the script
 required for correct removal of GNOME shared directories, not for the port
 functionality, so actual {RUN,LIB}_DEPENDS may have more entries.
 
+----------------------------------------------------------------------
+portsearch - A utility for searching the ports tree.
+
+     portsearch is a utility to for searching of the ports tree. It permits
+     much more detailed searches to be performed than ``make search
+     key=<string>'' by allowing you to specify which field(s) to search. It
+     also supports all valid perl(1) regular expressions for pattern matching.
+
+     portsearch displays matching ports in the same format as ``make search''
+     and also displays the number of matching ports found.
+
+     The following command line options are supported:
+
+	   -h	      Prints a multi-line help message and exits
+
+	   -n name    Search for name in the name field
+
+	   -p path    Search for path in the path field
+
+	   -i info    Search for info in the comments field
+
+	   -m maint   Search for maint in the Maintainer field
+
+	   -x index   Search for index in the category field
+
+	   -b b_deps  Search for b_deps in the build-depends field
+
+	   -r r_deps  Search for r_deps in the run-depends field
+
+	   -d deps    Search for deps in the both the build and run dependency
+		      fields. This option behaves differently to the other op-
+		      tions, see the EXAMPLES section
+
+	   -f file    Use the index file file instead of /usr/ports/INDEX
+
+     All searches are case-insensitive
+
+See the file README.portsearch for further information.
+
 ----------------------------------------------------------------------
 
 NOTE: These scripts need work and are *NOT* safe to use unless you know

Tools/scripts/README.portsearch

@@ -0,0 +1,117 @@
+
+PORTSEARCH(1)		FreeBSD General Commands Manual 	 PORTSEARCH(1)
+
+NAME
+     portsearch - A utility for searching the ports tree.
+
+SYNOPSIS
+     portsearch [-h] [-n name] [-p path] [-i info] [-m maint] [-x index] [-b
+     b_deps] [-r r_deps] [-d deps] [-f file]
+
+DESCRIPTION
+     portsearch is a utility to for searching of the ports tree. It permits
+     much more detailed searches to be performed than ``make search
+     key=<string>'' by allowing you to specify which field(s) to search. It
+     also supports all valid perl(1) regular expressions for pattern matching.
+
+     portsearch displays matching ports in the same format as ``make search''
+     and also displays the number of matching ports found.
+
+     The following command line options are supported:
+
+	   -h	      Prints a multi-line help message and exits
+
+	   -n name    Search for name in the name field
+
+	   -p path    Search for path in the path field
+
+	   -i info    Search for info in the comments field
+
+	   -m maint   Search for maint in the Maintainer field
+
+	   -x index   Search for index in the category field
+
+	   -b b_deps  Search for b_deps in the build-depends field
+
+	   -r r_deps  Search for r_deps in the run-depends field
+
+	   -d deps    Search for deps in the both the build and run dependency
+		      fields. This option behaves differently to the other op-
+		      tions, see the EXAMPLES section
+
+	   -f file    Use the index file file instead of /usr/ports/INDEX
+
+     All searches are case-insensitive
+
+     /usr/ports/INDEX is not updated everytime a change is made to the ports
+     tree so in order to get the most accurate results from using portsearch
+     you should consider rebuilding the index thus:
+
+	   # cd /usr/ports && make index
+
+FILES
+     /usr/ports/INDEX  The ports master index file
+
+EXAMPLES
+     Find all ports whose name contains "emacs":
+
+	   portsearch -n emacs
+
+     Restrict the search to only those ports whose name begins with "emacs" by
+     anchoring the match to the beginning of the name:
+
+	   portsearch -n ^emacs
+
+
+     Find all the ports in the textproc, print, and www categories that are
+     maintained by Nik or Jim and have a run-time dependency on the tidy(1)
+     port:
+
+	   portsearch -x '(textproc|print|www)' -m '(nik|jim)' -r tidy
+
+     Note that the regular expression operators have to be quoted to protect
+     them from the shell.
+
+     The behaviour of the -d deps option is slightly different to the other
+     search options. If used it makes portsearch search both the build- and
+     run-dependency fields. If the -b b_deps and/or the -r r_deps are used as
+     well then they are ignored; the deps pattern is used to search both
+     fields.
+
+     Note that
+
+	   portsearch -d foobar
+
+     is not the same as
+
+	   portsearch -b foobar -r foobar
+
+     Normally all the options are logically ANDed together so in the above ex-
+     ample a port would need to have both a build and run dependency on
+     "foobar" to match, whereas the -d option logically ORs the two dependency
+     fields so that only a single dependency is required for a match. This is
+     primarily to provide an easy way of generating a list of all the depen-
+     dencies of a port; handy if the maintainer is making changes and needs to
+     know which other ports may be affected.
+
+DIAGNOSTICS
+     portsearch exits 0 on success or 1 if a help message was output.
+
+SEE ALSO
+     perlre(1),  ports(7)
+
+AUTHORS
+     Mark Ovens <marko@freebsd.org>
+
+BUGS
+     The "Index" field would probably be better named "Category" but it has
+     been left unchanged to be consistent with ``make search''.
+
+     perl(1) treats ``-'' as a word boundary so when a dependency field is
+     wrapped over more than one line a port name may get split like this:
+
+	   gettext-0.10.35 jpeg-6b libproplist-0.10.1 libungif-
+	   4.1.0 png-1.0.6
+
+
+FreeBSD 			 13 June 2000				     2

Tools/scripts/portsearch

@@ -0,0 +1,190 @@
+#!/usr/bin/perl
+#-
+# Copyright (c) 2000 Mark Ovens
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer
+#    in this position and unchanged.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+#      $Id$
+#
+
+
+# Each port record in INDEX contains 10 fields, delimited by ``|'', some
+# of which may be empty. The fields are:
+#
+# distribution-name|port-path|installation-prefix|comment| \
+# description-file|maintainer|categories|build deps|run deps|www site  
+
+
+use strict;
+use Getopt::Std;
+use vars qw/ $key @list %fields %list %opts /;
+
+#
+# Global variables
+#
+
+my $VERSION = "1.0";
+my $file  = "/usr/ports/INDEX";
+my $match  = 1;
+my $count = 0;
+
+# We only need 7 of the 10 fields in a record; define which ones in a
+# hash slice to ignore the un-needed ones. This also makes it easy to
+# add or remove fields in the future.
+
+@fields{qw(n p i m x b r)} = (0, 1, 3, 5, 6, 7, 8);
+
+#
+# Print a basic help message
+#
+
+sub usage() {
+    print(STDERR "
+Usage: portsearch [-h] [-n name] [-p path] [-i info] [-m maint] [-x index]
+		[-b b_deps] [-r r_deps] [-d deps] [-f file]
+
+");
+} # usage()
+
+#
+# Print a more verbose help message
+#
+
+sub help() {
+    print(STDERR "portsearch $VERSION - A utility for searching the ports tree.
+
+Options:
+
+  -n name	Search for \"name\" in name of ports
+  -p path	Search for \"path\" in location of ports
+  -i info	Search for \"info\" in ports COMMENT files
+  -m maint	Search for \"maint\" in ports Maintainer
+  -x index	Search for \"index\" in ports categories
+  -b b_deps	Search for \"b_deps\" in build depends of ports
+  -r r_deps	Search for \"r_deps\" in run depends of ports
+  -d deps	Search for \"deps\" in both build & run depends of ports
+  -f file	Use \"file\" instead of /usr/ports/INDEX
+  -h		Print this message and exit
+
+Report bugs to <marko\@freebsd.org>.
+
+");
+} # help()
+
+#
+# The program proper
+#
+
+MAIN: {
+				# No command-line args
+    if ($#ARGV == -1) {
+	usage();
+	exit(1);
+    }
+
+    getopt('fnpimxbrd', \%opts);
+				# Command-line args, but without options
+    if (keys(%opts) == 0 ) {
+	usage();
+	exit(1);
+    }
+				# If ``-h'', ignore any other options
+    if (defined($opts{"h"})) {
+	help();
+	exit(1);
+    }
+				# A different INDEX file
+    if (defined($opts{"f"})) {
+	$file = $opts{"f"};
+    }
+				# If ``-d'' used we don't want ``-b'' & ``-r''
+    if (defined($opts{"d"})) {
+	delete $opts{"b"};
+	delete $opts{"r"};
+    }
+				# Finished with it now so remove it from hash
+    delete $opts{"f"};
+	
+    open(INDEX, "$file") || die "Unable to open $file";
+
+    while (<INDEX>) {
+	chomp;
+	@list = split(/\|/);
+
+        $match = 1;
+				# All searches are case-insensitive! 
+				# For ``-d'' search both build & run depends.
+				# Only fail to match if not found in either.
+	foreach $key (keys (%opts)) {
+	    if ($key eq "d") {
+		if ($list[$fields{"b"}] !~ m#$opts{$key}#i &&
+				  $list[$fields{"r"}] !~ m#$opts{$key}#i) {
+		    $match = 0;
+		    last;
+		    }
+	    } else {
+		if ($list[$fields{$key}] !~ m#$opts{$key}#i) {
+		    $match = 0;
+		    last;
+		}
+	    }
+	} # foreach
+
+	if ($match == 1) {
+	    $count++;
+	    write;
+	}
+
+    } # while
+
+    close(INDEX);
+
+    print ("Number of matching ports = $count\n\n");
+
+} # MAIN
+
+
+format STDOUT =
+
+Port:	@<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+$list[0]
+Path:	@<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+$list[1]
+Info:	^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+$list[3]
+~~      ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+$list[3]
+Maint:	@<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+$list[5]
+Index:	@<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+$list[6]
+B-deps:	^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+$list[7]
+~~      ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+$list[7]
+R-deps:	^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+$list[8]
+~~      ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
+$list[8]
+
+.