Desktop-Workspace-Util
view release on metacpan or search on metacpan
0.004 2026-05-04 Released-By: PERLANCAR; Urgency: medium
- [bugfix] Forgot to require Desktop::Open.
0.003 2026-04-15 Released-By: PERLANCAR; Urgency: medium
- Update to DesktopWorkspace 1.0.1.
- [function open_desktop_workspace_items] Add argument 'reuse_window'.
0.002 2026-03-29 Released-By: PERLANCAR; Urgency: medium
- [function open_desktop_workspace_items] Add dry-run feature.
- [bugfix] When opening, make sure we list items with detail=>1 to
get the properties.
0.001 2026-03-29 Released-By: PERLANCAR
- First release.
NAME
Desktop::Workspace::Util - Utilities related to DesktopWorkspace
VERSION
This document describes version 0.004 of Desktop::Workspace::Util (from
Perl distribution Desktop-Workspace-Util), released on 2026-05-04.
SYNOPSIS
DESCRIPTION
FUNCTIONS
get_desktop_workspace_module
Usage:
get_desktop_workspace_module(%args) -> any
Get the first Perl desktop workspace specification module.
This function is not exported by default, but exportable.
Arguments ('*' denotes required arguments):
* module* => *perl::modname*
(No description)
* ns_prefixes => *array[perl::modname|str]* (default:
["DesktopWorkspace",""])
List of namespaces to search for a Desktop Workspace specification
modules.
Return value: (any)
instantiate_desktop_workspace_module
Usage:
instantiate_desktop_workspace_module(%args) -> any
Instantiate the desktop workspace specification module (class).
This function is not exported by default, but exportable.
Arguments ('*' denotes required arguments):
* module* => *perl::modname*
(No description)
* module_args => *hash*
(No description)
* ns_prefixes => *array[perl::modname|str]* (default:
["DesktopWorkspace",""])
List of namespaces to search for a Desktop Workspace specification
modules.
Return value: (any)
list_desktop_workspace_items
Usage:
list_desktop_workspace_items(%args) -> [$status_code, $reason, $payload, \%result_meta]
List the items from desktop workspace specification module, with
filtering options.
This function is not exported by default, but exportable.
Arguments ('*' denotes required arguments):
* all => *bool*
Whether to include items that are not included by default (has
property `include_by_default`=0).
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)
open_desktop_workspace_items
Usage:
open_desktop_workspace_items(%args) -> [$status_code, $reason, $payload, \%result_meta]
Open desktop workspace items.
This function is not exported by default, but exportable.
This function supports dry-run operation.
Arguments ('*' denotes required arguments):
* all => *bool*
Whether to include items that are not included by default (has
Whether to include program items.
* include_url => *bool*
Whether to include URL items.
* kde_activity => *str*
Switch to the specified KDE activity name.
Override's desktop workspace specification's "kde_activity"
property.
* module* => *perl::modname*
(No description)
* module_args => *hash*
(No description)
lib/Desktop/Workspace/Util.pm view on Meta::CPAN
use Exporter qw(import);
use List::Util qw(first);
use Perinci::Sub::Util qw(gen_modified_sub);
our $AUTHORITY = 'cpan:PERLANCAR'; # AUTHORITY
our $DATE = '2026-05-04'; # DATE
our $DIST = 'Desktop-Workspace-Util'; # DIST
our $VERSION = '0.004'; # VERSION
our @EXPORT_OK = qw(
get_desktop_workspace_module
instantiate_desktop_workspace_module
list_desktop_workspace_items
open_desktop_workspace_items
);
our %SPEC;
our %argspec0_module = (
module => {
schema => 'perl::modname*',
req => 1,
pos => 0,
},
lib/Desktop/Workspace/Util.pm view on Meta::CPAN
module_args => {
schema => 'hash*',
},
);
$SPEC{':package'} = {
v => 1.1,
summary => 'Utilities related to DesktopWorkspace',
};
$SPEC{get_desktop_workspace_module} = {
v => 1.1,
summary => 'Get the first Perl desktop workspace specification module',
args => {
%argspecs_module,
},
result_naked => 1,
};
sub get_desktop_workspace_module {
my %args = @_;
my $module = $args{module} or die "Please specify 'module'";
my $ns_prefixes = $args{ns_prefixes} // ["DesktopWorkspace"];
push @$ns_prefixes, "" unless @$ns_prefixes;
for my $ns_prefix (@$ns_prefixes) {
my $mod = (length($ns_prefix) ? "$ns_prefix\::" : "") . $module;
(my $mod_pm = "$mod.pm") =~ s!::!/!g;
if (eval { require $mod_pm; 1 }) {
return $mod;
}
}
die "Can't find desktop workspace specification module '$module' (searched in ". join(", ", @$ns_prefixes).")";
}
$SPEC{instantiate_desktop_workspace_module} = {
v => 1.1,
summary => 'Instantiate the desktop workspace specification module (class)',
args => {
%argspecs_module,
%argspecopt_module_args,
},
result_naked => 1,
};
sub instantiate_desktop_workspace_module {
my %args = @_;
my $mod = get_desktop_workspace_module(
module => $args{module}, ns_prefixes => $args{ns_prefixes});
$mod->new(%{ $args{module_args} // {} });
}
sub _find_window {
my ($re, $all_windows) = @_;
log_trace "Checking existing window (%s) ...", $re;
for my $row (@$all_windows) {
if ($row->{title} =~ $re) {
log_trace "Found matching window %s", $row;
lib/Desktop/Workspace/Util.pm view on Meta::CPAN
$window->{existing_window_id} = $w->{id};
$window->{existing_window_kde_activity_name} = $w->{kde_activity_name};
}
}
}
}
\%windows;
}
$SPEC{list_desktop_workspace_items} = {
v => 1.1,
summary => 'List the items from desktop workspace specification module, with filtering options',
args => {
%argspecs_module,
%argspecopt_module_args,
all => {
summary => 'Whether to include items that are not included by default (has property `include_by_default`=0)',
schema => 'bool*',
tags => ['category:filtering'],
},
include_any_tags => {
lib/Desktop/Workspace/Util.pm view on Meta::CPAN
schema => 'bool*',
cmdline_aliases => {l=>{}},
tags => ['category:result'],
},
shuffle => {
schema => 'bool*',
tags => ['category:result'],
},
},
};
sub list_desktop_workspace_items {
my %args = @_;
my $obj = instantiate_desktop_workspace_module(
module => $args{module},
ns_prefixes => $args{ns_prefixes},
module_args => $args{module_args},
);
my $items = $obj->items;
if ($args{shuffle}) {
require List::Util;
$items = [List::Util::shuffle(@$items)];
lib/Desktop/Workspace/Util.pm view on Meta::CPAN
} @filtered_items;
}
[200, "OK", \@filtered_items, {
'func.obj' => $obj,
}];
}
gen_modified_sub(
die => 1,
output_name => 'open_desktop_workspace_items',
base_name => 'list_desktop_workspace_items',
summary => 'Open desktop workspace items',
description => <<'MARKDOWN',
MARKDOWN
add_args => {
kde_activity => {
summary => 'Switch to the specified KDE activity name',
description => <<'MARKDOWN',
Override's desktop workspace specification's `kde_activity` property.
MARKDOWN
schema => 'str*',
},
reuse_window => {
summary => 'Do not open if existing window is detected',
schema => 'bool*',
},
},
modify_meta => sub {
lib/Desktop/Workspace/Util.pm view on Meta::CPAN
my $orig = shift;
my %args = @_;
my $dry_run = $args{-dry_run};
my $obj;
my $items;
LIST_ITEMS: {
my $res = $orig->(%args, detail=>1);
unless ($res->[0] == 200) {
return [500, "Can't list desktop workspace items: $res->[0] - $res->[1]"];
}
$items = $res->[2];
$obj = $res->[3]{'func.obj'};
} # LIST_ITEMS
my $windows = _items2windows($items);
WINDOW:
for my $windowkey (sort keys %$windows) {
my $window = $windows->{$windowkey};
lib/Desktop/Workspace/Util.pm view on Meta::CPAN
my $i = 0;
for my $item (@$items) {
$i++;
my $file = $item->{file};
log_trace "%sOpening file %s (window %s) ...",
$dry_run ? "[DRY-RUN]" : "",
$file,
$windowkey;
unless ($dry_run) {
require Desktop::Open;
Desktop::Open::open_desktop($file);
}
} # for item
} elsif ($windowkey =~ /^dolphin_/) {
my $i = 0;
my @urls;
for my $item (@$items) {
$i++;
my $url = $item->{dir} // $item->{url};
lib/Desktop/Workspace/Util.pm view on Meta::CPAN
This document describes version 0.004 of Desktop::Workspace::Util (from Perl distribution Desktop-Workspace-Util), released on 2026-05-04.
=head1 SYNOPSIS
=head1 DESCRIPTION
=head1 FUNCTIONS
=head2 get_desktop_workspace_module
Usage:
get_desktop_workspace_module(%args) -> any
Get the first Perl desktop workspace specification module.
This function is not exported by default, but exportable.
Arguments ('*' denotes required arguments):
=over 4
=item * B<module>* => I<perl::modname>
(No description)
lib/Desktop/Workspace/Util.pm view on Meta::CPAN
List of namespaces to search for a Desktop Workspace specification modules.
=back
Return value: (any)
=head2 instantiate_desktop_workspace_module
Usage:
instantiate_desktop_workspace_module(%args) -> any
Instantiate the desktop workspace specification module (class).
This function is not exported by default, but exportable.
Arguments ('*' denotes required arguments):
=over 4
=item * B<module>* => I<perl::modname>
(No description)
lib/Desktop/Workspace/Util.pm view on Meta::CPAN
List of namespaces to search for a Desktop Workspace specification modules.
=back
Return value: (any)
=head2 list_desktop_workspace_items
Usage:
list_desktop_workspace_items(%args) -> [$status_code, $reason, $payload, \%result_meta]
List the items from desktop workspace specification module, with filtering options.
This function is not exported by default, but exportable.
Arguments ('*' denotes required arguments):
=over 4
=item * B<all> => I<bool>
Whether to include items that are not included by default (has property `include_by_default`=0).
lib/Desktop/Workspace/Util.pm view on Meta::CPAN
(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 open_desktop_workspace_items
Usage:
open_desktop_workspace_items(%args) -> [$status_code, $reason, $payload, \%result_meta]
Open desktop workspace items.
This function is not exported by default, but exportable.
This function supports dry-run operation.
Arguments ('*' denotes required arguments):
=over 4
lib/Desktop/Workspace/Util.pm view on Meta::CPAN
Whether to include program items.
=item * B<include_url> => I<bool>
Whether to include URL items.
=item * B<kde_activity> => I<str>
Switch to the specified KDE activity name.
Override's desktop workspace specification's C<kde_activity> property.
=item * B<module>* => I<perl::modname>
(No description)
=item * B<module_args> => I<hash>
(No description)
=item * B<ns_prefixes> => I<array[perl::modname|str]> (default: ["DesktopWorkspace",""])
( run in 2.064 seconds using v1.01-cache-2.11-cpan-b16cb0d3907 )