NAME
Mac::Carbon - Access to Mac OS Carbon API
SYNOPSIS
use Mac::Carbon;
use Mac::Carbon qw(:files :morefiles);DESCRIPTION
This module provides documentation of the Mac::Carbon modules, and acts as a frontend to them.
Mac::Carbon is a collection of perl modules for accessing the Carbon API under Mac OS X. It is a port of the Toolbox modules written by Matthias Neeracher for MacPerl.
This module will load in all the Carbon modules, and export all of the functions, constants, and other variables. An export tag is set up for each module, so they may be selected individually.
This module exists primarily because in Mac OS X, all the Carbon functions are imported into a C program with a single header, Carbon.h, so Mac OS X users may prefer to load in the entire Carbon API with a single module.
For detailed information on the Carbon API (highly recommended, as a familiarity with Carbon is assumed in the POD), see apple.com.
http://developer.apple.com/techpubs/macosx/Carbon/The modules were written for Mac OS originally, and are in part being ported to Carbon. You may also be interested in the original documentation.
http://developer.apple.com/techpubs/macos8/TOOLBOX MAPPINGS
Swiped from Mac/Toolbox.pod in the MacPerl distribution.
The Macintosh Operating System provides a rich API with thousands of toolbox calls. The MacPerl toolbox modules aim to make as much as possible of this functionality available to MacPerl programmers. The mapping of the toolbox interfaces into MacPerl is intended to be
Convenient to use for Perl programmers.
As close as possible to the C interfaces.
This translates into a mapping strategy which is discussed in the following sections.
Function mappings
MacPerl toolbox calls take their input arguments in the same order as the corresponding toolbox functions. Output arguments are never passed by reference, but returned from the calls. If there are several output arguments, a list is returned. If an error occurs, the function returns undef or () and the error code is available in the $^E variable.
$port = GetPort();
SetPort($port);
$desc = AECreateDesc("TEXT", "Hello, World") or die $^E;Data structure mappings
Complex data structures are mapped into blessed references. Data fields are available through member functions which return the value of a field if called without an argument and change the value if called with an argument.
$rect = Rect->new(10, 20, 110, 220);
$rect->top;
$rect->right(250);MAC OS X DIFFERENCES
The modules follow the same API under Mac OS X as Mac OS, except that the non-Carbon API is not supported (for example, NewHandle is supported, but NewHandleSys is not). Calling a function not supported by Carbon will generate an exception.
The MacPerl package is automatically bootstrapped in MacPerl; it is included here, though functions specific to the application and GUI (Answer, Pick, Reply, Quit, etc.) are not supported, and the MacPerl package must be loaded explicitly (e.g., use MacPerl;).
The Mac-specific error codes are put in $^E as in MacPerl, but $^E does not automatically convert the numeric error into a string in string context. See brian d foy's Mac::Errors module on the CPAN for this:
use Mac::Errors '$MacError';
my $info1 = FSpGetCatInfo($file1) or die $^E + 0; # error number
my $info2 = FSpGetCatInfo($file2) or die $MacError; # error stringMac::Errors is not included with or required by Mac::Carbon, but it is highly recommended.
$! is set at the same time $^E is set. This is different behavior from MacPerl, but similar to other platforms. On MacPerl, $^E is signed, and on Unix it is unsigned, so to get the numeric value from $^E, just add 0, as above. Could be worse.
Files are passed back and forth using Unix/POSIX filespecs (if you care about the gory details, a portion of the GUSI API has been reimplemented here, and it handles the conversions). Similarly, times are converted back and forth from the Mac OS epoch to the Unix epoch.
The support functions are in Carbon.h. See that file for descriptions of the issues, including bugs and possibilities for bugs, involved.
KNOWN BUGS
Docs not updated for Carbon incompatibilities (including changes to Processes fields). Generate list of all unsupported functions.
Deal with xsubpp issues (README).
Related to xsubpp issues, embedded POD in .xs should somehow be moved to .pm files (perhaps the new preprocessor could automatically dump the POD into the corresponding .pm file). This currently causes an error during the build, and results in man pages not being properly created, with all the documentation.
Test suite needs a lot of work. There are surely bugs to be uncovered in a test suite. All modules have been tested to some degree, but more exhaustive testing needs to happen.
Not specific to the Carbon versions: the Mac:: modules define classes such as
Handlewhich probably should be something else, likeMac::HandleorMac::Carbon::HandleorMac::Memory::Handle(other examples includeAEDesc,Point,Rect). No one has really complained before except on principle, but still ...In Mac::Processes, there are some issues with unsupported fields in the ProcessInfo struct.
In Mac::MoreFiles, FSpDTGetAPPL is very slow, as it has to fall back on CatSearch(). And worse, it doesn't find applications that don't have the creator/type in the application, but in the PkgInfo file. If this acceptable, then the tied %Application hash should be implemented differently.
In MacPerl package, perhaps support Ask/Answer/Pick via DoAppleScript.
Can we support XCMDs etc. via XL? Do we want to?
PACKAGES AND EXPORT TAGS
See each individual module for more information on use. See README for more information about modules not included here.
Mac::Components components
Mac::Files files
Mac::Gestalt gestalt
Mac::Memory memory
Mac::MoreFiles morefiles
Mac::Notification notification
Mac::Processes processes
Mac::Resources resources
Mac::Sound sound
Mac::Speech speech
Mac::Types types
MacPerl macperlAUTHOR
The Mac Toolbox modules were written by Matthias Neeracher <neeracher@mac.com>. They are currently maintained by Chris Nandor <pudge@pobox.com>.
SEE ALSO
perl(1).