Specific features of MacPerl					Matthias Neeracher 15Dec93

This file describes differences between MacPerl and a typical Unix perl
implementation. Much of this information can also be found at the end of
PerlHelp. If you have 411, search for PerlŠMacintoshŠExtensions.

1. VARIA

"\n" on a Mac means ASCII 13, as opposed to Unix, where it means ASCII 10

Pathnames are specified as:

volume:folder:file				for absolute pathnames
:folder:file						for relative pathnames
:file									for relative pathnames
file									for relative pathnames

MacPerl has a limited capability to handle constructs like `command` or
open(F, "|command"), if you are the lucky owner of ToolServer. Additionally, whether
you have toolserver or not, `pwd` and `Directory` (case is significant) always return
the current directory, followed by a newline.

2. SOCKETS

MacPerl has more Socket families than Unix Perl. Additionally, there is a call
choose() to allow the user to interactively specify addresses or file names. As
there are lots of rather complicated data types, there is a library header "GUSI.ph"
which defines packing/unpacking procedures.

Choose() is called as follows:

&MacPerl'Choose(DOMAIN,TYPE,PROMPT,CONSTRAINT,FLAGS,DEFAULT)
&MacPerl'Choose(DOMAIN,TYPE,PROMPT,CONSTRAINT,FLAGS)
&MacPerl'Choose(DOMAIN,TYPE,PROMPT,CONSTRAINT)
&MacPerl'Choose(DOMAIN,TYPE,PROMPT)
         Puts up a modal dialog prompting the user to choose an address. 
         DOMAIN specifies the communication domain, like for socket().
         TYPE may be used by future communication domains to further 
         differentiate within a domain, but is ignored by current domains. 
         PROMPT is a message that will appear in the dialog. CONSTRAINT may 
         be set to a suitable packed value to restrict the types of acceptable
         addresses.

         Examples:

         require "GUSI.ph";
         
         $file = 
            MacPerl'CHoose(
               &GUSI'AF_FILE, 0, "", 
               &GUSI'pack_sa_constr_file("OBJ ", "TEXT"));
                            
                            Return the full pathname of an existing text
                            or MPW object file.
         
         $dir = &MacPerl'Choose(&GUSI'AF_FILE, 0, "", "", &GUSI'CHOOSE_DIR);

                            Return the full pathname of an existing directory.
                            
         $file = 
            &MacPerl'Choose(
               &GUSI'AF_FILE, 0, "", "", 
               &GUSI'CHOOSE_NEW + &GUSI'CHOOSE_DEFAULT, "yo");

                            Return the pathname of a new file to be created.
									 
Socket families are:

Internet:

Packing addresses:	&GUSI'pack_sockaddr_in(family, address, port)
Unpacking addresses:	(family, address, port) = &GUSI'unpack_sockaddr_in(addr)
Choose:					Not available.

Unix:

