3. The MacTypes::FileURL
class
The FileURL
class represents a fixed filesystem location. This may be deterministic (i.e. existing locations only) or non-deterministic depending on how the object is created.
Methods
FileURL -- identifies a fixed filesystem location
Constructors:
FileURL.path(path) -- make FileURL object from POSIX path string
FileURL.hfs_path(path) -- make FileURL object from HFS path string
FileURL.url(url) -- make FileURL object from a local file:// URL string
FileURL.desc(desc) -- make FileURL object from an AE::AEDesc
of TypeFSS, TypeFSRef or TypeFileURL
Methods:
==
hash
inspect
path -- returns POSIX path string
hfs_path -- returns HFS path string
url -- returns file:// URL string
desc -- returns AE::AEDesc of TypeFSRef, TypeFSS or TypeFileURL
to_s -- synonym for #path
to_alias -- returns a MacTypes::Alias object
to_file_url -- returns a new MacTypes::FileURL object
Examples
require "appscript"
f = MacTypes::FileURL.path('/Users/foo/new file')
puts f.to_s
# /Users/foo/new file
puts f.url
# file://localhost/Users/foo/some%20file
puts f.inspect
# MacTypes::FileURL.path("/Users/foo/new file")
Appscript.app('TextEdit').documents[1].save(:in => f)
# saves front TextEdit document at the given location
Notes
Unlike the Alias
class which wraps TypeAlias
values only, the FileURL
class provides a uniform wrapper for several file-related types that may be returned by applications: TypeFSS
, TypeFSRef
and TypeFileURL
. When passing FileURL
values to applications, you should not normally need to worry about which value type a FileURL
object contains as well-designed applications will ask the Apple Event Manager to coerce the given value to the desired type as necessary.
When dealing with less well-behaved applications, however, you may need to pass an AEDesc of a specific type. In this case you should use the desc
method to obtain an AE::AEDesc
object, then call its coerce
method to obtain an AEDesc of the desired type. For example, if an older Carbon application refuses to accept a FileURL identifying a non-existing file location, you may need to provide a FSSpec instead:
require "appscript"
file_url = MacTypes::FileURL.path('/Users/foo/new file')
fs_spec = file_url.desc.coerce(KAE::TypeFSS)
Appscript.app('older app').documents[1].save(:in => fs_spec)
When used in an application command, a FileURL
object returned by appscript will always pack into the same TypeFSRef
, TypeFileURL
or TypeFSS
AEDesc it was created from. A FileURL
object returned by FileURL.path
, Alias#to_file_url
or FileURL#to_file_url
will always pack into an AEDesc of TypeFileURL
.
When comparing FileURL
objects for equality, be aware that FileURL#==
always performs case-sensitive comparisons, regardless of how the underlying filesystem handles case-[in]sensitivity.
Note that AEDescs of TypeFSRef
can represent existing filesystem locations only. AEDescs of TypeFileURL
can represent both existing and non-existing locations. AEDescs of TypeFSS
(FSSpecs) are deprecated on Mac OS X due to lack of proper Unicode and long filename support, and are retained for backwards compatibility with older applications only.
Be aware that FileURL#==
does not normalize file URLs; thus minor differences in capitalization, etc. can result in FileURL#==
returning false
even if both objects happen to identify the same filesystem location.