port, portindex: add portgroups as a searchable field and selector

doc/port-info.1

@@ -26,17 +26,19 @@ port-info \- Return information about the given ports\&.
 .nf
 \fBport\fR [\fB\-q\fR] [\fB\-D\fR \fIportdir\fR] \fBinfo\fR
      [\-\-categories|\-\-category] [\-\-conflicts] [\-\-depends] [\-\-depends_fetch]
-     [\-\-depends_extract] [\-\-depends_build] [\-\-depends_lib] [\-\-depends_run]
+     [\-\-depends_extract] [\-\-depends_patch] [\-\-depends_build] [\-\-depends_lib]
+     [\-\-depends_run] [\-\-depends_test]
      [\-\-description] [\-\-epoch] [\-\-fullname] [\-\-heading] [\-\-homepage] [\-\-index]
      [\-\-license] [\-\-line] [\-\-long_description] [\-\-maintainer|\-\-maintainers]
-     [\-\-name] [\-\-patchfiles] [\-\-platform|\-\-platforms] [\-\-portdir] [\-\-pretty]
+     [\-\-name] [\-\-patchfiles] [\-\-platform|\-\-platforms] [\-\-portdir]
+     [\-\-portgroup|\-\-portgroups] [\-\-pretty]
      [\-\-replaced_by] [\-\-revision] [\-\-subports] [\-\-variant|\-\-variants]
      [\-\-version]
      [[\fIportname\fR | \fIpseudo\-portname\fR | \fIport\-expressions\fR | \fIport\-url\fR]]
 .fi
 .SH "DESCRIPTION"
 .sp
-\fBport info\fR prints information about the given ports\&. Specifying at least one of the options limits the output to the corresponding field\&. If no fields are specified, a useful default set consisting of name, epoch, version, revision, categories, replaced_by, variants, description, homepage, dependencies, platforms, license, and maintainers is shown\&.
+\fBport info\fR prints information about the given ports\&. Specifying at least one of the options limits the output to the corresponding field\&. If no fields are specified, a useful default set consisting of name, epoch, version, revision, categories, replaced_by, variants, description, homepage, dependencies, portgroups, platforms, license, and maintainers is shown\&.
 .SH "OPTIONS"
 .sp
 The following options do not select fields for the output but change how the information is obtained or formatted:
@@ -69,7 +71,7 @@ List the categories of a port\&.
 List other ports that cannot be active at the same time as the given port\&.
 .RE
 .PP
-\fB\-\-depends\fR, \fB\-\-depends_fetch\fR, \fB\-\-depends_extract\fR, \fB\-\-depends_build\fR, \fB\-\-depends_lib\fR, \fB\-\-depends_run\fR
+\fB\-\-depends\fR, \fB\-\-depends_fetch\fR, \fB\-\-depends_extract\fR, \fB\-\-depends_patch\fR, \fB\-\-depends_build\fR, \fB\-\-depends_lib\fR, \fB\-\-depends_run\fR, \fB\-\-depends_test\fR
 .RS 4
 List the specified dependencies of a port\&.
 \fB\-\-depends\fR
