home *** CD-ROM | disk | FTP | other *** search
/ Magazyn Exec 5 / CD_Magazyn_EXEC_nr_5.iso / Programy / Programowanie / FetchRefs2.1.lha / FetchRefs2.1 / Documentation / FetchRefs.ADoc < prev   
Encoding:
Text File  |  2001-01-28  |  12.7 KB  |  369 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_FILE
  9. FetchRefs/FR_REQ
  10. FetchRefs/FR_ADD                                       FetchRefs/FR_ADD
  11.  
  12.    NAME
  13.     FR_ADD -- load additional index files
  14.  
  15.    SYNOPSIS
  16.     FR_ADD FILES/M
  17.  
  18.     FR_ADD [wildcard [...]]
  19.  
  20.    FUNCTION
  21.     FR_ADD will load extra    index files and add  them to the  internal
  22.     list. The index files already in memory are not removed.
  23.  
  24.    INPUTS
  25.     FILES/M - wildcard specification(s) for the index files to load.
  26.  
  27.    RESULTS
  28.     None.
  29.  
  30.    BUGS
  31.     None known.
  32.  
  33.    SEE ALSO
  34.     FR_CLEAR, FR_NEW
  35.  
  36. FetchRefs/FR_CLEAR                                     FetchRefs/FR_CLEAR
  37.  
  38.    NAME
  39.     FR_CLEAR -- remove any index files from memory
  40.  
  41.    SYNOPSIS
  42.     FR_CLEAR
  43.  
  44.    FUNCTION
  45.     Frees all memory allocated  to store loaded  index files. Most    of
  46.     the memory FetchRefs uses is the index so this will put  FetchRefs
  47.     into a low-memory sleep  mode. By later  calling FR_ADD or  FR_NEW
  48.     the original state can be restored.
  49.  
  50.    INPUTS
  51.     None.
  52.  
  53.    RESULTS
  54.     None.
  55.  
  56.    BUGS
  57.     None known.
  58.  
  59.    SEE ALSO
  60.     FR_ADD, FR_NEW
  61.  
  62. FetchRefs/FR_GET                                       FetchRefs/FR_GET
  63.  
  64.    NAME
  65.     FR_GET -- get a reference into a file or the clipboard
  66.  
  67.    SYNOPSIS
  68.     FR_GET FIND/A,TO/A,PUBSCREEN,FILEREF/S,CASE/S
  69.  
  70.     FR_GET <keyword> <filename> [public screen name] [FILEREF] [CASE]
  71.  
  72.    FUNCTION
  73.     Searches the index list for a  name matching the FIND keyword  and
  74.     writes it to the file specified by TO.
  75.  
  76.     The FIND argument  is a wildcard.  Thus you can  search on  things
  77.     like 'Open#?'  and get  a  long list  of functions  starting  with
  78.     'Open'. Many more wildcards exist; all the standard AmigaDOS  ones
  79.     are accepted.  However,  though  FR_GET  supports  wildcards,  the
  80.     provided ARexx scripts do not!
  81.  
  82.     If you need wildcarding capabilities you  can put the cursor on  a
  83.     space (see below)  before executing  the ARexx  script. This  will
  84.     open `the <Select reference> window'  where all  wildcards can  be
  85.     used in the pattern string gadget.
  86.  
  87.     When no matches are found, an error is returned. If excatly one is
  88.     found, the reference is written  to the filename specified by  the
  89.     TO argument.
  90.  
  91.     If the    supplied  keyword/wildcard  turns  out    to  match  several
  92.     references, a window is opened. Read more about this window in the
  93.     section named `the <Select reference> window', please. The  window
  94.     will also open if the empty  string '' matches the wildcard.  This
  95.     means that you can  position the cursor on  a space character  and
  96.     invoke FetchRefs. Then the  window will open and  you can enter  a
  97.     search pattern. Useful if you are going to look something up  that
  98.     is not in your current source view.
  99.  
  100.     The screen on which the above mentioned window is to be opened    is
  101.     specifed by using the PUBSCREEN argument. You specify the name    of
  102.     a public screen  which may  not be  in private    mode (they  rarely
  103.     are). If the  specified screen is  not available (non-existent  or
  104.     non-public) or    if  you  do  not specify  PUBSCREEN  at  all  then
  105.     FetchRefs will open  the window  on the  currently active  screen.
  106.     Should this  not be  public, the  default public  screen  (usually
  107.     Workbench) is used.
  108.     No matter where the  window opens that screen  will be brought    to
  109.     front (if it  is not already  there). When you  have finished  the
  110.     selection and the window  closes, the screen  is again put  behind
  111.     the other screens  (but only  if it was  brought to  front in  the
  112.     first place).
  113.  
  114.     If the FILEREF argument is given,  each of the files in the  index
  115.     file will be considered  a reference themselves.  The name of  the
  116.     reference is the  filename without any    leading path or  suffixes.
  117.     For example,  the  file 'DINCLUDE:Amiga30/exec/types.h'  would  be
  118.     considered a match if  you search for  the reference 'types'.  The
  119.     reason for  this truncation  is mainly    due to    the way  FetchRefs
  120.     works otherwise; types.h must be  truncated at the dot if  'types'
  121.     was a C structure and not  a file name - and FetchRefs really  has
  122.     no way of knowing what it actually is, until the match is  already
  123.     found; so, the most sensible idea seemed to trucate everything    at
  124.     the first non alpha-numeric character.
  125.  
  126.     Depending on whether you set the CASE flag or not, the    comparison
  127.     of the reference names is  either case sensitive (CASE  specified)
  128.     or not. If you are very good at memorizing capitalization you  may
  129.     want to turn it on -  personally I prefer to keep the search  case
  130.     insensitive.
  131.  
  132.     To write  the reference  to the  clipboard instead  of a  file,  a
  133.     filename of 'CLIPnn'  can be specified.  nn is the  number of  the
  134.     clipboard unit    you  wish to  use.  The  'CLIP' word  must  be  in
  135.     uppercase, otherwise the name is considered an usual file name.
  136.  
  137.    INPUTS
  138.     FIND/A      - name of reference to search for. Wildcards accepted.
  139.     TO/A      - file name to put the result into. 'CLIPnn' specifies
  140.             the clipboard unit nn.
  141.     PUBSCREEN - public screen to open the "select reference" window
  142.             on. Default is the currently active screen (if public,
  143.             otherwise the default public screen).
  144.     FILEREF   - let a reference search on the base name of a file
  145.             match with the entire file.
  146.     CASE      - activate case sensitive search.
  147.  
  148.    RESULTS
  149.     Two results are returned.
  150.  
  151.     rc will be
  152.         0 if the reference was successfully written
  153.         5 if `the <Select reference> window' was cancelled/closed
  154.        10 if no match was found for the specified search pattern
  155.        20 if an error (no memory, etc.) happend during the fetch
  156.  
  157.     rc2 contains  additional information;  if  rc is  0 then  it  will
  158.     contain a number specifying what  line the editor should move  the
  159.     cursor to after having loaded  the generated file. This line  will
  160.     contain the core of  the requested reference. If  rc is 5, 10,    or
  161.     20, rc2 will be a string  describing what went wrong. This can    be
  162.     passed on to the user through the editor (requester, title line).
  163.  
  164.    BUGS
  165.     None known.
  166.  
  167.    SEE ALSO
  168.  
  169. FetchRefs/FR_NEW                                       FetchRefs/FR_NEW
  170.  
  171.    NAME
  172.     FR_NEW -- clear internal index list and load a new
  173.  
  174.    SYNOPSIS
  175.     FR_NEW FILES/M
  176.  
  177.     FR_NEW [wildcard ...]
  178.  
  179.    FUNCTION
  180.     This is a combination  of FR_CLEAR and FR_ADD  and results in  the
  181.     internal list being  set to  nothing but what's  specified by  the
  182.     FILES arguments.
  183.  
  184.    INPUTS
  185.     FILES/M - wildcard specification(s) describing what files to load
  186.           instead of the current list.
  187.  
  188.    RESULTS
  189.     None.
  190.  
  191.    BUGS
  192.     None known.
  193.  
  194.    SEE ALSO
  195.     FR_ADD, FR_CLEAR
  196.  
  197. FetchRefs/FR_QUIT                                      FetchRefs/FR_QUIT
  198.  
  199.    NAME
  200.     FR_QUIT -- force FetchRefs to quit
  201.  
  202.    SYNOPSIS
  203.     FR_QUIT
  204.  
  205.    FUNCTION
  206.     Will send a ^C signal to the FetchRefs process that owns the ARexx
  207.     port. This  will force    FetchRefs to  free all    allocated  memory,
  208.     close down the ARexx port, and exit.
  209.  
  210.     A similar  effect can  be achived  by using  the C:Break  program,
  211.     running FetchRefs again, or by sending a ^C by any other means.
  212.  
  213.    INPUTS
  214.     None.
  215.  
  216.    RESULTS
  217.     None.
  218.  
  219.    BUGS
  220.     None known.
  221.  
  222.    SEE ALSO
  223.  
  224. FetchRefs/FR_FILE                                      FetchRefs/FR_FILE
  225.  
  226.    NAME
  227.     FR_FILE -- get the file(s) name(s) where the specified reference
  228.     can be found.
  229.  
  230.    SYNOPSIS
  231.     FR_FILE FIND/A,CASE/S
  232.  
  233.    FUNCTION
  234.     This function is like @{"FR_GET" LINK 3.3.}, but it return the names of the files.
  235.     where the reference(s) was found.
  236.  
  237.    INPUTS
  238.     FIND/A      - name of reference to search for. Wildcards accepted.
  239.     CASE      - activate case sensitive search.
  240.  
  241.    RESULTS
  242.     Two results are returned.
  243.  
  244.     rc will be
  245.         0 if the reference was successfully found
  246.            10 if no match was found for the specified search pattern
  247.            20 if an error (no memory, etc.) happend during the fetch
  248.  
  249.     rc2 contains  additional information;  if  rc is  0 then  it  will
  250.     contain the name of the file where the reference is present. If
  251.     several files were found, their names are separated by line feeds.
  252.     If  rc is not 0, rc2 will be a string  describing what went wrong.
  253.     This can  be passed on to the user through the editor (requester,
  254.     title line).
  255.  
  256.    BUGS
  257.     None known.
  258.  
  259.    SEE ALSO
  260.  
  261. FetchRefs/FR_REQ                                       FetchRefs/FR_REQ
  262.  
  263.    NAME
  264.     FR_REQ -- get a reference into a file or the clipboard and open
  265.     the FetchRefs requester
  266.  
  267.    SYNOPSIS
  268.     FR_REQ FIND/A,TO/A,PUBSCREEN,FILEREF/S,CASE/S
  269.  
  270.     FR_REQ <keyword> <filename> [public screen name] [FILEREF] [CASE]
  271.  
  272.    FUNCTION
  273.     Searches the index list for a  name matching the FIND keyword  and
  274.     writes it to the file specified by TO.
  275.  
  276.     The FIND argument  is a wildcard.  Thus you can  search on  things
  277.     like 'Open#?'  and get  a  long list  of functions  starting  with
  278.     'Open'. Many more wildcards exist; all the standard AmigaDOS  ones
  279.     are accepted.  However,  though  FR_GET  supports  wildcards,  the
  280.     provided ARexx scripts do not!
  281.  
  282.     If you need wildcarding capabilities you  can put the cursor on  a
  283.     space (see below)  before executing  the ARexx  script. This  will
  284.     open `the <Select reference> window'  where all  wildcards can  be
  285.     used in the pattern string gadget.
  286.  
  287.     When no matches are found, an error is returned. If excatly one is
  288.     found, the reference is written  to the filename specified by  the
  289.     TO argument.
  290.  
  291.     In every case  (one or more references found,  or no  reference at
  292.     all,  a window is opened.  Read  more  about this  window  in  the
  293.     section named `the <Select reference> window', please. The  window
  294.     will also open if the empty  string '' matches the wildcard.  This
  295.     means that you can  position the cursor on  a space character  and
  296.     invoke FetchRefs. Then the  window will open and  you can enter  a
  297.     search pattern. Useful if you are going to look something up  that
  298.     is not in your current source view.
  299.  
  300.     The screen on which the above mentioned window is to be opened    is
  301.     specifed by using the PUBSCREEN argument. You specify the name    of
  302.     a public screen  which may  not be  in private    mode (they  rarely
  303.     are). If the  specified screen is  not available (non-existent  or
  304.     non-public) or    if  you  do  not specify  PUBSCREEN  at  all  then
  305.     FetchRefs will open  the window  on the  currently active  screen.
  306.     Should this  not be  public, the  default public  screen  (usually
  307.     Workbench) is used.
  308.     No matter where the  window opens that screen  will be brought    to
  309.     front (if it  is not already  there). When you  have finished  the
  310.     selection and the window  closes, the screen  is again put  behind
  311.     the other screens  (but only  if it was  brought to  front in  the
  312.     first place).
  313.  
  314.     If the FILEREF argument is given,  each of the files in the  index
  315.     file will be considered  a reference themselves.  The name of  the
  316.     reference is the  filename without any    leading path or  suffixes.
  317.     For example,  the  file 'DINCLUDE:Amiga30/exec/types.h'  would  be
  318.     considered a match if  you search for  the reference 'types'.  The
  319.     reason for  this truncation  is mainly    due to    the way  FetchRefs
  320.     works otherwise; types.h must be  truncated at the dot if  'types'
  321.     was a C structure and not  a file name - and FetchRefs really  has
  322.     no way of knowing what it actually is, until the match is  already
  323.     found; so, the most sensible idea seemed to trucate everything    at
  324.     the first non alpha-numeric character.
  325.  
  326.     Depending on whether you set the CASE flag or not, the    comparison
  327.     of the reference names is  either case sensitive (CASE  specified)
  328.     or not. If you are very good at memorizing capitalization you  may
  329.     want to turn it on -  personally I prefer to keep the search  case
  330.     insensitive.
  331.  
  332.     To write  the reference  to the  clipboard instead  of a  file,  a
  333.     filename of 'CLIPnn'  can be specified.  nn is the  number of  the
  334.     clipboard unit    you  wish to  use.  The  'CLIP' word  must  be  in
  335.     uppercase, otherwise the name is considered an usual file name.
  336.  
  337.    INPUTS
  338.     FIND/A      - name of reference to search for. Wildcards accepted.
  339.     TO/A      - file name to put the result into. 'CLIPnn' specifies
  340.             the clipboard unit nn.
  341.     PUBSCREEN - public screen to open the "select reference" window
  342.             on. Default is the currently active screen (if public,
  343.             otherwise the default public screen).
  344.     FILEREF   - let a reference search on the base name of a file
  345.             match with the entire file.
  346.     CASE      - activate case sensitive search.
  347.  
  348.    RESULTS
  349.     Two results are returned.
  350.  
  351.     rc will be
  352.         0 if the reference was successfully written
  353.         5 if `the <Select reference> window' was cancelled/closed
  354.        10 if no match was found for the specified search pattern
  355.        20 if an error (no memory, etc.) happend during the fetch
  356.  
  357.     rc2 contains  additional information;  if  rc is  0 then  it  will
  358.     contain a number specifying what  line the editor should move  the
  359.     cursor to after having loaded  the generated file. This line  will
  360.     contain the core of  the requested reference. If  rc is 5, 10,    or
  361.     20, rc2 will be a string  describing what went wrong. This can    be
  362.     passed on to the user through the editor (requester, title line).
  363.  
  364.    BUGS
  365.     None known.
  366.  
  367.    SEE ALSO
  368.  
  369.