view release on metacpan or  search on metacpan

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

our $VERSION = '0.015'; # VERSION

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;

sub _find_qdbus {
    require File::Which;

    my @paths;
    if (my $path = File::Which::which("qdbus")) {
        log_trace "qdbus found in PATH: $path";
        push @paths, $path;
    } else {
        for my $dir ("/usr/lib/qt6/bin", "/usr/lib/qt5/bin") {
            if ((-d $dir) && (-x "$dir/qdbus")) {
                log_trace "qdbus found in $dir";
                push @paths, "$dir/qdbus";
            }
        }
    }

    @paths;
}

$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: {
                my @paths = _find_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";
                    $info->{klipper_path} = $path;

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

1;
# ABSTRACT: Common interface to clipboard manager functions

__END__

=pod

=encoding UTF-8

=head1 NAME

Clipboard::Any - Common interface to clipboard manager functions

=head1 VERSION

This document describes version 0.015 of Clipboard::Any (from Perl distribution Clipboard-Any), released on 2025-06-16.

=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. With C<xclip>, the history is viewed as having two items. The
first/recent is the primary selection and the second one is the secondary.


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