home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 7 / Apprentice-Release7.iso / Source Code / C / Applications / MacPerl 5.1.3 / Mac_Perl_513_src / perl5.002 / pod / macperl.pod < prev    next >
Encoding:
Text File  |  1996-08-18  |  9.3 KB  |  369 lines  |  [TEXT/MPS ]
  1. =head1 NAME
  2.  
  3. macperl - MacPerl specific features
  4.  
  5. =head1 DESCRIPTION
  6.  
  7. This file describes differences between MacPerl and a typical Unix perl
  8. implementation. 
  9.  
  10. =head2 VARIA
  11.  
  12. All time related functions measure time in seconds from 1904, not 1970 as in
  13. Unix.
  14.  
  15. "\n" on a Mac means ASCII 13, as opposed to Unix, where it means ASCII 10. If 
  16. you want ASCII 10, write "\012".
  17.  
  18. Pathnames are specified as:
  19.  
  20.     volume:folder:file              for absolute pathnames
  21.     :folder:file                    for relative pathnames
  22.     :file                           for relative pathnames
  23.     file                            for relative pathnames
  24.  
  25. MacPerl has a limited capability to handle constructs like `command` or
  26. C<open(F, "|command")>, if you are the lucky owner of ToolServer. Additionally, 
  27. whether you have toolserver or not, a few commands are implemented:
  28.  
  29. =over 5
  30.  
  31. =item *
  32.  
  33. `pwd` and `Directory` (case is significant) always return the current directory, 
  34. followed by a newline.
  35.  
  36. =item *
  37.  
  38. `hostname` returns the name of the current Mac if MacTCP is running.
  39.  
  40. =item * 
  41.  
  42. `glob xxx` expands the glob pattern xxx and returns a list of expanded file
  43. names. Only "*" and "?" are supported, with Option-x as an (MPW-style) 
  44. alternative to "*".
  45.  
  46. =item *
  47.  
  48. `stty raw` or `stty -sane` in the MacPerl application switch the console window
  49. to "raw" mode, i.e. turn off eching to the window and editing. `stty sane` or
  50. `stty -raw` restores normal mode.
  51.  
  52. =back
  53.  
  54. =head2 SOCKETS
  55.  
  56. MacPerl has more Socket families than Unix Perl. Additionally, there is a call
  57. choose() to allow the user to interactively specify addresses or file names. As
  58. there are lots of rather complicated data types, there is a library header "GUSI.ph"
  59. which defines packing/unpacking procedures.
  60.  
  61. Choose() is called as follows:
  62.  
  63. =over 8
  64.  
  65. =item MacPerl::Choose DOMAIN, TYPE, PROMPT, CONSTRAINT, FLAGS, DEFAULT
  66.  
  67. =item MacPerl::Choose DOMAIN, TYPE, PROMPT, CONSTRAINT, FLAGS
  68.  
  69. =item MacPerl::Choose DOMAIN, TYPE, PROMPT, CONSTRAINT
  70.  
  71. =item MacPerl::Choose DOMAIN, TYPE, PROMPT
  72.  
  73. Puts up a modal dialog prompting the user to choose an address. DOMAIN specifies 
  74. the communication domain, like for socket(). TYPE may be used by future 
  75. communication domains to further differentiate within a domain, but is ignored by 
  76. current domains. PROMPT is a message that will appear in the dialog. CONSTRAINT 
  77. may be set to a suitable packed value to restrict the types of acceptable addresses.
  78.  
  79. Examples:
  80.  
  81.      require "GUSI.ph";
  82.  
  83.      $file = 
  84.         MacPerl::Choose(
  85.            GUSI::AF_FILE, 0, "", 
  86.            GUSI::pack_sa_constr_file("OBJ ", "TEXT"));
  87.  
  88. Return the full pathname of an existing text
  89. or MPW object file.
  90.  
  91.      $dir = MacPerl::Choose(GUSI::AF_FILE, 0, "", "", GUSI::CHOOSE_DIR);
  92.  
  93. Return the full pathname of an existing directory.
  94.  
  95.      $file = 
  96.         MacPerl::Choose(
  97.            GUSI::AF_FILE, 0, "", "", 
  98.            GUSI::CHOOSE_NEW + GUSI::CHOOSE_DEFAULT, "yo");
  99.  
  100. Return the pathname of a new file to be created.
  101.  
  102. =back 
  103.  
  104. Socket families are:
  105.  
  106. =over 8
  107.  
  108. =item Internet
  109.  
  110. Packing an address:
  111.  
  112.     GUSI::pack_sockaddr_in(GUSI::AF_INET, address, port);
  113.  
  114. Unpacking an address:
  115.  
  116.     (family, address, port) = GUSI::unpack_sockaddr_in(addr);
  117.  
  118. Choose is not available.
  119.  
  120. =item Unix
  121.  
  122. Packing an address:
  123.  
  124.     GUSI'pack_sockaddr_un(GUSI::AF_UNIX, path)
  125.  
  126. Unpacking an address:
  127.  
  128.     (family, path) = GUSI::unpack_sockaddr_un(addr);
  129.  
  130. Choose: looking up an existing address:
  131.  
  132.     MacPerl::Choose(GUSI::AF_UNIX, 0, "", "", 0, "");
  133.  
  134. Creating a new address (No constraints may be specified):
  135.  
  136.     MacPerl::Choose(GUSI::AF_UNIX, 0, "Yes ?", "", 
  137.            GUSI::CHOOSE_NEW + GUSI::CHOOSE_DEFAULT, "yo");
  138.  
  139. =item Appletalk (ADSP)
  140.  
  141. Packing an address (numerical):
  142.  
  143.     GUSI::pack_sockaddr_atlk(GUSI::AF_APPLETALK, net, node, socket) 
  144.  
  145. Packing an address (symbolic):
  146.  
  147.     GUSI::pack_sockaddr_atlk_sym(GUSI::ATALK_SYMADDR, obj, type, zone)
  148.  
  149. Unpacking an address:
  150.  
  151.     (family, net, node, socket) = GUSI::unpack_sockaddr_atlk(addr)
  152.     (family, obj, type, zone)   = GUSI::unpack_sockaddr_atlk_sym(addr)
  153.  
  154. Choose: look up an existing address:
  155.  
  156.     MacPerl::Choose(GUSI::AF_APPLETALK, 0, "Eh ?", 
  157.            GUSI::pack_sa_constr_atlk("LaserWriter", "GorillaWriter"),
  158.            0, "");
  159.  
  160. New addresses may not currently be created with choose.
  161.  
  162. =item PPC Toolbox
  163.  
  164. Packing an address:
  165.  
  166.     GUSI'pack_sockaddr_ppc(GUSI::AF_PPC, type, name, porttype)
  167.  
  168. Unpacking addresses not available.
  169.  
  170. Choose: look up an existing address:
  171.  
  172.     MacPerl::Choose(GUSI::AF_PPC, 0, "Eh ?", 
  173.         GUSI::pack_sa_constr_ppc("Gonkulator"),
  174.         0, "");
  175.  
  176. New addresses may not currently be created with choose.
  177.  
  178. =back
  179.  
  180. =head2 ADDITIONAL FUNCTIONS AVAILABLE IN MACPERL
  181.  
  182. =over 8
  183.  
  184. =item MacPerl::Answer(PROMPT)
  185. =item MacPerl::Answer(PROMPT,BUTTON1)
  186. =item MacPerl::Answer(PROMPT,BUTTON1,BUTTON2)
  187. =item MacPerl::Answer(PROMPT,BUTTON1,BUTTON2,BUTTON3)
  188.  
  189. Presents to the user a dialog with 1, 2, or 3 buttons. 
  190.  
  191. Examples:
  192.  
  193.     MacPerl::Answer("Nunc et in hora mortis nostrae", "Amen");
  194.  
  195. always returns 0.
  196.  
  197.     MacPerl::Answer("I refuse");
  198.  
  199. is equivalent to C<&MacPerl'Answer("I refuse", "OK");>
  200.  
  201.     MacPerl::Answer("Delete hard disk ?", "OK", "Cancel");
  202.  
  203. returns 1 for OK, 0 for Cancel
  204.  
  205.     MacPerl::Answer("Overwrite existig file", "Overwrite", "Skip", "Cancel");
  206.  
  207. returns 2 for Overwrite, 1 for Skip, 0 for Cancel
  208.  
  209. =item MacPerl::Ask(PROMPT, DEFAULT)
  210. =item MacPerl::Ask(PROMPT)
  211.  
  212. Asks the user for a string. A default value may be given. Returns
  213. undef if the dialog is cancelled.
  214.  
  215. Example:
  216.  
  217.     $phone = MacPerl::Ask("Enter your phone number:");
  218.     $name  = MacPerl::Ask("Enter your first name", "Bruce");
  219.  
  220. Useful for Australian database applications
  221.  
  222. =item MacPerl::Pick(PROMPT, VALUES)
  223.  
  224. Asks the user to pick a choice from a list. VALUES is a list of choices. 
  225. Returns undef if the dialog is cancelled.
  226.  
  227. Examples:
  228.  
  229.     $color = MacPerl::Pick("What's your favorite color baby ?", "Red", "Green", "Gold");
  230.  
  231. =item MacPerl::SetFileInfo(CREATOR,TYPE,FILE...)
  232.  
  233. Changes the file types and creators of the file(s).
  234.  
  235. Examples:
  236.  
  237.     MacPerl::SetFileInfo("MPS ", "TEXT", yin, yang);
  238.  
  239. Turn yin and yang into MPW text files
  240.  
  241. =item MacPerl::GetFileInfo(FILE)
  242.  
  243. In scalar context, returns the file type. In array context, returns (creator,type).
  244.  
  245. Examples:
  246.  
  247.     MacPerl::GetFileInfo(yin);
  248.  
  249. Returns "TEXT" or ("MPS ", "TEXT").
  250.  
  251. =item MacPerl::DoAppleScript(SCRIPT)
  252.  
  253. Execute an AppleScript script.
  254.  
  255. Example:
  256.  
  257.     MacPerl::DoAppleScript(<<END_SCRIPT);
  258.     tell application "MacPerl"
  259.         make new Window
  260.         copy "Inserting text the hard way." to character 1 of front Window
  261.     end tell
  262.     END_SCRIPT
  263.  
  264. =item MacPerl::Reply(ANSWER)
  265.  
  266. Reply to current DoScript request. Useful if you are calling Perl 
  267. scripts from other applications.
  268.  
  269. =item MacPerl::Quit(LEVEL)
  270.  
  271. If LEVEL is 0, don't quit after ending the script. If 1, quit if 
  272. running under a runtime version, if 2, always quit. If LEVEL is 3,
  273. quit if this was the first script to be run since starting MacPerl.
  274.  
  275. =item MacPerl::LoadExternals(LIBFILE)
  276.  
  277. Load XCMD and XFCN extensions contained in file LIBFILE, which is searched
  278. along the same path as it would be for a require. The extensions are made
  279. accessible in the current package, unless they containing an explicit package
  280. name.
  281.  
  282. =item MacPerl::DebugExternals(DEBUGLEVEL)
  283.  
  284. If DEBUGLEVEL is 0, don't print any debug information for XCMDs and XFCNs. 
  285. If 1, print information for unimplemented callbacks. If 2, print 
  286. informations for all callbacks.
  287.  
  288. =item MacPerl::FAccess(FILE, CMD, ARGS)
  289.  
  290. When called from the tool, manipulate various information of files. To 
  291. get the command constants, it's convenient to require "FAccess.ph".
  292.  
  293. =over 8
  294.  
  295. =item $TAB = MacPerl::FAccess(FILE, F_GTABINFO)
  296.  
  297. =item MacPerl::FAccess(FILE, F_STABINFO, TAB)
  298.  
  299. Manipulate tabulator setting (in spaces per tab).
  300.  
  301. =item ($FONTNAME, $FONTSIZE) = MacPerl::FAccess(FILE, F_GFONTINFO)
  302.  
  303. =item $FONTNUM = MacPerl::FAccess(FILE, F_GFONTINFO)
  304.  
  305. =item MacPerl::FAccess(FILE, F_SFONTINFO, FONT [, SIZE])
  306.  
  307. Manipulate font and size information. Both font names and font numbers
  308. are accepted for F_SFONTINFO; F_GFONTINFO returns a font name in an
  309. array context, a font number in a scalar context.
  310.  
  311. =item ($STARTSEL, $ENDSEL, $DISPLAYTOP) = MacPerl::FAccess(FILE, F_GSELINFO)
  312.  
  313. =item $STARTSEL = MacPerl::FAccess(FILE, F_GSELINFO)
  314.  
  315. =item MacPerl::FAccess(FILE, F_SSELINFO, $STARTSEL, $ENDSEL [, $DISPLAYTOP])
  316.  
  317. Manipulate the MPW selection of a file.
  318.  
  319. =item ($LEFT, $TOP, $RIGHT, $BOTTOM) = MacPerl::FAccess(FILE, F_GWININFO)
  320. =item $TOP = MacPerl::FAccess(FILE, F_GWININFO)
  321. =item MacPerl::FAccess(FILE, F_SWININFO, LEFT, TOP [, RIGHT, BOTTOM])
  322.  
  323. Manipulate the window position.
  324.  
  325. =back
  326.  
  327. =item MacPerl::MakeFSSpec(PATH)
  328.  
  329. This command encodes a path name into an encoding (volume #, directory #,
  330. File name) which is guaranteed to be unique for every file. Don't store
  331. this encoding between runs of MacPerl!
  332.  
  333. =item MacPerl::MakePath(FSSPEC)
  334.  
  335. The inverse of MacPerl::MakeFSSpec(): turn an encoding into a path name.
  336.  
  337. =item MacPerl::Volumes()
  338.  
  339. In scalar context, return the FSSPEC of the startup volume. In list context, 
  340. return FSSPECs of all volumes.
  341.  
  342. =back
  343.  
  344. =head2 MACPERL SPECIFIC LIBRARIES
  345.  
  346. =over 8
  347.  
  348. =item StandardFile.pl   
  349.  
  350. Calls for standard file dialogs. A very convenient front end for MacPerl::Choose()
  351.  
  352. =item FindFolder.pl     
  353.  
  354. Returns the path names of special folders (System, Preferences).
  355.  
  356. =item CommConnect.pl   
  357.  
  358. Library for accessing the serial port.
  359.  
  360. =item GUSI.ph           
  361.  
  362. Definitions for socket related calls.
  363.  
  364. =item FAccess.ph        
  365.  
  366. Definitions for MacPerl::FAccess() (MPW tool only).
  367.  
  368. =back
  369.