mactypes

What is mactypes?

The mactypes module provides user-friendly wrappers for OS X Alias and FileURL objects, commonly used by scriptable applications to identify filesystem objects and locations, and for unit type values used by some applications to represent lengths, etc. It is automatically imported when requiring appscript, aem or osax.

Note that most scriptable applications do not use or understand POSIX paths, and while the Apple Event Manager does provide some built-in coercions for converting between path strings and alias/file objects, these work with HFS paths only. Therefore, when specifying files and folders to scriptable applications, use MacTypes::Alias and MacTypes::FileURL objects - not path strings - unless otherwise indicated.

MacTypes::Alias

The Alias class represents a persistent reference to a filesystem object. Aliases keep track of filesystem objects even if they're renamed or moved to another location on the same disk.

Methods

Alias -- a persistent reference to a filesystem object
    Constructors:

        Alias.path(path) -- make Alias object from POSIX path string

        Alias.hfs_path(path) -- make Alias object from HFS path string

        Alias.url(url) -- make Alias object from a local file:// URL string
    
        Alias.desc(desc) -- make Alias object from an AE::AEDesc
                            of TypeAlias

    Methods:

        ==

        hash
    
        inspect
    
        path -- returns POSIX path string to the object's current location
    
        hfs_path -- returns HFS path string to the object's current location

        url -- returns file:// URL string to the object's current location

        desc -- returns AE::AEDesc of TypeAlias

        to_s -- synonym for #path
    
        to_alias -- returns self
    
        to_file_url -- returns a MacTypes::FileURL object

Examples

require "appscript"

f = MacTypes::Alias.path('/Users/foo/some file')

puts f.to_s
# /Users/foo/some file

puts f.url
# file://localhost/Users/foo/some%20file

puts f.inspect
# MacTypes::Alias.path("/Users/foo/some file")

Appscript.app('TextEdit').open(f)
# opens document in TextEdit

Notes

Comparing an Alias object against a FileURL object always returns false, even if both point to the same location.

Remember that aliases can change when the corresponding filesystem object is moved, so take care when using Alias objects in situations that involve comparing or hashing them (e.g. Hash keys).

MacTypes::FileURL

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 insteaf:

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.

MacTypes::FileNotFoundError

FileNotFoundError is a subclass of RuntimeError. It is raised by Alias and FileURL objects when an operation that only works for existing filesystem objects/locations fails. For example:

require "appscript"

MacTypes::Alias.path('/some/non/existent/location')
# raises FileNotFoundError

MacTypes::Units

The Units class represents a measurement of some sort, e.g. 3 inches, 98.5 degrees Fahrenheit.

class Units

    Constructor:

        Units.new(value, type)
            value : Fixnum | Bignum | Float -- the amount, e.g. 3.5
            type : Symbol -- the unit of measurement, e.g. :centimeters

    Methods:

        ==

        hash

        inspect

        value -- returns the amount

        type -- returns the unit of measurement

        to_i -- returns the amount as an integer

        to_f -- returns the amount as a float

        to_s -- returns the measurement as a string, e.g. "3.5 centimeters"

The following unit types are defined as standard:

:centimeters                   :cubic_inches
:meters                        :cubic_feet
:kilometers                    :cubic_yards
:inches                        
:feet                          :liters
:yards                         :quarts
:miles                         :gallons
                               
:square_meters                 :grams
:square_kilometers             :kilograms
:square_feet                   :ounces
:square_yards                  :pounds
:square_miles                  
                               :degrees_Celsius
:cubic_centimeters             :degrees_Fahrenheit
:cubic_meters                  :degrees_Kelvin

Additional application-specific unit types can be added if needed.