path: root/man/qatom.1

.\" generated by mkman.py, please do NOT edit!
.TH qatom "1" "Jan 2024" "Gentoo Foundation" "qatom"
.SH NAME
qatom \- split atom strings
.SH SYNOPSIS
.B qatom
\fI[opts] <pkg>\fR
.SH DESCRIPTION
\fIqatom\fR parses strings into atoms and optionally compares them.  The
parsing into atoms results in CATEGORY, PN (package name), PV (package
version), PR (package revision), SLOT and REPO.  Next to these version
qualifiers (e.g.\ >, <, or =) and optional * suffix are extracted.  All
but PN are optional.

Comparison of atoms returns the relationship between two parsed atoms.
\fIqatom\fR does not allow to test conditions.  It is possible to
perform multiple comparisons by simply adding more arguments.
Comparisons are, however, always performed two by two, so there must be
an even count of arguments to the compare function.

The \fIqatom\fR applet is a direct wrapper around the atom parsing
functionalities used by various other applets.  As such this applet
allows easy testing or atom parsing and comparison behaviour.
.SH OPTIONS
.TP
\fB\-F\fR \fI<arg>\fR, \fB\-\-format\fR \fI<arg>\fR
Specify a custom  output  format.  The default format is
.nf
%{CATEGORY} %{PN} %{PV} %[PR] %[SLOT] %[pfx] %[sfx]
.fi
Conversion specifiers start with a \fI%\fR symbol and are followed
by either \fI{\fR or \fI[\fR.  Next is the name of the field to
expand, followed by a matching \fI}\fR or \fI]\fR.  The difference
between \fI{\fR and \fI[\fR is that the latter is only printed if
the field referred is set, while the former prints \fI<unset>\fR in
that case.

The following fields are supported, which are inline with the
variables from \fBebuild\fR(5).
.RS
.IP CATEGORY
The category of the package.
.IP P
The package name and version without the ebuild revision.
.IP PN
The package name.
.IP PV
The package version without the ebuild revision.
.IP PVR
The package version including ebuild revision, which is also printed
when zero, unlike for \fIPF\fR.
.IP PF
The package name, version and revision when not zero.  Thus, a zero
revision \fI\-r0\fR is not printed.
.IP PR
The ebuild revision, when force printed, outputs \fI\-r0\fR when unset.
.IP SLOT
The package slot, when force printed, outputs \fI\-\fR when unset.
.IP REPO
The package repository.
.IP pfx
The package prefixes, that is version specifiers.
.IP sfx
The package suffices, currently that is just the asterisk.
.RE
.TP
\fB\-c\fR, \fB\-\-compare\fR
Compare two atoms.
.TP
\fB\-s\fR, \fB\-\-scompare\fR
Compare two atoms in the given order data, query.
.TP
\fB\-p\fR, \fB\-\-print\fR
Print reconstructed atom.
.TP
\fB\-l\fR, \fB\-\-lookup\fR
Lookup atom in tree.
.TP
\fB\-\-root\fR \fI<arg>\fR
Set the ROOT env var.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Force all expansions, basically treat all \fI[\fR like \fI{\fR.
.TP
\fB\-q\fR, \fB\-\-quiet\fR
Ignored for compatibility with other qapplets.
.TP
\fB\-C\fR, \fB\-\-nocolor\fR
Ignored for compatibility with other qapplets.
.TP
\fB\-\-color\fR
Force color in output.
.TP
\fB\-h\fR, \fB\-\-help\fR
Print this help and exit.
.TP
\fB\-V\fR, \fB\-\-version\fR
Print version and exit.
.SH "ANTISLOT"
A feature present in portage-utils is the so-called antislot, and is
activated by starting the atom with a carrot (^), in place of the
blocker bang (!).  The antislot is similar to the inversing behaviour of
a blocker, but only operates on SLOT and SUBSLOT, and requires SLOT to
be available, e.g. it won't match unset SLOT (NULL).

The antislot is mostly useful with dependencies and is best described
with an example.  Consider a perl upgrade from \fIperl:0/5.28\fR to
\fIperl:0/5.30\fR.  To find a consumer for \fIperl:0/5.28\fR a simple
match can be made, e.g. using \fBqdepends\Rf(1):

.nf
	$ \fIqdepends -Q perl:0/5.28\fR
	virtual/perl-ExtUtils-MakeMaker-7.340.0-r1: ... dev-lang/perl:0/5.28 ...
	...
.fi

However, to query after \fIperl:0/5.30\fR is installed, which packages
are still not rebuilt (e.g. depending on an older perl: 5.28, 5.26,
etc.) one can use the antislot:

.nf
	$ \fIqdepends -Q ^perl:0/5.30\fR
	...
.fi

This will return any package that depends on \fIperl:0\fR not having
subslot \fI5.30\fR.
.P
Obviously this can be tested using \fBqatom\fR using the \fI-c\fR
option:

.nf
	$ \fIqatom -c ^perl:0/5.30 perl-5.28.1:0/5.28\fR
	^perl:0/5.30 == perl-5.28.1:0/5.28
.fi
.SH "REPORTING BUGS"
Please report bugs via http://bugs.gentoo.org/
.br
Product: Gentoo Linux; Component: Current packages
.SH AUTHORS
.nf
Ned Ludd <solar@gentoo.org>
Mike Frysinger <vapier@gentoo.org>
Fabian Groffen <grobian@gentoo.org>
.fi
.SH "SEE ALSO"
.BR q (1),
.BR qcheck (1),
.BR qdepends (1),
.BR qfile (1),
.BR qgrep (1),
.BR qkeyword (1),
.BR qlist (1),
.BR qlop (1),
.BR qmanifest (1),
.BR qmerge (1),
.BR qpkg (1),
.BR qsearch (1),
.BR qsize (1),
.BR qtbz2 (1),
.BR qtegrity (1),
.BR quse (1),
.BR qwhich (1),
.BR qxpak (1)