@@ -137,6 +139,11 @@ List the platforms supported by a port\&. This field exists for historical reaso
 Print the path to a port\(cqs directory relative to the port tree root\&.
 .RE
 .PP
+\fB\-\-portgroup\fR, \fB\-\-portgroups\fR
+.RS 4
+List the PortGroups used by a port, including their versions\&.
+.RE
+.PP
 \fB\-\-replaced_by\fR
 .RS 4
 List the name of the port that replaces a port, if any\&.

doc/port-info.1.txt

@@ -11,10 +11,12 @@ SYNOPSIS
 [cmdsynopsis]
 *port* [*-q*] [*-D* 'portdir'] *info*
      [--categories|--category] [--conflicts] [--depends] [--depends_fetch]
-     [--depends_extract] [--depends_build] [--depends_lib] [--depends_run]
+     [--depends_extract] [--depends_patch] [--depends_build] [--depends_lib]
+     [--depends_run] [--depends_test]
      [--description] [--epoch] [--fullname] [--heading] [--homepage] [--index]
      [--license] [--line] [--long_description] [--maintainer|--maintainers]
-     [--name] [--patchfiles] [--platform|--platforms] [--portdir] [--pretty]
+     [--name] [--patchfiles] [--platform|--platforms] [--portdir]
+     [--portgroup|--portgroups] [--pretty]
      [--replaced_by] [--revision] [--subports] [--variant|--variants]
      [--version]
      [['portname' | 'pseudo-portname' | 'port-expressions' | 'port-url']]
@@ -25,7 +27,7 @@ DESCRIPTION
 the options limits the output to the corresponding field. If no fields are
 specified, a useful default set consisting of name, epoch, version, revision,
 categories, replaced_by, variants, description, homepage, dependencies,
-platforms, license, and maintainers is shown.
+portgroups, platforms, license, and maintainers is shown.
 
 OPTIONS
 -------
@@ -52,7 +54,7 @@ The rest of the options affect which fields will be given in the output:
 *--conflicts*::
     List other ports that cannot be active at the same time as the given port.
 
-*--depends*, *--depends_fetch*, *--depends_extract*, *--depends_build*, *--depends_lib*, *--depends_run*::
+*--depends*, *--depends_fetch*, *--depends_extract*, *--depends_patch*, *--depends_build*, *--depends_lib*, *--depends_run*, *--depends_test*::
     List the specified dependencies of a port. *--depends* is a shorthand option
     for all other *--depends_** options.
 
@@ -93,6 +95,9 @@ The rest of the options affect which fields will be given in the output:
 *--portdir*::
     Print the path to a port's directory relative to the port tree root.
 
+*--portgroup*, *--portgroups*::
+    List the PortGroups used by a port, including their versions.
+
 *--replaced_by*::
     List the name of the port that replaces a port, if any.
 

doc/port-search.1

@@ -134,6 +134,33 @@ in the name, but not the description\&.
 Test the search string against the path of the directory that contains the port\&.
 .RE
 .PP
+\fB\-\-portgroup\fR, \fB\-\-portgroups\fR
+.RS 4
+Search for ports that use a given PortGroup\&. The pattern has the optional form
+\fINAME@VERSION\fR, where either half may be omitted\&. For example,
+\fBport search \-\-portgroup python\fR
+prints all ports using any version of the python PortGroup, while
+\fBport search \-\-portgroup python@1\&.0\fR
+restricts the match to ports using version 1\&.0 of that PortGroup\&. The form
+\fB\-\-portgroup @1\&.0\fR
+matches any PortGroup whose version is 1\&.0\&.
+.sp
+The pattern on each side of the
+\fI@\fR
+is interpreted according to the selected matching style (\fB\-\-glob\fR
+by default, or
+\fB\-\-exact\fR,
+\fB\-\-regex\fR)\&. Unlike other fields, matching is performed against each portgroup entry individually rather than against the serialized list, so
+\fB\-\-exact \-\-portgroup python\fR
+works as expected\&.
+.sp
+There is also a pseudo\-portname selector
+\fBportgroup:python\fR
+available for use with
+\fBport-echo\fR(1)
+and other commands\&.
+.RE
+.PP
 \fB\-\-variant\fR, \fB\-\-variants\fR
 .RS 4
 Search for variant names\&.

doc/port-search.1.txt

@@ -98,6 +98,23 @@ Field selection
     Test the search string against the path of the directory that contains the
     port.
 
+*--portgroup*, *--portgroups*::
+    Search for ports that use a given PortGroup. The pattern has the optional
+    form 'NAME@VERSION', where either half may be omitted. For example, *port
+    search --portgroup python* prints all ports using any version of the
+    python PortGroup, while *port search --portgroup pass:[python@1.0]*
+    restricts the match to ports using version 1.0 of that PortGroup. The
+    form *--portgroup @1.0* matches any PortGroup whose version is 1.0.
++
+The pattern on each side of the '@' is interpreted according to the selected
+matching style (*--glob* by default, or *--exact*, *--regex*). Unlike other
+fields, matching is performed against each portgroup entry individually rather
+than against the serialized list, so *--exact --portgroup python* works as
+expected.
++
+There is also a pseudo-portname selector *portgroup:python* available for use
+with man:port-echo[1] and other commands.
+
 *--variant*, *--variants*::
     Search for variant names.
 

doc/port.1

@@ -314,6 +314,95 @@ or
 .sp -1
 .IP \(bu 2.3
 .\}
+\fIdepends_lib\fR
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIdepends_build\fR
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIdepends_run\fR
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIdepends_fetch\fR
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIdepends_extract\fR
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIdepends_patch\fR
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIdepends_test\fR
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIdepends\fR
+(shorthand for all depends_* selectors)
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
 \fIlicense\fR
 .RE
 .sp
@@ -325,9 +414,46 @@ or
 .sp -1
 .IP \(bu 2.3
 .\}
+\fIreplaced_by\fR
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
 \fIportdir\fR
 .RE
 .sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIportgroup\fR
+or
+\fIportgroups\fR
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIsubport\fR
+or
+\fIsubports\fR
+.RE
+.sp
 Other pseudo\-portname selectors match ports which have a particular relationship to another port\&. These will match ports that are direct or recursive dependencies or dependents of the given portname:
 .sp
 .RS 4
@@ -385,6 +511,17 @@ Other pseudo\-portname selectors match ports which have a particular relationshi
 \fIrdependentof\fR
 .RE
 .sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIsubportof\fR
+.RE
+.sp
 Search strings that will expand to a set of matching ports can be constructed based on the "\fIpseudo\-portname selector\fR":regex combination used\&. \fIportnames\fR containing valid UNIX glob patterns will also expand to the set of matching ports\&. Any action passed to port will be invoked on each of them\&.
 .sp
 For example:

doc/port.1.txt

@@ -73,8 +73,19 @@ matches the given regular expression. Usage is: selector:regex
     - 'description'
     - 'long_description'
     - 'homepage'
+    - 'depends_lib'
+    - 'depends_build'
+    - 'depends_run'
+    - 'depends_fetch'
+    - 'depends_extract'
+    - 'depends_patch'
+    - 'depends_test'
+    - 'depends' (shorthand for all depends_* selectors)
     - 'license'
+    - 'replaced_by'
     - 'portdir'
+    - 'portgroup' or 'portgroups'
+    - 'subport' or 'subports'
 
 Other pseudo-portname selectors match ports which have a particular
 relationship to another port. These will match ports that are direct or
@@ -86,6 +97,7 @@ recursive dependencies or dependents of the given portname:
     - 'rdepends'
     - 'dependentof'
     - 'rdependentof'
+    - 'subportof'
 
 Search strings that will expand to a set of matching ports can be constructed
 based on the "'pseudo-portname selector'":regex combination used. 'portnames'