Packing addresses:	&GUSI'pack_sockaddr_un(family, path)
Unpacking addresses:	(family, path) = &GUSI'unpack_sockaddr_un(addr)
Choose:					choose(&GUSI'AF_UNIX, 0, "", "", 0, "");
							looks up an existing address.
							choose(
								&GUSI'AF_UNIX, 0, "Yes ?", "", 
								&GUSI'CHOOSE_NEW + &GUSI'CHOOSE_DEFAULT, "yo");
							creates a new address.
							No constraints may be specified.

Appletalk (ADSP):

Packing addresses:	&GUSI'pack_sockaddr_atlk(family, net, node, socket) 	(numerical)
							&GUSI'pack_sockaddr_atlk_sym(family, obj, type, zone)	(symbolic)
Unpacking addresses:	(family, net, node, socket) = &GUSI'unpack_sockaddr_atlk(addr)
							(family, obj, type, zone) = &GUSI'unpack_sockaddr_atlk_sym(addr)
Choose:					choose(&GUSI'AF_APPLETALK, 0, "Eh ?", 
								&GUSI'pack_sa_constr_atlk("LaserWriter", "GorillaWriter"),
								0, "");
							looks up an existing address.
							New addresses may not currently be created with choose.

PPC Toolbox:

Packing addresses:	&GUSI'pack_sockaddr_ppc(family, type, name, porttype)
Unpacking addresses:	Not available.
Choose:					choose(&GUSI'AF_PPC, 0, "Eh ?", 
								&GUSI'pack_sa_constr_ppc("Gonkulator"),
								0, "");
							looks up an existing address.
							New addresses may not currently be created with choose.


3. ADDITIONAL FUNCTIONS AVAILABLE IN MACPERL

&MacPerl'Answer(PROMPT)
&MacPerl'Answer(PROMPT,BUTTON1)
&MacPerl'Answer(PROMPT,BUTTON1,BUTTON2)
&MacPerl'Answer(PROMPT,BUTTON1,BUTTON2,BUTTON3)
          Presents to the user a dialog with 1, 2, or 3 buttons. 
          
          Examples:
          
          &MacPerl'Answer("Nunc et in hora mortis nostrae", "Amen");
                              
                            always returns 0.
                            
          &MacPerl'Answer("I refuse");
          
                              is equivalent to &MacPerl'Answer("I refuse", "OK");
          
          &MacPerl'Answer("Delete hard disk ?", "OK", "Cancel");
                  
                            returns 1 for OK, 0 for Cancel
        
          &MacPerl'Answer("Overwrite existig file", "Overwrite", "Skip", "Cancel");
              
                            returns 2 for Overwrite, 1 for Skip, 0 for Cancel
									 
&MacPerl'Ask(PROMPT, DEFAULT)
&MacPerl'Ask(PROMPT)
          Asks the user for a string. A default value may be given. Returns
          undef if the dialog is cancelled.
          
          Example:
          
          $phone = &&MacPerl'Ask("Enter your phone number:");
          $name = &&MacPerl'Ask("Enter your first name", "Bruce");
          
                            Useful for Australian database applications
									 
&MacPerl'Pick(PROMPT, VALUES)
          Asks the user to pick a choice from a list. VALUES is a list of choices. 
          Returns undef if the dialog is cancelled.
          
          Examples:
          
          $color = &MacPerl'Pick("What's your favorite color baby ?", "Red", "Green", "Gold");
			 
&MacPerl'SetFileInfo(CREATOR,TYPE,FILE...)
			Changes the file types and creators of the file(s).

			Examples:

			&MacPerl'SetFileInfo("MPS ", "TEXT", yin, yang);

									Turn yin and yang into MPW text files

&MacPerl'GetFileInfo(FILE)
			In scalar context, returns the file type. In array context, returns
			(creator,type).

			Examples:

			&MacPerl'GetFileInfo(yin);

									Returns "TEXT" or ("MPS ", "TEXT").

&MacPerl'DoAppleScript(SCRIPT)
			Execute an AppleScript script.
			
			Example:
			
			&MacPerl'DoAppleScript(<<END_SCRIPT);
tell application "MacPerl"
	make new Window
	copy "Inserting text the hard way." to character 1 of front Window
end tell
END_SCRIPT

&MacPerl'Reply(ANSWER)
			Reply to current DoScript request. Useful if you are calling Perl 
			scripts from other applications.
			
&MacPerl'Quit(LEVEL)
			If Level is 0, don't quit after ending the script. If 1, quit if 
			running under a runtime version, if 2, always quit.

&MacPerl'LoadExternals(LIBFILE)
			Load XCMD and XFCN extensions contained in file LIBFILE, which is searched
			along the same path as it would be for a require. The extensions are made
			accessible in the current package, unless they conatin an explicit package
			name.

&MacPerl'DebugExternals(DEBUGLEVEL)
			If DEBUGLEVEL is 0, don't print any debug information for XCMDs and XFCNs. 
			If 1, print information for unimplemented callbacks. If 2, print 
			informations for all callbacks.

&MacPerl'FAccess(FILE, CMD, ARGS)
			When called from the tool, manipulate various information of files. To 
			get the command constants, it's convenient to require "FAccess.ph".

	$TAB = &MacPerl'FAccess(FILE, &F_GTABINFO)
	&MacPerl'FAccess(FILE, &F_STABINFO, TAB)
			Manipulate tabulator setting (in spaces per tab).
			
	($FONTNAME, $FONTSIZE) = &MacPerl'FAccess(FILE, &F_GFONTINFO)
	$FONTNUM = &MacPerl'FAccess(FILE, &F_GFONTINFO)
	&MacPerl'FAccess(FILE, &F_SFONTINFO, FONT [, SIZE])
			Manipulate font and size information. Both font names and font numbers
			are accepted for F_SFONTINFO; F_GFONTINFO returns a font name in an
			array context, a font number in a scalar context.
			
	($STARTSEL, $ENDSEL, $DISPLAYTOP) = &MacPerl'FAccess(FILE, &F_GSELINFO)
	$STARTSEL = &MacPerl'FAccess(FILE, &F_GSELINFO)
	&MacPerl'FAccess(FILE, &F_SSELINFO, $STARTSEL, $ENDSEL [, $DISPLAYTOP])
			Manipulate the MPW selection of a file.
			
	($LEFT, $TOP, $RIGHT, $BOTTOM) = &MacPerl'FAccess(FILE, &F_GWININFO)
	$TOP = &MacPerl'FAccess(FILE, &F_GWININFO)
	&MacPerl'FAccess(FILE, &F_SWININFO, LEFT, TOP [, RIGHT, BOTTOM])
			Manipulate the window position.

.