NAME
Linux::DesktopFiles - Fast parsing of the Linux desktop files.
SYNOPSIS
use Linux::DesktopFiles;
my $obj = Linux::DesktopFiles->new( terminalize => 1 );
print join("\n", $obj->get_desktop_files);
my $hash_ref = $obj->parse_desktop_files;DESCRIPTION
The Linux::DesktopFiles, a very fast and simple way to parse the Linux desktop files.
CONSTRUCTOR METHODS
The following constructor methods are available:
- $obj = Linux::DesktopFiles->new( %options )
-
This method constructs a new
Linux::DesktopFilesobject and returns it. Key/value pair arguments may be provided to set up the initial state.By default,
Linux::DesktopFiles->new();is equivalent with:
Linux::DesktopFiles->new( terminal => $ENV{TERM}, terminalize => 0, terminalization_format => "%s -e '%s'", skip_entry => [], skip_filename_re => [], substitutions => [], desktop_files_paths => ['/usr/local/share/applications', '/usr/share/applications'], keys_to_keep => ["Name", "Exec", "Icon"], categories => [qw( Utility Development Education Game Graphics AudioVideo Network Office Settings System )], case_insensitive_cats => 0, keep_unknown_categories => 0, unknown_category_key => 'Other', );
Main options
- desktop_files_paths => ['dir1', 'dir2', ...]
-
Sets the directories where to find the desktop files.
- keys_to_keep => [qw(Name Exec Icon Comment ...)]
-
Any valid keys from the desktop files to keep in the results from
parse_desktop_file. The Categories key is implicitly included. - categories => [qw(Graphics Network AudioVideo ...)]
-
Any valid categories from the desktop files. Any category not listed will be ignored or stored in the unknown_category_key when
keep_unknown_categoriesis set to a true value.
Other options
- keep_unknown_categories => $bool
-
When an entry is not part of any specified category, it will be stored inside the unknown category, specified by unknown_category_key.
- unknown_category_key => $name
-
Category name where to store the entries which do not belong to any specified category.
- case_insensitive_cats => $bool
-
This option makes the category names case insensitive, by lowercasing and replacing any non-alphanumeric characters with an underscore. For example,
X-XFCEbecomesx_xfce. - terminal => $command
-
This terminal command will be used when terminalize is set to a true value.
- terminalize => $bool
-
When the value of Terminal is true, modify the Exec value to something like:
terminal -e 'command'This option will include the
Terminalkey inside the keys_to_keep array. - terminalization_format => q{%s -e '%s'}
-
Format used by
sprintf()to terminalize a command which requires to be executed inside a terminal.Used internally as:
sprintf($self->{terminalization_format}, $self->{terminal}, $entry{Exec});
Regex options
- skip_filename_re => qr/regex/
-
Skip any desktop file if its file name matches the regex.
NOTE: File names are from the last slash to the end.
- skip_entry => [{key => 'KeyName', re => qr/REGEX/i}, {...}]
-
Skip any desktop file if the value from a given key matches a regular expression.
The key can be any valid key from the desktop files.
Example:
skip_entry => [ {key => 'Name', re => qr/(?:about|terminal)/i}, {key => 'Exec', re => qr/xterm/}, ], - substitutions => [{key => 'KeyName', re => qr/REGEX/i, value => 'Value'}, {...}]
-
Substitute, by using a regex, in the returned values from desktop files.
The key can be any valid key from the desktop files.
The re can be any valid regular expression. Anything matched by the regex, will be replaced with the string stored in value.
For global matching/substitution, set the global key to a true value.
Example:
substitutions => [ {key => 'Exec', re => qr/xterm/, value => 'tilix'}, {key => 'Exec', re => qr/\$HOME\b/, value => '/my/home', global => 1}, ],
SUBROUTINES/METHODS
- $obj->get_desktop_files()
-
Returns a list with the absolute paths to all desktop files from desktop_files_paths.
In scalar context, returns an ARRAY reference.
- $obj->parse(\%hash, @desktop_files)
-
Parse a list of desktop files into a HASH ref, where the keys of the HASH are the categories from desktop files and the values are ARRAY references containing information about each entry, as returned by
parse_desktop_file(). - $obj->parse_desktop_file($desktop_file)
-
Parse a given desktop file and return a key-value list as a result.
Example:
my %info = $obj->parse_desktop_file($desktop_file);where
%infomight look something like this:my %info = ( Name => "...", Exec => "...", Icon => "...", Categories => ["...", "...", "..."], SubCategories => {Category1 => ["...", "..."], Category2 => ["...", "..."]}, );When keep_unknown_categories is true and a given entry does not belong to any category,
parse_desktop_filewill set Categories to [unknown_category_key].Returns a HASH reference in scalar contenxt.
When a given file cannot be parsed or its specified as Hidden or NoDisplay, an empty list is returned (undef in scalar context).
- $obj->parse_desktop_files()
-
It returns a HASH reference categorized on category names, with ARRAY references as values, each ARRAY containing a HASH reference with the keys specified in the keys_to_keep option, and values from the desktop files.
The returned HASH reference may look something like this:
{ Utility => [ {Exec => "...", Name => "..."}, {Exec => "...", Name => "..."} ], Network => [ {Exec => "...", Name => "..."}, {Exec => "...", Name => "..."} ], }This function is equivalent with:
$obj->parse(\%hash, $obj->get_desktop_files);In list contenxt, it returns a key-value list, while, in scalar context, it returns a HASH reference.
REPOSITORY
https://github.com/trizen/Linux-DesktopFiles
AUTHOR
Daniel Șuteu, <trizen at cpan.org>
COPYRIGHT AND LICENSE
Copyright (C) 2012-2017
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.