notcat.1

.\" notcat.1 -- notcat man page
.\" Copyright 2024 Jack Conger
.\"
.\" notcat is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" notcat is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with notcat.  If not, see <http://www.gnu.org/licenses/>.

.TH NOTCAT 1
.SH NAME
notcat \- print or send notifications
.SH SYNOPSIS
.B notcat
[\fB\-h\fR | \fB\-\-help\fR]
.br
.B notcat
[\fBgetcapabilities\fR | \fBgetserverinfo\fR | \fBlisten\fR]
.br
.B notcat
[\fBclose\fR \fIID\fR | \fBinvoke\fR \fIID\fR [\fIKEY\fR]]
.br
.B notcat send
[\fB-aAchiItu\fR \fIVALUE\fR]... [\fB-p\fR] [\fB--\fR] [\fISUMMARY\fR]
[\fIBODY\fR]
.br
.B notcat
[\fB\-se\fR] [\fB\-t\fR \fITIMEOUT\fR] [\fB\-\-capabilities=\fICAP\fR,\fICAP\fR...] \\
.br
       [\fB\-\-on\-notify=\fICMD\fR] [\fB\-\-on\-close=\fICMD\fR] [\fB\-\-on\-empty=\fICMD\fR] \\
.br
       [\fB\-\-\fR] [\fIFORMAT ARGUMENTS\fR]...
