view release on metacpan or  search on metacpan

lib/Clipboard/Any.pm  view on Meta::CPAN

package Clipboard::Any;

use 5.010001;
use strict;
use warnings;
use Log::ger;

use Exporter::Rinci qw(import);
use IPC::System::Options 'system', 'readpipe', 'run', -log=>1;

our $AUTHORITY = 'cpan:PERLANCAR'; # AUTHORITY
our $DATE = '2026-07-07'; # DATE
our $DIST = 'Clipboard-Any'; # DIST
our $VERSION = '0.017'; # VERSION

sub _x_selection {
    my $sel = $ENV{PERL_CLIPBOARD_ANY_XCLIP_SELECTION} // 'primary';
    $sel =~ s/\W+/_/g;
    $sel;
}

our $known_clipboard_managers = [qw/klipper parcellite clipit xclip/];
our $sch_clipboard_manager = ['str', in=>$known_clipboard_managers];
our %argspecopt_clipboard_manager = (
    clipboard_manager => {
        summary => 'Explicitly set clipboard manager to use',
        schema => $sch_clipboard_manager,
        description => <<'MARKDOWN',

The default, when left undef, is to detect what clipboard manager is running.

MARKDOWN
        cmdline_aliases => {m=>{}},
    },
);

our %argspec0_index = (
    index => {
        summary => 'Index of item in history (0 means the current/latest, 1 the second latest, and so on)',
        schema => 'int*',
        description => <<'MARKDOWN',

If the index exceeds the number of items in history, empty string or undef will
be returned instead.

MARKDOWN
    },
);

our %SPEC;

$SPEC{':package'} = {
    v => 1.1,
    summary => 'Common interface to clipboard manager functions',
    description => <<'MARKDOWN',

This module provides common functions related to clipboard manager.

Supported clipboard manager: KDE Plasma's Klipper (`klipper`), `parcellite`,
`clipit`, `xclip`. Support for more clipboard managers, e.g. on Windows or other
Linux desktop environment is welcome.

MARKDOWN
};

$SPEC{'detect_clipboard_manager'} = {
    v => 1.1,
    summary => 'Detect which clipboard manager program is currently running',
    description => <<'MARKDOWN',

Will return a string containing name of clipboard manager program, e.g.
`klipper`. Will return undef if no known clipboard manager is detected.

MARKDOWN
    result_naked => 1,
    args => {
        detail => {
            schema => 'bool*',
            cmdline_aliases => {l=>{}},
        },
    },
    #result => {
    #    schema => $sch_clipboard_manager,
    #},
};
sub detect_clipboard_manager {
    my %args = @_;

    require File::Which;

    require Proc::Find;
    no warnings 'once';
    local $Proc::Find::CACHE = 1;

    my $info = {};
  DETECT: {

      DETECT_KLIPPER:
        {
            log_trace "Checking whether clipboard manager klipper is running ...";

          METHOD1: {
                require Desktop::KDE::Util;
                my $paths = Desktop::KDE::Util::which_qdbus();

                unless (@$paths) {
                    log_trace "qdbus not found, checking using qdbus";
                    last;
                }

                for my $path (@$paths) {
                    my $out;
                    system({capture_merged=>\$out}, $path, "org.kde.klipper", "/klipper");
                    unless ($? == 0) {
                        # note, when klipper is disabled via System Tray Settings >
                        # General > Extra Items, the object path /klipper disappears.
                        log_trace "Failed listing org.kde.klipper /klipper methods (using qdus at $path)";
                        next;
                    }
                    log_trace "org.kde.klipper/klipper object active, concluding using klipper";
                    $info->{manager} = "klipper";

lib/Clipboard/Any.pm  view on Meta::CPAN

__END__

=pod

=encoding UTF-8

=head1 NAME

Clipboard::Any - Common interface to clipboard manager functions

=head1 VERSION

This document describes version 0.017 of Clipboard::Any (from Perl distribution Clipboard-Any), released on 2026-07-07.

=head1 DESCRIPTION

This module provides a common interface to interact with clipboard.

Some terminology:

=over

=item * clipboard content

The current clipboard content. Some clipboard manager supports storing multiple
items (multiple contents). All the items are called L</clipboard history>.

=item * clipboard history

Some clipboard manager supports storing multiple items (multiple contents). All
the items are called clipboard history. It is presented as an array. The current
item/content is at index 0, the secondmost current item is at index 1, and so
on.

=back

=head2 Supported clipboard managers

=head3 Klipper

The default clipboard manager on KDE Plasma.

=head3 clipit

=head3 parcellite

=head3 xclip

This is not a "real" clipboard manager, but just an interface to the X
selections. It has a history of just one item, either the C<primary> selection
or the C<clipboard> selection. You can choose which selection to use via
environment variable C<PERL_CLIPBOARD_ANY_XCLIP_SELECTION>. The default is the
C<primary> selection.


This module provides common functions related to clipboard manager.

Supported clipboard manager: KDE Plasma's Klipper (C<klipper>), C<parcellite>,
C<clipit>, C<xclip>. Support for more clipboard managers, e.g. on Windows or other
Linux desktop environment is welcome.

=head1 NOTES

2021-07-15 - Tested on my system (KDE Plasma 5.12.9 on Linux).

=head1 FUNCTIONS


=head2 add_clipboard_content

Usage:

 add_clipboard_content(%args) -> [$status_code, $reason, $payload, \%result_meta]

Add a new content to the clipboard.

For C<xclip>: when adding content, the primary selection is set. The clipboard
content is unchanged.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

=over 4

=item * B<chomp_newline> => I<bool>

Remove trailing newlines before adding item to clipboard.

=item * B<clipboard_manager> => I<str>

Explicitly set clipboard manager to use.

The default, when left undef, is to detect what clipboard manager is running.

=item * B<content> => I<str>

(No description)

=item * B<tee> => I<bool>

If set to true, will output content back to STDOUT.


=back

Returns an enveloped result (an array).

First element ($status_code) is an integer containing HTTP-like status code
(200 means OK, 4xx caller error, 5xx function error). Second element
($reason) is a string containing error message, or something like "OK" if status is
200. Third element ($payload) is the actual result, but usually not present when enveloped result is an error response ($status_code is not 2xx). Fourth
element (%result_meta) is called result metadata and is optional, a hash
that contains extra information, much like how HTTP response headers provide additional metadata.

Return value:  (any)



=head2 clear_clipboard_content