home *** CD-ROM | disk | FTP | other *** search
/ Aminet 33 / Aminet 33 - October 1999.iso / Aminet / dev / misc / FetchRefs1.3.lha / FetchRefs1.3 / Documentation / FetchRefs.ADoc < prev   
Encoding:
Text File  |  1996-02-25  |  6.9 KB  |  222 lines
  1. TABLE OF CONTENTS
  2.  
  3. FetchRefs/FR_ADD
  4. FetchRefs/FR_CLEAR
  5. FetchRefs/FR_GET
  6. FetchRefs/FR_NEW
  7. FetchRefs/FR_QUIT
  8. FetchRefs/FR_ADD                                       FetchRefs/FR_ADD
  9.  
  10.    NAME
  11.     FR_ADD -- load additional index files
  12.     
  13.    SYNOPSIS
  14.     FR_ADD FILES/M
  15.     
  16.     FR_ADD [wildcard [...]]
  17.     
  18.    FUNCTION
  19.     FR_ADD will load extra  index files and add  them to the  internal
  20.     list. The index files already in memory are not removed.
  21.     
  22.    INPUTS
  23.     FILES/M - wildcard specification(s) for the index files to load.
  24.     
  25.    RESULTS
  26.     None.
  27.     
  28.    BUGS
  29.     None known.
  30.     
  31.    SEE ALSO
  32.     FR_CLEAR, FR_NEW
  33.  
  34. FetchRefs/FR_CLEAR                                     FetchRefs/FR_CLEAR
  35.  
  36.    NAME
  37.     FR_CLEAR -- remove any index files from memory
  38.     
  39.    SYNOPSIS
  40.     FR_CLEAR
  41.     
  42.    FUNCTION
  43.     Frees all memory allocated  to store loaded  index files. Most  of
  44.     the memory FetchRefs uses is the index so this will put  FetchRefs
  45.     into a low-memory sleep  mode. By later  calling FR_ADD or  FR_NEW
  46.     the original state can be restored.
  47.     
  48.    INPUTS
  49.     None.
  50.     
  51.    RESULTS
  52.     None.
  53.     
  54.    BUGS
  55.     None known.
  56.     
  57.    SEE ALSO
  58.     FR_ADD, FR_NEW
  59.     
  60. FetchRefs/FR_GET                                       FetchRefs/FR_GET
  61.  
  62.    NAME
  63.     FR_GET -- get a reference into a file or the clipboard
  64.     
  65.    SYNOPSIS
  66.     FR_GET FIND/A,TO/A,PUBSCREEN,FILEREF/S,CASE/S
  67.     
  68.     FR_GET <keyword> <filename> [public screen name] [FILEREF] [CASE]
  69.     
  70.    FUNCTION
  71.     Searches the index list for a  name matching the FIND keyword  and
  72.     writes it to the file specified by TO.
  73.     
  74.     The FIND argument  is a wildcard.  Thus you can  search on  things
  75.     like 'Open#?'  and get  a  long list  of functions  starting  with
  76.     'Open'. Many more wildcards exist; all the standard AmigaDOS  ones
  77.     are accepted.  However,  though  FR_GET  supports  wildcards,  the
  78.     provided ARexx scripts do not!
  79.     
  80.     If you need wildcarding capabilities you  can put the cursor on  a
  81.     space (see below)  before executing  the ARexx  script. This  will
  82.     open `the <Select reference> window'  where all  wildcards can  be
  83.     used in the pattern string gadget.
  84.     
  85.     When no matches are found, an error is returned. If excatly one is
  86.     found, the reference is written  to the filename specified by  the
  87.     TO argument.
  88.     
  89.     If the  supplied  keyword/wildcard  turns  out  to  match  several
  90.     references, a window is opened. Read more about this window in the
  91.     section named `the <Select reference> window', please. The  window
  92.     will also open if the empty  string '' matches the wildcard.  This
  93.     means that you can  position the cursor on  a space character  and
  94.     invoke FetchRefs. Then the  window will open and  you can enter  a
  95.     search pattern. Useful if you are going to look something up  that
  96.     is not in your current source view.
  97.     
  98.     The screen on which the above mentioned window is to be opened  is
  99.     specifed by using the PUBSCREEN argument. You specify the name  of
  100.     a public screen  which may  not be  in private  mode (they  rarely
  101.     are). If the  specified screen is  not available (non-existent  or
  102.     non-public) or  if  you  do  not specify  PUBSCREEN  at  all  then
  103.     FetchRefs will open  the window  on the  currently active  screen.
  104.     Should this  not be  public, the  default public  screen  (usually
  105.     Workbench) is used.
  106.     No matter where the  window opens that screen  will be brought  to
  107.     front (if it  is not already  there). When you  have finished  the
  108.     selection and the window  closes, the screen  is again put  behind
  109.     the other screens  (but only  if it was  brought to  front in  the
  110.     first place).
  111.     
  112.     If the FILEREF argument is given,  each of the files in the  index
  113.     file will be considered  a reference themselves.  The name of  the
  114.     reference is the  filename without any  leading path or  suffixes.
  115.     For example,  the  file 'DINCLUDE:Amiga30/exec/types.h'  would  be
  116.     considered a match if  you search for  the reference 'types'.  The
  117.     reason for  this truncation  is mainly  due to  the way  FetchRefs
  118.     works otherwise; types.h must be  truncated at the dot if  'types'
  119.     was a C structure and not  a file name - and FetchRefs really  has
  120.     no way of knowing what it actually is, until the match is  already
  121.     found; so, the most sensible idea seemed to trucate everything  at
  122.     the first non alpha-numeric character.
  123.     
  124.     Depending on whether you set the CASE flag or not, the  comparison
  125.     of the reference names is  either case sensitive (CASE  specified)
  126.     or not. If you are very good at memorizing capitalization you  may
  127.     want to turn it on -  personally I prefer to keep the search  case
  128.     insensitive.
  129.     
  130.     To write  the reference  to the  clipboard instead  of a  file,  a
  131.     filename of 'CLIPnn'  can be specified.  nn is the  number of  the
  132.     clipboard unit  you  wish to  use.  The  'CLIP' word  must  be  in
  133.     uppercase, otherwise the name is considered an usual file name.
  134.     
  135.    INPUTS
  136.     FIND/A    - name of reference to search for. Wildcards accepted.
  137.     TO/A      - file name to put the result into. 'CLIPnn' specifies
  138.             the clipboard unit nn.
  139.     PUBSCREEN - public screen to open the "select reference" window
  140.             on. Default is the currently active screen (if public,
  141.             otherwise the default public screen).
  142.     FILEREF   - let a reference search on the base name of a file
  143.             match with the entire file.
  144.     CASE      - activate case sensitive search.
  145.          
  146.    RESULTS
  147.     Two results are returned. 
  148.     
  149.     rc will be
  150.         0 if the reference was successfully written
  151.         5 if `the <Select reference> window' was cancelled/closed
  152.        10 if no match was found for the specified search pattern
  153.        20 if an error (no memory, etc.) happend during the fetch
  154.     
  155.     rc2 contains  additional information;  if  rc is  0 then  it  will
  156.     contain a number specifying what  line the editor should move  the
  157.     cursor to after having loaded  the generated file. This line  will
  158.     contain the core of  the requested reference. If  rc is 5, 10,  or
  159.     20, rc2 will be a string  describing what went wrong. This can  be
  160.     passed on to the user through the editor (requester, title line).
  161.     
  162.    BUGS
  163.     None known.
  164.     
  165.    SEE ALSO
  166.    
  167. FetchRefs/FR_NEW                                       FetchRefs/FR_NEW
  168.  
  169.    NAME
  170.     FR_NEW -- clear internal index list and load a new
  171.     
  172.    SYNOPSIS
  173.     FR_NEW FILES/M
  174.     
  175.     FR_NEW [wildcard ...]
  176.     
  177.    FUNCTION
  178.     This is a combination  of FR_CLEAR and FR_ADD  and results in  the
  179.     internal list being  set to  nothing but what's  specified by  the
  180.     FILES arguments.
  181.     
  182.    INPUTS
  183.     FILES/M - wildcard specification(s) describing what files to load
  184.           instead of the current list.
  185.     
  186.    RESULTS
  187.     None.
  188.     
  189.    BUGS
  190.     None known.
  191.     
  192.    SEE ALSO
  193.     FR_ADD, FR_CLEAR
  194.     
  195. FetchRefs/FR_QUIT                                      FetchRefs/FR_QUIT
  196.  
  197.    NAME
  198.     FR_QUIT -- force FetchRefs to quit
  199.     
  200.    SYNOPSIS
  201.     FR_QUIT
  202.     
  203.    FUNCTION
  204.     Will send a ^C signal to the FetchRefs process that owns the ARexx
  205.     port. This  will force  FetchRefs to  free all  allocated  memory,
  206.     close down the ARexx port, and exit.
  207.     
  208.     A similar  effect can  be achived  by using  the C:Break  program,
  209.     running FetchRefs again, or by sending a ^C by any other means.
  210.     
  211.    INPUTS
  212.     None.
  213.     
  214.    RESULTS
  215.     None.
  216.     
  217.    BUGS
  218.     None known.
  219.     
  220.    SEE ALSO
  221.  
  222.