NAME

Linux::DesktopFiles - Get and parse 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(
        abs_icon_paths   => 0,
        skip_svg_icons   => 0,
        icon_db_filename => undef,

        icon_dirs_first  => [],
        icon_dirs_second => [],
        icon_dirs_last   => [],

        case_insensitive_cats   => 0,
        strict_icon_dirs        => 0,
        use_current_theme_icons => 0,

        terminal    => $ENV{TERM},
        terminalize => 0,

        home_dir        => $ENV{HOME},
        gtk_rc_filename => "$ENV{HOME}/.gtkrc-2.0",

        skip_entry       => [],
        skip_filename_re => [],
        substitutions    => [],

        desktop_files_paths => ['/usr/share/applications'],
        keys_to_keep        => ["Name", "Exec", "Icon"],
        true_values         => ['true', 'True', '1'],
        categories          => [
                                qw( Utility
                                  Development
                                  Education
                                  Game
                                  Graphics
                                  AudioVideo
                                  Network
                                  Office
                                  Settings
                                  System )
                               ],
      );

Main options

desktop_files_paths => ['dir1', 'dir2', ...]

Set directories where to find the desktop files (default: /usr/share/applications)

keys_to_keep => [qw(Name Exec Icon Comment ...)]

Any of the valid keys from desktop files. This keys will be stored in the retured hash reference when calling $obj->parse_desktop_files.

categories => [qw(Graphics Network AudioVideo ...)]

Any of the valid categories from the desktop files. Any category not listed will be ignored.

Other options

keep_unknown_categories => 1

When an item is not part of any specified category, put it into an unknown category, specified by unknown_category_key.

unknown_category_key => 'key_name'

Category name where to store the applications which doesn't belong to any specified category.

case_insensitive_cats => 1

This option makes the categories case insensitive, by lowercasing and replacing any non-alpha numeric characters with an underscore. For example, "X-XFCE" will be equivalent with "x_xfce".

terminalize => 1

When Terminal is true, modify the Exec value to something like: terminal -e 'command'

terminal => "xterm"

This terminal will be used when terminalize is set to a true value.

terminalization_format => q{%s -e '%s'}

Format used by sprintf to terminalize a command which requires to run in a new terminal.

home_dir => "/home/dir"

Set the home directory. This value is used to locate icons in the ~/.local/share/icons.

gtk_rc_filename => "/path/to/.gtkrc-x.x"

This file is used to get the icon theme name from it. (default: ~/.gtkrc-2.0) NOTE: It works with Gtk3 as well.

true_values => [qw(1 true True)]

This values are used to test for trueness some values from the desktop files.

Icon options

abs_icon_paths => 1

Resolve the absolute file paths for Icon values.

icon_db_filename => "filename.db"

A database file which will be used to store icon names as keys and icon paths as values for a faster lookup (used with GDBM_File). NOTE: Works in combination with abs_icon_paths.

skip_svg_icons => 1

Ignore SVG icons when looking for absolute icon paths.

icon_dirs_first => [dir1, dir2, ...]

When looking for absolute icon paths, look in this directories first, before looking in the directories of the current icon theme.

icon_dirs_second => [dir1, dir2, ...]

When looking for full icon paths, look in this directories as a second icon theme. (Before /usr/share/pixmaps)

icon_dirs_last => [dir1, dir2, ...]

Look in this directories at the very last, after looked in /usr/share/pixmaps, /usr/share/icons/hicolor and some other directories.

strict_icon_dirs => 1

Be very strict and use only the directories specified in either one of icon_dirs_first, icon_dirs_second and/or icon_dirs_last.

use_current_theme_icons => 1

Use the current icon theme (from ~/.gtkrc-2.0) even when strict_icon_dirs is set to a true value. This option is useful when you want to get only the icons from the current theme. It is usually used in combination with strict_icon_dirs. When strict_icon_dirs is set a false value, this option is true by default. When strict_icon_dirs is set a true value, this option is false by default.

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->get_icon_theme_name()

Returns the name of the current icon theme, if any, otherwise returns undef;

$obj->get_icon_path("icon_name")

If abs_icon_paths is set to a true value, returns the absolute path of an icon name located in the system. If it can't find the icon name, it returns an empty string. If abs_icon_paths is set to a false value, it strips the extension name of the icon (if any), and returns the icon name. If the icon name is undefined, it returns an empty string.

$obj->parse(\%hash, @desktop_files)

Parse a list of desktop files into a HASH ref.

$obj->parse_desktop_file("filename")

It returns a HASH reference which contains the keys_to_keep and the corresponding values from the given file.

$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-2016

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