perl-Glib r1062 - trunk

[tsch svn gnome org]

Author: tsch
Date: Tue Jan 20 19:38:23 2009
New Revision: 1062
URL: http://svn.gnome.org/viewvc/perl-Glib?rev=1062&view=rev

Log:
Add documentation for Glib->filename_to_uri and filename_from_uri.  Patch by
Kevin Ryde.


Modified:
   trunk/ChangeLog
   trunk/Glib.pm

Modified: trunk/Glib.pm
==============================================================================
--- trunk/Glib.pm	(original)
+++ trunk/Glib.pm	Tue Jan 20 19:38:23 2009
@@ -1,4 +1,4 @@
-# Copyright (C) 2003-2008 by the gtk2-perl team (see the file AUTHORS for
+# Copyright (C) 2003-2009 by the gtk2-perl team (see the file AUTHORS for
 # the full list)
 #
 # This library is free software; you can redistribute it and/or modify it under
@@ -420,7 +420,7 @@
 
 =back
 
-Other functions for converting URIs are currently missing. Also, it might
+It might
 be useful to know that perl currently has no policy at all regarding
 filename issues, if your scalar happens to be in utf-8 internally it will
 use utf-8, if it happens to be stored as bytes, it will use it as-is.
@@ -440,7 +440,54 @@
 necessarily reversible.  These functions are intended to be used for failsafe
 display of filenames, for example in gtk+ labels.
 
-Since gtk+ 2.6, Glib 1.12
+Since glib 2.6, Glib 1.12
+
+=back
+
+The following convert filenames to and from URI encoding.  (See also
+L<URI::file>.)
+
+=over 4
+
+=item $string = filename_to_uri ($filename, $hostname)
+
+=item $string = Glib->filename_to_uri ($filename, $hostname)
+
+Return a "file://" schema URI for a filename.  Unsafe and non-ascii chars in
+C<$filename> are escaped with URI "%" forms.
+
+C<$filename> must be an absolute path as a byte string in local filesystem
+encoding.  C<$hostname> is a utf-8 string, or empty or C<undef> for no host
+specified.  For example,
+
+    filename_to_uri ('/my/x%y/<dir>/foo.html', undef);
+    # returns 'file:///my/x%25y/%3Cdir%3E/foo.html'
+
+If C<$filename> is a relative path or C<$hostname> doesn't look like a
+hostname then C<filename_to_uri> croaks with a C<Glib::Error>.
+
+When using the class style C<< Glib->filename_to_uri >> remember that the
+C<$hostname> argument is mandatory.  If you forget then it looks like a
+2-argument call with filename of "Glib" and hostname of what you meant to be
+the filename.
+
+=item $filename = filename_from_uri ($uri)
+
+=item ($filename, $hostname) = filename_from_uri ($uri)
+
+Extract the filename and hostname from a "file://" schema URI.  In scalar
+context just the filename is returned, in array context both filename and
+hostname are returned.
+
+The filename returned is bytes in the local filesystem encoding.  The
+hostname returned is utf-8.  For example,
+
+    ($f,$h) = filename_from_uri ('file://foo.com/r%26b/bar.html');
+    # returns '/r&b/bar.html' and 'foo.com'
+
+If C<$uri> is not a "file:", or is mal-formed, or the hostname part doesn't
+look like a host name then C<filename_from_uri> croaks with a
+C<Glib::Error>.
 
 =back