home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / Perl / Non-RPC / !Perl / !Help < prev    next >
Text File  |  1999-04-17  |  10KB  |  267 lines
  1. ****************************************************************************
  2. *                                       *
  3. *                        Perl                   *
  4. *          Practical Extraction and Report Language           *
  5. *                    Version 5.005                   *
  6. *                 RISC OS  port 1.13                   *
  7. *                 Dynamically Linked                   *
  8. *                                       *
  9. ****************************************************************************
  10.  
  11.  
  12.                     STOP
  13.  
  14.  
  15. As warned the incorrect 'RiscOS' has gone. Packages are now RISCOS::
  16. and $^O reports 'riscos'. To find everything that needs changing try:
  17.  
  18. scripts.grep -t RiscOS myscriptdir..*
  19.  
  20. Beware: as RISC OS filesystems are case insensitive, use RiscOS; will find
  21. RISCOS, but not import subroutines. This will lead to a lot of wacky syntax
  22. errors. The brute-force solution is to
  23.  
  24. perl -i~ -p 's/RiscOS/RISCOS/' myscriptdir..*
  25.  
  26. (By the way, .. recursive globbing can be quite useful.)
  27.  
  28. The directory structure has changed since 1.11 :-)
  29. Most of the perl library is now in a single zip file, and I've hacked perl to
  30. read libraries direct from a zip file. You *can* read the zip file with Infozip
  31. or SparkFS, but *please* leave it settype'd data, else perl will use SparkFS to
  32. read from it (which is probably slower). Again it is best to back up any changes
  33. you made to your !Perl, and start afresh with this copy if you're using 1.11 or
  34. earlier. I'm experimenting with sfio to get the remaining few library files
  35. inside the zip (those which use __DATA__).
  36.  
  37. UnixLib still can't cope with command lines like
  38.  
  39. perl -le 'print @ARGV' <Wimp$Scrap>
  40.  
  41. as it thinks you mean
  42.  
  43. perl -le 'print @ARGV' <"Wimp$Scrap" >
  44.  
  45. and tries to open the (illegaly named) Wimp$Scrap for input redirection. This
  46. causes problems with programs such as !Netplex. Try changing the lines
  47. with set Alias$@RunType_102 in !Boot and !Run, replacing "perl" with "do perl".
  48. "do" is supplied with RiscPCs, and expands the variables before perl runs.
  49. Strictly UnixLib is doing nothing wrong. Due to popular demand UnixLib will
  50. probably be improved to guess when OS variables are wanted.
  51.  
  52. (consider perl somescript <Foo>Bar   - redirect from Foo to Bar, or use the OS
  53. variable Foo to make a filename to put in @ARGV?  There are ambiguous cases)
  54.  
  55. Anyway, back to the regular diatribe:
  56.  
  57.                  NO WARRANTY
  58.  
  59.      BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
  60. FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
  61. OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
  62. PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
  63. OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  64. MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
  65. TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
  66. PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
  67. REPAIR OR CORRECTION.
  68.  
  69.      IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
  70. WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
  71. REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
  72. INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
  73. OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
  74. TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
  75. YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
  76. PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
  77. POSSIBILITY OF SUCH DAMAGES.
  78.  
  79.  
  80.  
  81. Perl is a language optimized for scanning arbitrary text files, extracting
  82. information from those text files, and printing reports based on that
  83. information. It's also a good language for many system management tasks.
  84. The language is intended to be practical (easy to use, efficient, complete)
  85. rather than beautiful (tiny, elegant, minimal).
  86.  
  87. This !Perl application contains a perl binary, dynamically linked
  88. extensions (including socket support), standard perl libraries (providing
  89. many useful functions), and some RISC OS libraries providing RISC OS
  90. specific functions and perl-like interfaces to RISC OS system calls. The
  91. convention used throughout the scripts, modules and regression tests is that
  92. if a file is unmodified from the Unix source distribution is set filetyped
  93. text, whereas if a file needed any modification it is filetyped perl (102).
  94.  
  95. When first seen by the filer !Perl will set an icon for perl files, initialise
  96. some variables needed by the perl binary, add the directory containing the
  97. perl binary to your Run$Path, and set a run-type for perl files so that
  98. double-clicking will run perl.
  99.  
  100. Running the !Perl application will also open the scripts directory and set
  101. the WimpSlot "next" to 1024K. BEWARE - this still may not be enough memory for
  102. some scripts.
  103.  
  104. You may wish to copy the perl binary to a library directory where you keep
  105. other command line programs (such as compilers). If so, you should ensure
  106. that the actions performed by the !Boot file inside !Perl occur when you
  107. start your machine, so that perl can find its libraries. This can be done by
  108. placing !Perl in the !Boot.Choices.Boot.Tasks directory on a Risc PC, or by
  109. placing !Perl in a directory that is "seen" when your machine starts (ie a
  110. directory where you keep your common applications).
  111.  
  112. Probably the three most powerful features of core perl are:
  113. *    its regular expressions for pattern matching.
  114. *    its ability to cope with arbitary length strings.
  115. *    its associative arrays (hashes) which allow data to be stored by
  116.     key/value pairs.
  117.  
  118. In addition, probably the four most useful features of the RISC OS port are
  119. *    filename globbing.
  120. *    *command/program output capture.
  121. *    full access to all SWIs - passing data to and from perl.
  122. *    the DrawFile manipulation library.
  123.  
  124.  
  125. The scripts directory contains many useful scripts which demonstrate how to
  126. use perl, and how some of the RISC OS specific functions work.
  127.  
  128. Some of the most useful are:
  129. grep        find strings (patterns in files) - coupled with optional
  130.         throwback and files specified by recursive globs allows
  131.         entire source trees to be searched. Very powerful.
  132. finger        finger in perl - how to write portable socket code.
  133.         (This script will run unmodified on Unix)
  134. SetType+    settype multiple files specified by wildcards.
  135. rename        Larry Wall's clasic rename script, which allows files to
  136.         be renamed using a perl expression to generate the new
  137.         name from the old.
  138. drawfile    10 line script to demonstrate manipulating DrawFiles
  139.         (Try changining all instances of 'Homerton.Medium' to
  140.          'Sassoon.Primary' in multiple drawfiles within nested
  141.          groups using some other system...)
  142.  
  143. If you have used a previous perl port....
  144.  
  145. Globbing improved
  146.     1: * and # can be used in all directory names, not just the final
  147.        leafname
  148.     2: .. matches any number of directories, so @..* matches all files
  149.        in the current directory and all subdirectories
  150.     3: path variables are searched (recursively) - path variables in the
  151.        returned list of filenames can either be left in place or
  152.        expanded fully. (see the library documentation for RISCOS::File)
  153.  
  154. Program output capture more reliable
  155.     Perl will capture program output without needing an internal lookup
  156.     table of what to treat as a *command
  157.  
  158. SWIs can now be called by name or number
  159.     Pass a number and it will be recognised as such - bypassing the long
  160.     overhead of the SWI name lookup
  161.  
  162. Almost all perl modules work
  163.     Bigint, Complex, File::Copy, ...
  164.     Many extensions work (eg Socket IO Fcntl)
  165.     All regression tests that the Config.pm say should pass do!
  166.  
  167.  
  168. *IF YOU HAVE USED A PREVIOUS PERL PORT* note that this perl defaults to
  169. "Unix style" filenames. (consistent with perl ports to other OSes)
  170. To *TURN OFF* automatic filename conversion
  171.  
  172.     use RISCOS::Filespec;
  173.  
  174. at the start of your script (or invoke perl as perl -MRISCOS::Filespec)
  175.  
  176.  
  177. -------------------------------Hints and Tips-------------------------------
  178.  
  179. The modules supplied with perl provide a large amount of common
  180. functionality, portable across many platforms. *Not* investigating and using
  181. the supplied modules is about as wise as not using the ANSI C library.
  182.  
  183. For example, to expand all the tabs in an array of lines of text:
  184.  
  185.     use Text::Tabs;
  186.     @lines_without_tabs = expand(@lines_with_tabs);
  187.  
  188.  
  189. If you want to copy anything:
  190.     use File::Copy;
  191.     copy <from> <to>
  192. or
  193.     use RISCOS::File 'copy';
  194.     copy <from> <to> [<flags>]
  195.  
  196. in preference to *copy or calling OS_FSControl 26.
  197.  
  198. Flags default to 0 [*], and are as for OS_FSControl 26 *except* that bit 13
  199. is toggled. This means that *by default* an appropriately sized user buffer
  200. is provided internally, avoiding problems copying to/from archives.
  201. [Appropriately sized is currently implemented as min( <filesize>, 128K ) ]
  202. * If flags are not supplied then force is turned on unless the target is
  203. locked. This means that you can copy over a destination file automatically.
  204.  
  205. If you want the Internet hostname:
  206.     use Sys::hostname;
  207.     $name = hostname();
  208.    
  209. as it automatically tries all known methods to get this information.
  210. [See Unixlib's unix.c.gethostname for the implementation]
  211.  
  212.  
  213. Beware of full pathnames:
  214.  
  215. "ADFS::Bagpuss.$.!Boot" ne 'ADFS::Bagpuss.$.!Boot'
  216.  
  217. because $. is a variable that gets interpolated.
  218.  
  219. However even if you are careful and go:
  220.  
  221. $somevar = 'ADFS::Bagpuss.$.!Boot'
  222.  
  223. DONT:
  224.     $othervar =~ /^$somevar/;
  225.  
  226. this **will** come unstuck because $somevar is **interpolated AGAIN** in the
  227. regular expression.
  228.  
  229. DO:
  230.     $othervar =~ /^\Q$somevar\E/;
  231.  
  232. to stop this second interpolation! (looks like it should quote the '$').
  233. This won't screw up with \ in filenames, as \ is the Previously Set
  234. Directory, and the only character that can legally follow it is .
  235.  
  236.  
  237. Beware of <System$Variables> in filenames:
  238.  
  239. DONT:
  240.     open( FILE, $file );
  241.  
  242. this will fail if $file starts "<somesystem$var>"
  243.  
  244. DO:
  245.     open( FILE, "<$file" );
  246.  
  247. They also confuse the parser in globs, and the $ will get interpolated
  248.  
  249. DONT:
  250.     <<Obey$Dir>.*>
  251.  
  252. DO:
  253.     < <Obey\$Dir>.*>
  254.  
  255.  
  256. ----------------------------------------------------------------------------
  257.  
  258. Perl may be copied subject to the conditions of the "Artistic License"
  259. which you will find in the file "Artistic".
  260.  
  261. The perl source code and utilities needed to remake perl from scratch are
  262. available from ftp://ftp.unfortu.net/pub/flirble/users/nick/P/
  263.  
  264. Nicholas Clark <nick@unfortu.net>
  265.  
  266. PS Now look at !Perl.scripts.drawfile
  267.