.SH DESCRIPTION
.B notcat
is a D-Bus notification daemon which formats and prints received
notifications to standard output, or runs arbitrary subcommands when
notifications are received and deleted.
.PP
The
.I FORMAT
arguments control how notifications are formatted when they are
printed or executed in subcommands.
They support arbitrary strings.
If
.B notcat
finds one of the following format sequences among them, then it will
replace it in-place with the appropriate value, \fBprintf\fR-style.
.TP
\fB%%\fR
A literal \fB%\fR
.TP
\fB%i\fR
Notification ID
.TP
\fB%a\fR
App name
.TP
\fB%s\fR
Summary
.TP
\fB%B\fR
Body text, with newlines replaced with spaces to maintain printing
one line per notification
.TP
\fB%t\fR
Expiration timeout in milliseconds; 0 indicates no timeout, and -1
indicates timeout is up to the notification server
.TP
\fB%u\fR
Urgency; either \fBLOW\fR, \fBNORMAL\fR, or \fBCRITICAL\fR
.TP
\fB%n\fR
Type of
.B notcat
event (i.e., which subcommand is being called); either \fBnotify\fR,
\fBclose\fR, or \fBempty\fR
.TP
\fB%c\fR
Category; often of the form \fIclass\fR.\fIspecific\fR, but may be
simply \fIclass\fR
.TP
\fB%(h:\fINAME\fB)\fR
Hint value with the given
.I NAME
.TP
\fB%(A:\fIKEY\fB)\fR
Action name with the given
.I KEY
.PP
If no
.I FORMAT
arguments are provided, then
.B notcat
defaults to \fB%s\fR.
.SS CONDITIONALS
.PP
In addition to the above-listed format sequences,
.B notcat
supports \fIformat conditionals\fR.
These take the form
.IP
\fB%(?\fIK\fB:\fIEXPR\fB)\fR,
.PP
which tests if the notification's value of
.I K
exists and is non-empty or non-default, and if so, formats \fIEXPR\fR.
.I EXPR
may include more conditionals or format sequences.
.PP
Currently implemented behavior around different keys include
.TP
.B a
Formats
.I EXPR
if the notification's appname is non-empty.
.TP
.B s
Formats
.I EXPR
if the notification's summary is non-empty.
.TP
.B B
Formats
.I EXPR
if the notification has a body and it is non-empty.
.TP
.B t
Formats
.I EXPR
if the notification's timeout is set to a value other than -1.
.TP
.B c
Formats
.I EXPR
if the notification has a category set.
.TP
.B u
Formats
.I EXPR
if the notification's urgency is set to a value other than \fBNORMAL\fR.
.PP
In all cases, if the notification event has no associated
notification (like with \fB--on-empty\fR,) then the conditionals will
be false.
.SS ENVIRONMENT VARIABLES
.PP
If the
.B \-e
argument is supplied, then instead of the formatted arguments,
subcommands are invoked with the following environment variables set
to the appropriate values:
.TP
$\fINOTCAT_EVENT\fR
Type of
.B notcat
event (i.e., which subcommand is being called); either \fBnotify\fR,
\fBclose\fR, or \fBempty\fR.
.TP
$\fINOTE_ID\fR
Notification ID
.TP
$\fINOTE_APP_NAME\fR
App name
.TP
$\fINOTE_SUMMARY\fR
Summary
.TP
$\fINOTE_BODY\fR
Notification body
.TP
$\fINOTE_CATEGORY\fR
Category; often of the form \fIclass\fR.\fIspecific\fR, but may be
simply \fIclass\fR
.TP
$\fINOTE_URGENCY\fR
Urgency; either \fBLOW\fR, \fBNORMAL\fR, or \fBCRITICAL\fR
.TP
$\fINOTE_TIMEOUT\fR
Expiration timeout in milliseconds; 0 indicates no timeout, and -1
indicates timeout is up to the notification server
.PP
Arbitrary hints are not yet supported with the
.B \-e
flag.
.B \-e
is useless when used without explicit subcommands, because
\fBnotcat\fR's default behavior only introspects the
.I FORMAT
arguments.
.SH OPTIONS
.TP
\fB\-h\fR, \fB\-\-help\fR
Display help and exit.
.TP
\fB\-s\fR, \fB\-\-shell\fR
Run subcommands within a subshell, using
.IP
\fC$SHELL \-c $CMD
.TP
\fB\-e\fR, \fB\-\-env\fR
Pass subcommands information about notifications through the
environment, rather than using formatted arguments.
.TP
\fB\-t\fR, \fB\-\-timeout=\fITIMEOUT\fR
Default timeout for notifications received by \fBnotcat\fR, expressed
in milliseconds.
This value must be expressible as a 32-bit integer.
.TP
\fB\-\-capabilities=\fICAP\fR,\fICAP\fR...
Additional capabilities for
.B notcat
to advertise.
By default,
.B notcat
tries to advertise a reasonable set of capabilities, either (if
.B \-e
is not set) based on its
.I FORMAT
arguments, or based on the set of environment variables that
.B notcat
passes to subcommands.
Capabilities must only consist of alphanumeric characters and dashes.
.TP
\fB\-\-on\-notify=\fICMD\fR
Run the command
.I CMD
each time a notification is created or replaced.
By default, the command is invoked via \fBexecvp\fR, with its
arguments set to the interpolated
.I FORMAT
arguments provided to \fBnotcat\fR.
.IP
If not provided,
.B notcat
defaults to its built-in \fBecho\fR.
.TP
\fB\-\-on\-close=\fICMD\fR
Run the command
.I CMD
each time a notification is closed.
By default, the command is invoked via \fBexecvp \fR, with its
arguments set to the interpolated
.I FORMAT
arguments provided to \fBnotcat\fR.
.IP
If not provided, then \fBnotcat\fR's default behavior is to do
nothing.
.TP
\fB\-\-on\-empty=\fICMD\fR
Run the command
.I CMD
whenever the last notification is closed, and no more notifications
remain.
The command is invoked via \fBexecvp\fR.
Because \fB\-\-on\-empty\fR isn't associated with any particular
notification, all
.I FORMAT
arguments except for \fB%n\fR interpolate to the empty string.
.IP
If not provided, then \fBnotcat\fR's behavior is to do nothing.
.TP
\fB\-\-\fR
Stop option parsing.
This may be used in case there are
.I FORMAT
arguments which would otherwise be parsed as options to \fBnotcat\fR.
.SH CLIENT COMMANDS
The
.B notcat
command can be used to interact as a client with an already-running
notification server.
Existing commands are:
.TP
\fBclose\fR \fIID\fR
Close the notification with the given \fIID\fR.
.TP
\fBinvoke\fR \fIID\fR [\fIKEY\fR]
Invoke the action with the key \fIKEY\fR on the notification with the
given \fIID\fR.
If no \fIKEY\fR is provided, \fBdefault\fR is used.
Unfortunately, \fBinvoke\fR will only work with notification servers
which advertise the \fBx-notlib-remote-actions\fR capability, which will
probably only ever be 
.B notcat
itself.
.TP
\fBgetcapabilities\fR
Get the capabilities of the notification server.
.TP
\fBgetserverinfo\fR
Get basic information about the notification server.
.TP
\fBlisten\fR
Listen for signals from the notification server and print them as
they arrive.
.TP
\fBsend\fR
Send a notification to the server.
In addition to any options, \fBsend\fR requires at most two arguments
specifying the notification summary and body, respectively.
If only one argument is given, it is used as the summary.
.PP
There are several options for the
.B send
command, described as follows.
.SS SEND OPTIONS
.PP
.B notcat send
supports a relatively standard set of notification options, with some
allowances for extra flexibility.
These options correspond with behavior found in the D-Bus
Notifications API documentation.
.TP
\fB-a\fR, \fB--app-name=\fINAME\fR
App name.
.TP
\fB-A\fR, \fB--actions=\fIACTION\fB,\fIKEY\fB:\fINAME\fR...
Actions.
Multiple comma-separated actions may be supplied in one arg, and if
an action is provided as a \fIKEY\fR:\fINAME\fR, then \fINAME\fR will
be used in the notification display.
.TP
\fB-c\fR, \fB--category=\fICATEGORY\fR
Notification category, which should be one of the values given in the
D-Bus Notifications API documentation.
.TP
\fB-h\fR, \fB--hint=\fR[[\fITYPE\fR]\fB:\fR]\fINAME\fB:\fIVALUE\fR
A hint, which is an arbitrary key-value pair.
.B notcat
uses GLib's type format strings and parser to get values from this
argument.
Most likely types to be useful are: \fBb\fR, boolean; \fBy\fR, byte;
\fBs\fR, string; \fBi\fR, 32-bit int; and \fBu\fR, 32-bit unsigned
int.
If no type is specified, or the given type is empty,
.B notcat
defaults to a string.
.TP
\fB-i\fR, \fB--id=\fIID\fR
Notification ID to replace (if currently in use).
Must be a non-negative integer.
.TP
\fB-I\fR, \fB--icon=\fIICON\fR
Name or path of the icon to display with this notification.
.TP
\fB-p\fR, \fB--print-id\fR
If set,
.B notcat
will print the ID of the notification after sending it.
.TP
\fB--sync\fR
If set,
.B notcat
will wait until the notification is closed to exit.
It will also print the name of any actions invoked on the
notification when they occur.
.TP
\fB-t\fR, \fB--timeout=\fITIMEOUT\fR
Notification timeout.
The default value is managed by the server.
.TP
\fB-u\fR, \fB--urgency=\fIURGENCY\fR
Urgency of the notification.
May be one of \fBlow\fR, \fBnormal\fR, or \fBcritical\fR.
.SH EXAMPLES
Simple invocation to print notification summaries and bodies as they
arrive:
.IP
\fCnotcat %s %B
.PP
Invocation that has the same behavior as above, but by invoking
.B echo
in a subshell on each notification:
.IP
\fCnotcat \-s \(aq\-\-on-notify=echo $*\(aq %s %B
.PP
Note the trailing \fC$*\fR in the \fB--on-notify\fR command; this is
required for the invoked
.B echo
to receive the args from its calling shell.
.PP
Invocation that has (roughly) the same behavior as above, but using
environment variables this time:
.IP
\fCnotcat \-se \(aq\-\-on-notify=echo $NOTE_SUMMARY $NOTE_BODY\(aq
.PP
This invocation has the disadvantage of being somewhat more verbose,
and also loses the automatic formatting that
.B notcat
applies to the notification body, in favor of providing control to the
user, and making longer shell scripts run as subcommands significantly
clearer.
.SH AUTHOR
.B notcat
is written by Jack Conger (jpco).
.PP
Both
.B notcat
and this manual page are released under the GNU General Public
License, version 3+.
.SH ERRATA
Markup and links are not yet supported.
.PP
Format sequences lack the escaping facilities to allow arbitrary text
in things like conditionals.
.PP
Some capabilities will likely never be supported.
In particular, the \fBbody-images\fR, \fBicon-multi\fR,
\fBicon-static\fR, and \fBsound\fR capabilities are outside the
intended design of \fBnotcat\fR.
.SH SEE ALSO
\fBnotify\-send\fR\|(1)
.SH STANDARDS
.B notcat
conforms to version 1.2 of the Desktop Notifications Specification.