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 / MacPerl5 / MacPerl.Frontend < prev    next >
Encoding:
Text File  |  1996-02-01  |  11.2 KB  |  5 lines  |  [TEXT/MPS ]
  1. Front end features of MacPerl                    Matthias Neeracher 03Dec94
  2.  
  3. This file describes features only present in the MacPerl application, which
  4. are not directly related to the language itself.
  5.  
  6. 1. USER INTERFACE
  7.  
  8. This area is notoriously underdocumented. I can't give more than hints at the moment
  9. (I have a standing offer to write decent manuals if anybody researches and writes my 
  10. PhD thesis for me :-):
  11.  
  12. a) Online Help
  13.  
  14. Selecting any perl operator and choosing Help from the Help menu (That's the question 
  15. mark icon on the right side of the menubar) will give you chapter and verse from the
  16. Perl manual page.
  17.  
  18. If you turn on Balloon Help and point at a Perl operator, a balloon will give you
  19. a summary of parameters to the operator.
  20.  
  21. a) Menus
  22.  
  23. MacPerl for the most part tries to behave like a typical primitive text editor.
  24. "Format" in the Edit menu presents a choice of text fonts and sizes. "Preferences"
  25. controls many settings, the most important of which is a list of library folders.
  26.  
  27. "Jump to…" in the Edit menu allows to pop up files and lines based on the current 
  28. selection. The following formats are supported:
  29.  
  30.    Format                                  Example
  31.    /File\s+["']([^"']+)["']\D*(\d+)/i      File "om:mani:padme:hum", Line 23
  32.    /["']([^"']+)["']\D*(\d+)/              "om:mani:padme:hum", Line 23
  33.    /["']([^"']+)["']/                      "om:mani:padme:hum"
  34.    /.+/                                           om:mani:padme:hum
  35.     
  36. 2. PACKAGES
  37.  
  38. A MacPerl file can be saved in various forms, depending on what you choose 
  39. from the popup menu in the "Save As..." dialog:
  40.  
  41.  - A plain text file. These can be opened from any text editor or word processor.
  42.  - A droplet. This combines the script and some glue code into a "Mini-application".
  43.    These will automatically run when double-clicked from the finder, and all files
  44.     you drop on them in the Finder will appear in the @ARV array.
  45.  - A runtime. While they in some respects behave like droplets, they are much more
  46.    heavyweight and will set you back several 100K every time you save one. The 
  47.     advantage of runtimes is that they run without the MacPerl application.
  48.  - Any other packaging you could think of. A MacHTTP package will appear in a few
  49.    days. The release verson of MacPerl 4.1.4 will describe how to add packaging
  50.     options to MacPerl.
  51.  
  52. 3. APPLEEVENTS/APPLESCRIPT
  53.  
  54. MacPerl has been scriptable and recordable since version 4.1.0. Most AppleEvents
  55. supported are the fairly conventional text events you'll find in the Scriptable
  56. Text Editor. In fact, MacPerl should support pretty much the same text manipulations
  57. as STE, except that STE generates somewhat prettier scripts when being recorded. If
  58. you find something working in STE and not in MacPerl, talk to me about it!
  59.  
  60. The only two events that are somewhat special to MacPerl are Save and Do Script.
  61.  
  62. Event:                    Save [core/save]
  63. Direct parameter:        A window object reference [obj ], a file [fss ], or text [TEXT]
  64. "in" [dest] (opt):    A file [fss ] to save in.
  65. "as" [fltp] (opt):    A save type [svas] (standard types are Text [TEXT], Droplet [SCPT]
  66.                      and System 7 runtime [MrP7] or an enumeration cast to [svas]).
  67.  
  68. This event does the same as the core save event, but it can also save files not open
  69. at the time and even on-the-fly text, and it can save in any package available. This
  70. is useful to e.g. save a file as a MacPerl droplet from another application.
  71.  
  72. Event:                    "Do Script" [misc/dosc]
  73. Direct parameter:        A file [fss ], text [TEXT] or a list of files and text.
  74. Reply:               Text results, depending on mode.
  75. "extract" [EXTR] (opt): A boolean [bool] which when false prevents searching for a #! line.
  76. "debug" [DEBG] (opt):A boolean which when true runs the Perl debugger
  77. "mode" [MODE] (opt): A mode [MODE], one of Local [LOCL], Batch [BATC], 
  78.                             Remote [RCTL], or Duplex [DPLX].
  79. "environment" [ENVT] (opt): A list of text [TEXT] variable/value pairs to add to the 
  80.                      environment.
  81. [SASE] (opt):        A record used as a callback event for remote mode.
  82.  
  83. As opposed to the standard "Do Script" event, MacPerl's "Do Script" accepts a list as
  84. the direct parameter and stuffs all further elements into @ARGV. The mode parameter
  85. has a major influence on the way the script is executed:
  86.  
  87.  - Local mode is the default. The script just runs and only returns text if you call
  88.    &MacPerl'Reply().
  89.  - Batch mode redirects standard output and error to the reply apple event. Standard
  90.    output is put into the direct parameter of the reply, while standard error is
  91.     put into element [diag] of parameter [OUTP].
  92.  - Remote control mode returns immediately from the DoScript request. Clients are
  93.    then expected to communicate with MacPerl with "Send Data" [McPL/DATA] events.
  94.     These contain standard input in the direct parameter and output as explained 
  95.     above. Furthermore, the 'WANT' parameter of the reply contains enumeration codes
  96.     for all input descriptors awaiting input. Sending a null descriptor with any
  97.     code signals an end of file for that file. MacPerl sets a boolean DONE parameter
  98.     in its reply to signal the last data being sent. If you did specify a SASE parameter
  99.     in your Do Script or Send Data events, it will be sent back to you the next 
  100.     time MacPerl waits for input.
  101.  - Duplex is an often faster variant of Remote Control mode. The difference is that
  102.    in Duplex mode, MacPerl will initiate I/O itself by putting actual data in the
  103.     SASE events it sends out. Please see below for examples of interaction in Remote
  104.     Control and Duplex mode.
  105.  - Both Batch and Remote control/Duplex mode support opening further input and output
  106.    streams as "Dev:AEVT:[4 byte code]". Standard input/output is "Dev:AEVT", standard
  107.     error is "Dev:AEVT:diag". Note that these names are case sensitive!
  108.  
  109. Furthermore, you can specify environment settings which will show up in %ENV in the
  110. environment parameter. If you specify a value for "PERLLIB", the library folders
  111. specified in the "Preferences…" dialog are appended to the value you specify.
  112.  
  113. 4. REMOTE CONTROL vs. DUPLEX MODE
  114.  
  115. To illustrate the workings of Remote Control and Duplex mode and their differences, 
  116. here are to AppleEvent logs from PCGI glue doing a Server push.
  117.  
  118. First, the older glue using RCTL mode:
  119.  
  120. -----------------------------------------------------------------------------------
  121. #
  122. # The PCGI glue receives a request from WebStar:
  123. #
  124. 'WWWΩ'\sdoc{'----':'TEXT'(), kfor:“animate”, user:'TEXT'(), pass:'TEXT'(), 
  125.                 frmu:'TEXT'(), addr:“192.33.93.95”, svnm:“neeracher.slip.ethz.ch”, 
  126.                 svpt:“80”, scnm:“/Nu.acgi”, ctyp:'TEXT'(), 
  127.                 refr:“http://neeracher.slip.ethz.ch/Nu.acgi”, 
  128.                 Agnt:“Mozilla/2.0b6a (Macintosh; I; PPC)”, Kact:“ACGI”, 
  129.                 Kapt:“/Nu.acgi”, post:'TEXT'(), meth:“GET”, Kcip:“192.33.93.95”, 
  130.                 Kfrq:“GET /Nu.acgi?animate HTTP/1.0
  131. Referer: http://neeracher.slip.ethz.ch/Nu.acgi
  132. Connection: Keep-Alive
  133. User-Agent: Mozilla/2.0b6a (Macintosh; I; PPC)
  134. Host: neeracher.slip.ethz.ch
  135. Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
  136.  
  137. ”, Kcid:13, &inte:cans, &timo:2147483647}
  138. #
  139. # The glue starts the Perl script in RCTL mode. Note how the header fields are passed
  140. # as environment variables:
  141. #
  142. misc\dosc{'----':[alis(«0000000000D8000200000…»)], 
  143.              MODE:RCTL, SASE:{evcl:McPL, evid:SASE}, 
  144.              ENVT:[“SERVER_SOFTWARE”, “MacHTTP/2.0”, 
  145.                       “GATEWAY_INTERFACE”, “CGI/1.1”, 
  146.                      “SERVER_PROTOCOL”, “HTTP/1.0”, 
  147.                      “QUERY_STRING”, “animate”, 
  148.                      “REMOTE_ADDR”, “192.33.93.95”, 
  149.                      “REQUEST_METHOD”, “GET”, 
  150.                      “SERVER_NAME”, “neeracher.slip.ethz.ch”, 
  151.                      “SERVER_PORT”, “80”, 
  152.                      “SCRIPT_NAME”, “/Nu.acgi”, 
  153.                      “HTTP_REFERER”, “http://neeracher.slip.ethz.ch/Nu.acgi”, 
  154.                      “HTTP_USER_AGENT”, “Mozilla/2.0b6a (Macintosh; I; PPC)”, 
  155.                      “HTTP_CONNECTION”, “Keep-Alive”, 
  156.                      “HTTP_HOST”, “neeracher.slip.ethz.ch”, 
  157.                      “HTTP_ACCEPT”, “image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*”]}
  158. #
  159. # Perl immediately replies:
  160. #
  161. aevt\ansr{}
  162. #
  163. # Now Perl wants to push the header. It does this by sending the SASE event back to
  164. # the glue:
  165. #
  166. McPL\SASE{}
  167. #
  168. # The glue sends an almost empty data event to MacPerl to provoke an answer:
  169. #
  170. McPL\DATA{INPT:{'----':“--More--
  171. ”}}
  172. #
  173. # Perl replies with the data:
  174. #
  175. aevt\ansr{'----':“HTTP/1.0 200 OK
  176. Server: MacHTTP/2.0
  177. MIME-Version: 1.0
  178. Content-Type: multipart/x-mixed-replace;boundary=EOM
  179.  
  180. --EOM
  181. Content-type: text/plain
  182.  
  183. 1
  184. ”, WANT:['----'], DONE:bool(«00»)}
  185. #
  186. # The glue sends the data back to WebStar. First it replies to the original WebStar
  187. # request with an announcement that the answer is going to arrive in multiple parts:
  188. #
  189. aevt\ansr{'----':“<SEND_PARTIAL>”}
  190. # 
  191. # Now it sends the real data
  192. #
  193. 'WWWΩ'\SPar{'----':“HTTP/1.0 200 OK
  194. Server: MacHTTP/2.0
  195. MIME-Version: 1.0
  196. Content-Type: multipart/x-mixed-replace;boundary=EOM
  197.  
  198. --EOM
  199. Content-type: text/plain
  200.  
  201. 1
  202. ”, Kmor:bool(«01»), Kcid:13}
  203. #
  204. # Again, Perl wants to send more data:
  205. #
  206. McPL\SASE{}
  207. #
  208. # The glue asks Perl for more data:
  209. #
  210. McPL\DATA{INPT:{'----':“--More--
  211. ”}}
  212. #
  213. # Perl sends the data:
  214. #
  215. aevt\ansr{'----':“--EOM
  216. Content-type: text/plain
  217.  
  218. 2
  219. ”, WANT:['----'], DONE:bool(«00»)}
  220. #
  221. # And the glue sends the data to WebStar
  222. #
  223. 'WWWΩ'\SPar{'----':“--EOM
  224. Content-type: text/plain
  225.  
  226. 2
  227. ”, Kmor:bool(«01»), Kcid:13}
  228.  
  229. -----------------------------------------------------------------------------------
  230.  
  231. Now the newer glue in DPLX mode. Note how only one AppleEvent per push is exchanged
  232. between the glue and MacPerl, instead of two:
  233.  
  234. -----------------------------------------------------------------------------------
  235.  
  236. #
  237. # The PCGI glue receives a request from WebStar:
  238. #
  239. 'WWWΩ'\sdoc{'----':'TEXT'(), kfor:“animate”, user:'TEXT'(), pass:'TEXT'(), 
  240.                 frmu:'TEXT'(), addr:“192.33.93.95”, svnm:“neeracher.slip.ethz.ch”, 
  241.                 ... identical to RCTL case ... 
  242. Connection: Keep-Alive
  243. User-Agent: Mozilla/2.0b6a (Macintosh; I; PPC)
  244. Host: neeracher.slip.ethz.ch
  245. Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
  246.  
  247. ”, Kcid:15, &inte:cans, &timo:2147483647}
  248. #
  249. # The glue starts the Perl script in DPLX mode. 
  250. #
  251. misc\dosc{'----':[alis(«...»)], MODE:DPLX, SASE:{evcl:McPL, evid:SASE}, 
  252.             ENVT:[... identical to RCTL case ...]}
  253. #
  254. # Perl immediately replies:
  255. #
  256. aevt\ansr{}
  257. #
  258. # Now Perl wants to push the header. Again, it does this by sending the SASE event 
  259. # back to the glue, but this time, it already includes the data:
  260. #
  261. McPL\SASE{'----':“HTTP/1.0 200 OK
  262. Server: MacHTTP/2.0
  263. MIME-Version: 1.0
  264. Content-Type: multipart/x-mixed-replace;boundary=EOM
  265.  
  266. --EOM
  267. Content-type: text/plain
  268.  
  269. 1
  270. ”, WANT:['----'], DONE:bool(«00»), &inte:cans, &timo:3600}
  271. #
  272. # The glue sends the data back to WebStar. First it replies to the original WebStar
  273. # request with an announcement that the answer is going to arrive in multiple parts:
  274. #
  275. aevt\ansr{'----':“<SEND_PARTIAL>”}
  276. # 
  277. # Now it sends the real data
  278. #
  279. 'WWWΩ'\SPar{'----':“HTTP/1.0 200 OK
  280. Server: MacHTTP/2.0
  281. MIME-Version: 1.0
  282. Content-Type: multipart/x-mixed-replace;boundary=EOM
  283.  
  284. --EOM
  285. Content-type: text/plain
  286.  
  287. 1
  288. ”, Kmor:bool(«01»), Kcid:15}
  289. #
  290. # Now the glue confirms the pushed data to Perl
  291. #
  292. aevt\ansr{INPT:{'----':“--More--
  293. ”}}
  294. #
  295. # Again, Perl wants to send more data:
  296. #
  297. McPL\SASE{'----':“--EOM
  298. Content-type: text/plain
  299.  
  300. 2
  301. ”, WANT:['----'], DONE:bool(«00»), &inte:cans, &timo:3600}
  302. #
  303. # And the glue sends the data to WebStar
  304. #
  305. 'WWWΩ'\SPar{'----':“--EOM
  306. Content-type: text/plain
  307.  
  308. 2
  309. ”, Kmor:bool(«01»), Kcid:15}
  310. #
  311. # ... and confirms the pushed data to Perl
  312. #
  313. aevt\ansr{INPT:{'----':“--More--
  314. ”}}
  315.  
  316. -----------------------------------------------------------------------------------
  317.