Desktop-Workspace-Util
view release on metacpan or search on metacpan
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.002 of Desktop::Workspace::Util (from
Perl distribution Desktop-Workspace-Util), released on 2026-03-29.
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.
Some notes: - if you do not use "new_browser_window", then URLs will be
opened in the previous Firefox window which might be in another KDE
activity.
This function is not exported by default, but exportable.
This function supports dry-run operation.
Arguments ('*' denotes required arguments):
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)
* new_browser_window => *bool*
When having to open one or more browser tabs, open a new browser
window.
Override's desktop workspace specification's "new_browser_window"
property.
* ns_prefixes => *array[perl::modname|str]* (default:
["DesktopWorkspace",""])
List of namespaces to search for a Desktop Workspace specification
modules.
* query => *array[str]*
lib/Desktop/Workspace/Util.pm view on Meta::CPAN
use Exporter qw(import);
use Perinci::Sub::Util qw(gen_modified_sub);
our $AUTHORITY = 'cpan:PERLANCAR'; # AUTHORITY
our $DATE = '2026-03-29'; # DATE
our $DIST = 'Desktop-Workspace-Util'; # DIST
our $VERSION = '0.002'; # 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} // {} });
}
$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',
Some notes:
- if you do not use `new_browser_window`, then URLs will be opened in the
previous Firefox window which might be in another KDE activity.
MARKDOWN
add_args => {
new_browser_window => {
summary => 'When having to open one or more browser tabs, open a new browser window',
description => <<'MARKDOWN',
Override's desktop workspace specification's `new_browser_window` property.
MARKDOWN
schema => 'bool*',
},
kde_activity => {
summary => 'Switch to the specified KDE activity name',
description => <<'MARKDOWN',
Override's desktop workspace specification's `kde_activity` property.
MARKDOWN
schema => 'str*',
},
},
modify_meta => sub {
my $meta = shift;
$meta->{features} = {
dry_run => 1,
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 @url_items;
my @file_items;
my @dir_items;
my @prog_items;
CATEGORIZE_ITEMS: {
lib/Desktop/Workspace/Util.pm view on Meta::CPAN
require Desktop::Open;
my $i = 0;
for my $item (@file_items) {
$i++;
my $file = $item->{file};
log_trace "%sOpening file [%d/%d] %s ...",
$dry_run ? "[DRY-RUN]" : "",
$i, scalar(@file_items), $file;
unless ($dry_run) {
Desktop::Open::open_desktop($file);
}
}
} # OPEN_FILES
OPEN_DIRS: {
# we currently use dolphin to open dirs
last unless @dir_items;
my $i = 0;
my @dirs;
lib/Desktop/Workspace/Util.pm view on Meta::CPAN
This document describes version 0.002 of Desktop::Workspace::Util (from Perl distribution Desktop-Workspace-Util), released on 2026-03-29.
=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.
Some notes:
- if you do not use C<new_browser_window>, then URLs will be opened in the
previous Firefox window which might be in another KDE activity.
This function is not exported by default, but exportable.
This function supports dry-run operation.
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<new_browser_window> => I<bool>
When having to open one or more browser tabs, open a new browser window.
Override's desktop workspace specification's C<new_browser_window> property.
=item * B<ns_prefixes> => I<array[perl::modname|str]> (default: ["DesktopWorkspace",""])
List of namespaces to search for a Desktop Workspace specification modules.
=item * B<query> => I<array[str]>
(No description)
=item * B<shuffle> => I<bool>
( run in 0.761 second using v1.01-cache-2.11-cpan-c966e8aa7e8 )