NAME

WebShortcutUtil::Write - Utilities for writing web shortcut files

SYNOPSIS

  use WebShortcutUtil::Write qw(
        create_desktop_shortcut_filename
        create_url_shortcut_filename
        create_webloc_shortcut_filename
        write_desktop_shortcut_file
        write_url_shortcut_file
        write_webloc_binary_shortcut_file
        write_webloc_xml_shortcut_file);

  # Helpers to create a file name (with bad characters removed).
  my $filename = create_desktop_shortcut_filename("Shortcut: Name");
  my $filename = create_url_shortcut_filename("Shortcut: Name");
  my $filename = create_webloc_shortcut_filename("Shortcut: Name");

  # Write shortcuts
  write_desktop_shortcut_file("myshortcut.desktop", "myname", "http://myurl.com/");
  write_url_shortcut_file("myshortcut.url", "myname", "http://myurl.com/");
  write_webloc_binary_shortcut_file("myshortcut_binary.webloc", "myname", "http://myurl.com/");
  write_webloc_xml_shortcut_file("myshortcut_xml.webloc", "myname", "http://myurl.com/");

DESCRIPTION

The following subroutines are provided:

create_desktop_shortcut_filename( NAME [,LENGTH] )

create_url_shortcut_filename( NAME [,LENGTH] )

create_webloc_shortcut_filename( NAME [,LENGTH] )

Creates a file name based on the specified shortcut name. The goal is to allow the file to be stored on a wide variety of filesystems without issues. The following rules are used:

1 An appropriate extension is added based on the shortcut type (e.g. ".url").

2 Removes characters which are prohibited in some file systems (such as "?" and ":"). Note there may still be characters left that will cause difficulty, such as spaces and single quotes.

3 If the resulting name (after removing characters) is an empty string, the file will be named "_".

4 Unicode characters are not changed. If there are unicode characters, they could cause problems on some file systems. If you do not want unicode characters in the file name, you are responsible for removing them or converting them to ASCII.

5 If the filename is longer than 100 characters (including the extension), it will be truncated. This maximum length was chosen somewhat arbitrarily. You may optionally override it by passing in a length parameter.

The following references discuss file name restrictions:

• http://en.wikipedia.org/wiki/Filename

• http://msdn.microsoft.com/en-us/library/windows/desktop/aa365247(v=vs.85).aspx

• http://support.grouplogic.com/?p=1607

• https://www.dropbox.com/help/145/en

write_desktop_shortcut_file( FILENAME, NAME, URL )

write_url_shortcut_file( FILENAME, NAME, URL )

write_webloc_binary_shortcut_file( FILENAME, NAME, URL )

write_webloc_xml_shortcut_file( FILENAME, NAME, URL )

These routines write shortcut files of the specified type. The shortcut will contain the specified name/title and URL. Note that some shortcuts do not contain a name inside the file, in which case the name parameter is ignored.

If your URL contains unicode characters, it is recommended that you convert it to an ASCII-only URL (see http://en.wikipedia.org/wiki/Internationalized_domain_name ). That being said, write_desktop_shortcut_file and write_url_shortcut_file will write unicode URLs. The webloc writers should as well, although this functionality requires more testing.

Note: The Mac::PropertyList module (http://search.cpan.org/~bdfoy/Mac-PropertyList/) must be installed in order to write ".webloc" files.

SEE ALSO

http://search.cpan.org/~beckus/WebShortcutUtil/lib/WebShortcutUtil.pm

COPYRIGHT AND LICENSE

Copyright (C) 2013 by Andre Beckus

This library is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language itself.