.Dd November 29, 2016
.Dt VIS-CLIPBOARD 1
.Os Vis 0.8
.
.Sh NAME
.Nm vis-clipboard
.Nd Read from or write to the system clipboard
.
.Sh SYNOPSIS
.Nm vis-clipboard
.Fl -usable
.Pp
.Nm vis-clipboard
.Fl -copy
.Op Fl -selection Ar selection
.Pp
.Nm vis-clipboard
.Fl -paste
.Op Fl -selection Ar selection
.
.Sh DESCRIPTION
.Nm vis-clipboard
wraps various system-specific tools for interacting with a system clipboard,
like
.Xr xsel 1
for X11,
.Xr pbcopy 1
for Mac OS X,
and
.Pa /dev/clipboard
on Cygwin.
.Pp
.Nm vis-clipboard
can run in three different ways,
depending on the flag given on the command-line.
.Bl -tag -width flag
.It Fl -usable
In this mode,
.Nm vis-clipboard
looks for a way to interface with the system clipboard.
If it finds one,
it terminates with exit code 0.
If no interface to the system clipboard is available,
it terminates with exit code 1.
.It Fl -copy
In this mode,
.Nm vis-clipboard
reads the content of standard input,
and stores it in the system clipboard.
.It Fl -paste
In this mode,
.Nm vis-clipboard
reads the content of the system clipboard,
and writes it to standard output.
.It Fl -selection Ar selection
specify which selection to use, options are "primary" or "clipboard"
.El
.
.Sh ENVIRONMENT
The following environment variables affect the operation of
.Nm vis-clipboard :
.Bl -tag -width Ev
.It Ev DISPLAY
If non-empty,
.Nm vis-clipboard
will prefer to access the X11 clipboard even if other options are available.
.El
.
.Sh EXIT STATUS
.Ex -std vis-clipboard
.
When run with the
.Fl -usable
flag,
an exit status of 0 means that it found a supported system-specific tool,
while 1 means that clipboard access is not available.
.
.Sh EXAMPLES
Test whether clipboard access is available:
.Bd -literal -offset indent
if vis-clipboard --usable; then
	echo "Clipboard access available"
else
	echo "No clipboard"
fi
.Ed
.Pp
Copy a friendly greeting to the clipboard:
.Bd -literal -offset indent
echo "Hello, World" | vis-clipboard --copy
.Ed
.Pp
Send the current contents of the system clipboard to be recorded and analyzed:
.Bd -literal -offset indent
vis-clipboard --paste | curl -d - https://www.nsa.gov/
.Ed
.
.Sh SEE ALSO
.Xr pbcopy 1 ,
.Xr pbpaste 1 ,
.Xr vis 1 ,
.Xr xclip 1 ,
.Xr xsel 1