Documentation for the aepack and aetypes modules, by Vincent Marchetti

<vincem@en.com>.

2 files changed, 112 insertions, 0 deletions

diff --git a/Doc/mac/libaepack.tex b/Doc/mac/libaepack.tex
new file mode 100644
index 0000000..2dfee0b
--- /dev/null
+++ b/Doc/mac/libaepack.tex
@@ -0,0 +1,73 @@
+\section{\module{aepack} ---
+         Conversion between Python variables and AppleEvent data containers}
+
+\declaremodule{standard}{aepack}
+  \platform{Mac}
+%\moduleauthor{Jack Jansen?}{email}
+\modulesynopsis{Conversion between Python variables and AppleEvent
+                data containers.}
+\sectionauthor{Vincent Marchetti}{vincem@en.com}
+
+
+The \module{aepack} module defines functions for converting (packing)
+Python variables to AppleEvent descriptors and back (unpacking).
+Within Python the AppleEvent descriptor is handled by Python objects
+of built-in type \pytype{AEDesc}, defined in module \refmodule{AE}.
+
+The \module{aepack} module defines the following functions:
+
+
+\begin{funcdesc}{pack}{x\optional{, forcetype}}
+Returns an \class{AEDesc} object  containing a conversion of Python
+value x. If \var{forcetype} is provided it specifies the descriptor
+type of the result. Otherwise, a default mapping of Python types to
+Apple Event descriptor types is used, as follows:
+
+\begin{tableii}{l|l}{textrm}{Python type}{descriptor type}
+  \lineii{\class{FSSpec}}{typeFSS}
+  \lineii{\class{Alias}}{typeAlias}
+  \lineii{integer}{typeLong (32 bit integer)}
+  \lineii{float}{typeFloat (64 bit floating point)}
+  \lineii{string}{typeText}
+  \lineii{list}{typeAEList}
+  \lineii{dictionary}{typeAERecord}
+  \lineii{instance}{\emph{see below}}
+\end{tableii}  
+ 
+\pytype{FSSpec} and \pytype{Alias} are built-in object types defined
+in the module \refmodule{macfs}. 
+  
+If \var{x} is a Python instance then this function attempts to call an
+\method{__aepack__()} method.  This method should return an
+\pytype{AE.AEDesc} object.
+
+If the conversion \var{x} is not defined above, this function returns
+the Python string representation of a value (the repr() function)
+encoded as a text descriptor.
+\end{funcdesc}
+
+\begin{funcdesc}{unpack}{x}
+  \var{x} must be an object of type \class{AEDesc}. This function
+  returns a Python object representation of the data in the Apple
+  Event descriptor \var{x}. Simple AppleEvent data types (integer,
+  text, float) are returned as their obvious Python counterparts.
+  Apple Event lists are returned as Python lists, and the list
+  elements are recursively unpacked.  Object references
+  (ex. \code{line 3 of document 1}) are returned as instances of
+  \class{aetypes.ObjectSpecifier}.  AppleEvent descriptors with
+  descriptor type typeFSS are returned as \class{FSSpec}
+  objects.  AppleEvent record descriptors are returned as Python
+  dictionaries, with keys of type \class{?} and elements recursively
+  unpacked.
+\end{funcdesc}
+
+
+\begin{seealso}
+  \seemodule{AE}{Built-in access to Apple Event Manager routines.}
+  \seemodule{aetypes}{Python definitions of codes for Apple Event
+                      descriptor types.}
+  \seetitle[http://developer.apple.com/techpubs/mac/IAC/IAC-2.html]{
+            Inside Macintosh: Interapplication
+            Communication}{Information about inter-process
+            communications on the Macintosh.}
+\end{seealso}
diff --git a/Doc/mac/libaetypes.tex b/Doc/mac/libaetypes.tex
new file mode 100644
index 0000000..0c2795a
--- /dev/null
+++ b/Doc/mac/libaetypes.tex
@@ -0,0 +1,39 @@
+\section{\module{aetypes} ---
+         AppleEvent objects}
+
+\declaremodule{standard}{aetypes}
+  \platform{Mac}
+%\moduleauthor{Jack Jansen?}{email}
+\modulesynopsis{Python representation of the Apple Event Object Model.}
+\sectionauthor{Vincent Marchetti}{vincem@en.com}
+
+
+The \module{aetypes} defines classes used to represent Apple Event
+object specifiers. An object specifier is essentially an address of an
+object implemented in a Apple Event server. An Apple Event specifier
+is used as the direct object for an Apple Event or as the argument of
+an optional parameter. In AppleScript an object specifier is
+represented by a phrase such as:
+\code{character 23 of document "Semprini"}. The classes defined in
+this module allow this specifier to be represented by a Python object
+which is initialized as follows:
+\code{res = Document(1).Character(23)}
+
+
+The \module{AEObjects} module defines the following class:
+
+\begin{classdesc}{ObjectSpecifier}{want, form, seld, from}
+  This is the base class for representing object specifiers and is
+  generally not constructed directly by the user. Its important
+  functionality is to define an \function{__aepack__()} function,
+  which returns the Apple Event descriptor containing the object
+  specifier.  Its data members, set directly from the constructor
+  arguments, are:
+\end{classdesc}
+
+\begin{memberdesc}{want}
+  A four character string representing the class code of the
+  object. These class codes are specified in Apple Event Suites; for
+  example the standard code for a character object is the 4 bytes
+  \samp{char}.
+\end{memberdesc}