Linux::DesktopFiles(3)

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::DesktopFiles" object 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. This keys will be stored in the returned hash reference when calling "$obj->parse_desktop_files".

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_categories" is set to a true value.

  Other options

keep_unknown_categories => $bool
    When an item is not part of any specified category, will be stored inside the unknown category, specified by unknown_category_key.

unknown_category_key => $name
    Category name where to store the applications 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-alpha numeric characters with an underscore. For example, "X-XFCE" becomes "x_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'

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}, $command);

  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 the specified 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 values of the 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 the string stored in value. For global matching/substitution, you need to set the global key to a true value.

    Example:

            substitutions => [
                {key => 'Exec', re => qr/xterm/,    value => 'sakura'},
                {key => 'Exec', re => qr/\$HOME\b/, value => '/my/home', global => 1},
            ],

SUBROUTINES/METHODS

$obj->get_desktop_files()
    Get all desktop files. In list context returns a list, but in scalar context, it returns an array reference containing the full names of the desktop files.

$obj->parse(\%hash, @desktop_files)
    Parse a list of desktop files into a HASH ref.

$obj->parse_desktop_files()
    It returns a HASH reference which categories names as keys, and ARRAY references as values which contains HASH references with the keys specified in the keys_to_keep option, and values from the desktop files.

    The returned HASH reference might 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);

REPOSITORY
<https://github.com/trizen/Linux-DesktopFiles>

AUTHOR
Daniel "Trizen" Șuteu, <trizenx@gmail.com>

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.

SEE ALSO
File::DesktopEntry and X11::FreeDesktop::DesktopEntry