rb-appscript

3. Packing and unpacking data

Codecs

The AEM::Codecs class provides methods for converting Ruby data to AE::AEDesc objects, and vice-versa.

Codecs

    Constructor:
        new

    Methods:
        
        # pack/unpack data
        
        pack(data) -- convert Ruby data to an AEDesc; will raise
                a TypeError if data's type/class is unsupported
            data : anything
            Result : AEDesc

        unpack(desc) -- convert an AEDesc to Ruby data; will return
                the AEDesc unchanged if it's an unsupported type
            desc : AEDesc
            Result : anything
        
        # compatibility options
        
        add_unit_types(types) -- register custom unit type 
                definitions
            types : list -- a list of lists, where each sublist  
                    is of form [name, code, pack_proc, unpack_proc] 
                    or [name, code]; if the packer and unpacker 
                    procs are omitted, the AEDesc data is packed/
                    unpacked as a double-precision float
        
        dont_cache_unpacked_specifiers -- by default, object 
                specifier descriptors returned by an application 
                are reused for efficiency; invoke this method to 
                use AppleScript-style behavior instead (i.e. fully 
                unpacking and repacking object specifiers each time) 
                for better compatibility with problem applications
        
        pack_strings_as_type(code) -- by default, strings are 
                packed as typeUnicodeText descriptors; some older 
                non-Unicode-aware applications may require text 
                to be supplied as typeChar/typeIntlText descriptors
            code : String -- four-char code, e.g. KAE::TypeChar 
                    (see KAE module for available text types)
        
        use_ascii_8bit -- by default, text descriptors are unpacked 
                as Strings with UTF-8 Encoding on Ruby 1.9+; invoke 
                this method to mimic Ruby 1.8-style behavior where 
                Strings contain UTF-8 encoded data and ASCII-8BIT 
                Encoding
        
        use_datetime -- by default, dates are unpacked as Time 
                instances; invoke this method to unpack dates as 
                DateTime instances instead

AE types

The Apple Event Manager defines several types for representing type/class names, enumerator names, etc. that have no direct equivalent in Ruby. Accordingly, aem defines several classes to represent these types on the Ruby side. All share a common abstract base class, AETypeBase:

AETypeBase -- Abstract base class

    Constructor:
        new(code)
            code : str -- a four-character Apple event code

    Methods:
        code
            Result : str -- Apple event code

The four concrete classes are:

AEType < AETypeBase -- represents an AE object of typeType


AEEnum < AETypeBase -- represents an AE object of typeEnumeration


AEProp < AETypeBase -- represents an AE object of typeProperty


AEKey < AETypeBase -- represents an AE object of typeKeyword