rb-appscript

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.