home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Utilities / Programming / EnterAct 3.5 / EnterAct's magic clipboard < prev    next >
Encoding:
Text File  |  1995-08-30  |  6.4 KB  |  159 lines  |  [TEXT/KEEN]
  1. EnterAct's magic clipboard
  2. ------------------------
  3.  
  4. Prerequisites: you should see the "hAWK User’s Manual" and read
  5. enough to know how to run hAWK programs before diving in here.
  6. However, no harm in browsing....
  7.  
  8. Added for version 3 of EnterAct, you can now write hAWK
  9. programs that watch EnterAct's clipboard, and, when your
  10. specified conditions are met, write anything you like back to the
  11. clipboard. This gives you in effect a "magic clipboard", ideal for
  12. reducing repetitive, moderately complicated tasks to a simple
  13. Copy and Paste.
  14.  
  15. When you're done with your hAWK "magic clipboard" program,
  16. you can stop it with <Command><period>.
  17.  
  18. Example programs, in the "hAWK programs" folder:
  19. "$ClipGlossary" lets you remember and expand glossary abbreviations.
  20. "$ClipOldCDeclToNew" converts old C declarations to new ANSI style.
  21. "$ClipMagicTemplate" is a stripped-down simple example to build on,
  22. talked about below.
  23. "$ClipFormatFuncIntro" will reformat a messy function start into
  24. something elegant (instructions are at the beginning of its file).
  25.  
  26. §    How it works
  27. By default, any hAWK program you start up while using EnterAct
  28. will run concurrently with EnterAct. Big hAWK programs can take
  29. a while, so this allows you to continue working with EnterAct
  30. while hAWK chugs away, for the most part unobtrusively, in
  31. the background. Most of the time, you'll run hAWK programs that
  32. do one specific job and then quit -- but what if it just kept
  33. running and running and running?
  34.  
  35. hAWK has two special built-in functions, getclip() and putclip(),
  36. that allow it to monitor and change EnterAct's private clipboard.
  37. Armed with these, you can write a hAWK program that runs
  38. "forever", and does specific things to the clipboard under
  39. specific circumstances. What all those specifics are is up to you.
  40.  
  41. §    An example
  42. Since an ounce of code is often worth a pound of explanation,
  43. here's an example of a loop you can use to monitor the clipboard
  44. and trigger action under specific circumstances:
  45.  
  46.     #$ClipMagicTemplate: you can use this as the basis for your
  47.     # own clipboard changers. This example just truncates the
  48.     # clip to its last line, provided it starts with a space.
  49.     BEGIN {
  50.         clipCharsToWatch = 32;
  51.         while (1) # run until <Command><period>...
  52.             {
  53.             # see if clipboard has changed
  54.             if ((newClip = getclip(clipCharsToWatch)) != oldClip)
  55.                 {
  56.                 oldClip = newClip;
  57.                 # a leading space is used as the trigger
  58.                 if (substr(newClip, 1,1) == " ")
  59.                     DoSomething()
  60.                 }
  61.             }
  62.         }
  63.  
  64.     function DoSomething(            fullClip, numLines, lines, outClip, out)
  65.         {
  66.         fullClip = getclip(); # gets calling editor's private clip
  67.         numLines = split(fullClip, lines, "\r");
  68.         # with "split", the last line will be empty if the last
  69.         # character copied was a return.
  70.         if (lines[numLines] == "")
  71.             --numLines;
  72.         
  73.         #...do things with the clipboard, and create the new clip "out"
  74.         ### just for example, keep only the last line of the old clip
  75.         out = out lines[numLines] "\r";
  76.         
  77.         # In this specific case, since we are looking for a space at
  78.         # the beginning of the clip, make sure our new clip does NOT
  79.         # start with a space
  80.         sub(/^[ ]+/, "", out); # that's a [space] there
  81.         
  82.         # send the result back to the calling editor's clip
  83.         putclip(out);
  84.         # update "oldClip"
  85.         oldClip = substr(out, 1, 32);
  86.         # flash menu bar to signal something happened
  87.         beep(0);
  88.         }
  89. (you'll also find the above program in your "hAWK programs" folder)
  90.  
  91. The monitoring all takes place in your BEGIN section (or, if you
  92. prefer, in your END section after reading some input). Running
  93. forever, we look at just the first 32 characters of the clipboard
  94. to see if the clip has changed. If the clip has changed, and the first
  95. character on it is a space, we call the function DoSomething(), which
  96. retrieves the entire clipboard to "fullClip", breaks it into separate
  97. lines in the array "lines", creates a new clipboard string in "out",
  98. writes it back to EnterAct with "putclip()", and then flashes the
  99. menu bar to show something happened as a result of the Copy in
  100. EnterAct.
  101.  
  102. The line
  103.     if ((newClip = getclip(clipCharsToWatch)) != oldClip)
  104. determines if the first 32 characters of the clipboard have changed
  105. since the last time the clipboard was looked at. If so, the specific
  106. trigger for doing something is
  107.     if (substr(newClip, 1,1) == " ")
  108.         DoSomething()
  109. which simply checks to see if the latest clipboard starts with a space.
  110.  
  111. "DoSomething()" retrieves the full clipboard (up to a limit of 32K
  112. actually) and then breaks it into lines, after which the clip is at
  113. its mercy. A new clip string is created in "out", and written back to
  114. EnterAct with
  115.     putclip(out);
  116. The "beep(0)" will signal you that this hAWK program has been
  117. triggered to rewrite the clipboard.
  118.  
  119. With the above program running, if you copied several lines of text
  120. by picking Copy in Enteract, and the first line began with a space,
  121. then you would see the menu bar flash. If you then did a Paste, the
  122. pasted text would turn out to be only the last line you just copied
  123. (minus any leading spaces). If you copied text that did not begin
  124. with a space then the menu bar would not flash and your clip would
  125. be unchanged.
  126.  
  127. §    Other examples
  128. The program "$ClipOldCDeclToNew" is a very real example that converts
  129. a specific style of "old-fashioned" C function declaration to the new
  130. ANSI prototype style. It looks for a very specific pattern in the
  131. declaration, but you could adapt it to be more general. It saved me
  132. hours of tedious work.
  133.  
  134. "$ClipGlossary" lets you remember and expand glossary abbreviations.
  135. Both making an entry in your glossary and expanding a glossary
  136. entry work by Copy and Paste: to make an entry, you would Copy
  137. text in the format gloss abbreviation full text, as in
  138.     gloss forloop for (i = 0; i <= ??; ++i)
  139.         {
  140.         
  141.         }
  142. --the "gloss" part serves a signal that you are making an entry,
  143. and the menu bar will flash to show that the entry has been made.
  144. To expand this entry, you would type "forloop" and then Copy it
  145. and Paste right over it (after the menu bar flashes) to produce
  146.     for (i = 0; i <= ??; ++i)
  147.         {
  148.         
  149.         }
  150.  
  151. §    (?)
  152. If the above didn't make much sense yet, but you really would like a
  153. magic clipboard, just start in on the "hAWK User's Manual" and you'll
  154. be writing your own hAWK programs in short order. hAWK is a
  155. Mac version of AWK, an interpreted language that's like C but with
  156. many built-in functions for text and data manipulation. As you've
  157. seen, running a hAWK program is pretty easy: writing them isn't that
  158. hard either, especially if you know C (a good bet).
  159.