home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 514a.lha / sregexp.library_v9.0 / sregexp.doc < prev    next >
Text File  |  1991-06-08  |  14KB  |  433 lines
  1. TABLE OF CONTENTS
  2.  
  3. sregexp.library/AnchorPath
  4. sregexp.library/BuildPath
  5. sregexp.library/FreeSpathInfo
  6. sregexp.library/FreeSregExp
  7. sregexp.library/IsWild
  8. sregexp.library/ParseSregExp
  9. sregexp.library/MatchNSregExp
  10. sregexp.library/MatchSregExp
  11. sregexp.library/NextFile
  12.  
  13. sregexp.library/AnchorPath              sregexp.library/AnchorPath
  14.  
  15.     NAME
  16.     AnchorPath -- get set up to match a wildcard path.
  17.  
  18.     SYNOPSIS
  19.     spath = AnchorPath(anc, wld)
  20.     D0           A0    A1
  21.     struct SpathInfo *AnchorPath(char *, char *);
  22.  
  23.     FUNCTION
  24.     This is the first step in matching a wildcarded path. This routine
  25.     will preparse all of the wildcard elements in the path and set
  26.     everything up for subsequent calls to NextFile.
  27.  
  28.     If NULL is returned, then IoErr can be examined to find out more on
  29.     whatever went wrong.
  30.  
  31.     The wildcarded path is made up of (almost, see bug note) any legal
  32.     AmigaDOS path name, with wildcard expressions in the place of file
  33.     and directory names.  There is one additional syntax: '.../' means
  34.     recursively search all sub-directories. so:
  35.         DH0:.../fred
  36.     would search all of DH0 for a (file or directory or either, see
  37.     NextFile) named fred.
  38.  
  39.     One pretty nifty feature is that wildcards are legal in the volume
  40.     node part of the path.    This will match to any file system device or
  41.     assigned directory or volume node that the system currently has
  42.     mounted. So to match all of the hard drive partitions in your system
  43.     you would use 'DH?:.../fred'.  The root of your current device will
  44.     be matched only if the pattern explicitly matches a null string (ie
  45.     either just ':' or '%:')
  46.  
  47.     INPUTS
  48.     anc      - a null terminated string which is the name of a
  49.             directory.    All paths returned by BuildPath and NextFile
  50.             will be relative to this directory.
  51.  
  52.     wld      - the wildcarded path to be matched.
  53.  
  54.     RESULTS
  55.     spath      - a pointer to a SpathInfo structure ready for calls to
  56.             NextFile.
  57.  
  58.     NOTES
  59.     It will be most usual to pass a pointer to a null string for anc,
  60.     this will make all paths relative to the current working directory.
  61.  
  62.     If the wildcarded path ends in a '/' then the search will match only
  63.     directories, and the '/' will be appended to all paths returned by
  64.     BuildPath and NextFile. If you specify a path ending in '/' and then
  65.     ask NextFile to look for only files the search will fail.  If the
  66.     path does not end in a '/' then no '/' will be appended to the path
  67.     returned, regardless of whether the match is to a file or a
  68.     directory.
  69.  
  70.     BUGS
  71.     (well, possible bugs actually)  If one of the elements of the path
  72.     explicitly matches a null string (ie. either /%/ or just //) then
  73.     the routine will match to the parent directory. This works in all of
  74.     the cases I have tried (and the only important use, which is at the
  75.     beginning of the path.) I am just not terribly confident with the
  76.     way it's done, so if funny bugs creep up, look here first.
  77.  
  78.     SEE ALSO
  79.     ParseSregExp, NextFile, BuildPath, FreeSpathInfo
  80.  
  81. sregexp.library/BuildPath               sregexp.library/BuildPath
  82.  
  83.     NAME
  84.     BuildPath -- build the path to the current match to a SpathInfo
  85.              structure
  86.  
  87.     SYNOPSIS
  88.     len = BuildPath(spi,buff,len)
  89.     D0        A0  A1     D0
  90.     int BuildPath(Struct SpathInfo *, char *, int);
  91.  
  92.     FUNCTION
  93.     The path to the current match of the SpathInfo structure is copied
  94.     into the buffer and null terminated.  This will have unpredictable
  95.     results, possibly including fireworks, if it is called before the
  96.     first call to NextFile.
  97.  
  98.     This routine will mainly be used to try again with a bigger buffer
  99.     if NextPath failed with SPE_BUFF_FULL.
  100.  
  101.     INPUTS
  102.     spi      - The pointer returned by a call to AnchorPath
  103.  
  104.     buff      - a buffer length len long to copy the path name into.
  105.  
  106.     len      - the length of the buffer, buff.
  107.  
  108.  
  109.     RESULTS
  110.     len      - exactly the same as returned by NextFile.
  111.  
  112.     SEE ALSO
  113.     NextFile, AnchorPath.
  114.  
  115. sregexp.library/FreeSpathInfo               sregexp.library/FreeSpathInfo
  116.  
  117.     NAME
  118.     FreeSpathInfo -- free up all of the resources locked by calls
  119.              to AnchorPath and NextFile
  120.  
  121.     SYNOPSIS
  122.     FreeSpathInfo(spi)
  123.               A0
  124.     void FreeSpathInfo(struct SpathInfo *);
  125.  
  126.     FUNCTION
  127.     This will free all of the memory and file locks currently wrapped up
  128.     in the SpathInfo structure.  This is the ONLY way you should try to
  129.     free up these resources.
  130.  
  131.     This routine can be called at any point, either immediately after
  132.     the call to AnchorPath, or after any calls to NextFile or BuildPath.
  133.  
  134.     INPUTS
  135.     spi      - A pointer to a SpathInfo structure to be freed.
  136.  
  137.     SEE ALSO
  138.     AnchorPath.
  139.  
  140. sregexp.library/FreeSregExp             sregexp.library/FreeSregExp
  141.  
  142.     NAME
  143.     FreeSregExp -- free up a preparsed wildcard created by ParseSregExp
  144.  
  145.     SYNOPSIS
  146.     FreeSregExp(sreg)
  147.             A0
  148.     void FreeSregExp(struct SregExp *);
  149.  
  150.     FUNCTION
  151.     This routine will free all of the resources associated with a
  152.     preparsed wildcard expression.    This is the only legal way to free
  153.     the object created by ParseSregExp, and you should not try to do it
  154.     yourself.
  155.  
  156.     INPUTS
  157.     sreg      - a pointer to the preparsed wildcard expression returned
  158.             by ParseSregExp.
  159.  
  160.     SEE ALSO
  161.     ParseSregExp, MatchNSregExp, MatchSregExp.
  162.  
  163. sregexp.library/IsWild                      sregexp.library/IsWild
  164.  
  165.     NAME
  166.     IsWild -- test if a string has any unescaped wildcard characters.
  167.  
  168.     SYNOPSIS
  169.     bool = IsWild(wildcard);
  170.     D0          A0
  171.     int IsWild(char *);
  172.  
  173.     FUNCTION
  174.     This routine merely checks if the string contains any unescaped
  175.     wildcard characters.  It does not actually test if the string is
  176.     wild.  For example, it would fail on '(this is a test)' because of
  177.     the round brackets, which are wildcard characters.
  178.  
  179.     INPUTS
  180.     wildcard  - a pointer to a wildcard string.
  181.  
  182.     RESULTS
  183.     bool      - non-zero if any unescaped wildcard characters were
  184.             found.
  185.  
  186.     NOTES
  187.     This routine has very little merit, and is not really all that
  188.     useful.  I will probably add a routine in future versions that does
  189.     the same thing but takes the preparsed wildcard expression and
  190.     returns the unique string which it will match, or NULL.
  191.  
  192.     SEE ALSO
  193.     ParseSregExp.
  194.  
  195. sregexp.library/ParseSregExp            sregexp.library/ParseSregExp
  196.  
  197.     NAME
  198.     ParseSregExp -- preparse a wildcard expression for matching.
  199.  
  200.     SYNOPSIS
  201.     sreg = ParseSregExp(wildcard)
  202.     D0         A0
  203.     struct SregExp *ParseSregExp(char *);
  204.  
  205.     FUNCTION
  206.     A wildcard string must be preparsed before it can be passed to
  207.     MatchSregExp or MatchNSregExp to actually test if it matches a given
  208.     target string.
  209.  
  210.     This function returns a pointer to the successfully created
  211.     structure, or NULL on failure.    On failure, IoErr() can be examined
  212.     to get more information on the cause of the trouble.
  213.     ERROR_INVALID_COMPONENT_NAME is returned if the wildcard string is
  214.     illegal and ERROR_NO_FREE_STORE is returned if memory allocation
  215.     failed.
  216.  
  217.     WILDCARD SYNTAX
  218.     The wildcard syntax accepted is an extension of the usual AmigaDOS
  219.     wildcards.  Any 1.3 wildcard expression should be ok.  Apparently
  220.     under 2.0 they have added a not operator, and the one here may or
  221.     may not be compatible with the way they have done it.  (They SHOULD
  222.     have done it this way.)
  223.  
  224.     Here is a synopsis:
  225.  
  226.     ?        matches any one character
  227.  
  228.     #(pat)      matches zero or more occurrences of the pattern pat.
  229.  
  230.     (pat)       separates out a piece of the pattern.
  231.  
  232.     pat1|pat2   matches to either pat1 or pat2
  233.  
  234.     '           escapes the special meaning of these symbols.
  235.  
  236.     %        matches the null string.
  237.  
  238.     These are the extensions:
  239.  
  240.     [chars]     will match any single character in the set chars,
  241.             specified as single characters or ranges separated by a
  242.             -.    Ex. [af-i+] would match a, f, g, h, i, and +.  If ~
  243.             is the first character in the set then the set matched
  244.             is the complement of the set specified. Ex. [~a-z] would
  245.             match any one character that is not a (lower case if
  246.             case sensitivity is on) letter. Note that a [~a] is NOT
  247.             the same as a ~[a]. The former would match a 'b' but not
  248.             a 'ab', whereas the latter would match both. Special
  249.             care should be taken when using this wildcard in case
  250.             insensitive matches. As expected, [a] would match either
  251.             'a' or 'A' in a case insensitive search, but [~a] would
  252.             match anything, since it doesn't match 'a', but would
  253.             match a 'A'.
  254.  
  255.     ~(pat)      will match anything that doesn't match the pattern.
  256.             Note: it is illegal to repeat a not. ie #~a is illegal.
  257.             (So is #(~(a)) so don't even try it.) You can repeat
  258.             something with a not IN it, as long as it can't be
  259.             reduced to the form #~(pattern). (A #[~a] is OK.)
  260.             However ~#a has the expected effect (matches any
  261.             non-null string not composed entirely of a's.)
  262.  
  263.     *        same as #?.
  264.  
  265.     INPUTS
  266.     wildcard  - a pointer to the null terminated wildcard expression
  267.             string.
  268.  
  269.     RETURNS
  270.     sreg      - a preparsed version of the wildcard expression.
  271.  
  272.     SEE ALSO
  273.     FreeSregExp, MatchNSregExp, MatchSregExp.
  274.  
  275. sregexp.library/MatchNSregExp               sregexp.library/MatchNSregExp
  276.  
  277.     NAME
  278.     MatchNSregExp - match a preparsed wildcard expression to a target
  279.  
  280.     SYNOPSIS
  281.     bool = MatchNSregExp(target,sreg,case,len)
  282.     D0              A0     A1    D0    D1
  283.     int MatchNSregExp(char *, struct SregExp *, int int);
  284.  
  285.     FUNCTION
  286.     This function tests if the given fixed length target string matches
  287.     the preparsed wildcard expression.
  288.  
  289.     This routine is identical to MatchSregExp, except it takes a pointer
  290.     to a string and its length, rather than a null terminated string.
  291.  
  292.     INPUTS
  293.     target      - the null terminated target string you wish to test
  294.             against the wildcard expression.
  295.  
  296.     sreg      - the preparsed wildcard expression.
  297.  
  298.     case      - if this is non-zero then the match is case sensitive,
  299.             otherwise it is case insensitive.
  300.  
  301.     len      - the length of the string pointed to by target.
  302.  
  303.     RESULTS
  304.     bool      - non-zero if the target matches the expression, zero
  305.             otherwise.
  306.  
  307.     NOTES
  308.     See ParseSregExp for a discussion of the wildcard expression and the
  309.     tricky behaviour of character sets (ie. [...]) when the search is
  310.     case insensitive.
  311.  
  312.     This routine is handy for matching BCPL strings.  If p is a c
  313.     pointer (byte, not longword address) of a BCPL string then
  314.  
  315.         MatchNSregExp(p+1,sreg,case,*p)
  316.  
  317.     will test the BCPL string for a match.
  318.  
  319.     SEE ALSO
  320.     FreeSregExp, ParseSregExp, MatchSregExp.
  321.  
  322. sregexp.library/MatchSregExp            sregexp.library/MatchSregExp
  323.  
  324.     NAME
  325.     MatchSregExp - match a preparsed wildcard expression to a target
  326.  
  327.     SYNOPSIS
  328.     bool = MatchSregExp(target,sreg,case)
  329.     D0              A0     A1   D0
  330.     int MatchSregExp(char *, struct SregExp *, int);
  331.  
  332.     FUNCTION
  333.     This function tests if the given null terminated target string
  334.     matches the preparsed wildcard expression.
  335.  
  336.     This routine is identical to MatchNSregExp, except it takes a
  337.     pointer to a null terminated string,  rather than a string and its
  338.     length.
  339.  
  340.     INPUTS
  341.     target      - the null terminated target string you wish to test
  342.             against the wildcard expression.
  343.  
  344.     sreg      - the preparsed wildcard expression.
  345.  
  346.     case      - if this is non-zero then the match is case sensitive,
  347.             otherwise it is case insensitive.
  348.  
  349.     RESULTS
  350.     bool      - non-zero if the target matches the expression, zero
  351.             otherwise.
  352.  
  353.     NOTES
  354.     See ParseSregExp for a discussion of the wildcard expression and the
  355.     tricky behaviour of character sets (ie. [...]) when the search is
  356.     case insensitive.
  357.  
  358.     This call currently just results in the call:
  359.  
  360.         MatchNSregExp(target,sreg,case,strlen(target));
  361.  
  362.     but this may change in future version.
  363.  
  364.     SEE ALSO
  365.     FreeSregExp, ParseSregExp, MatchNSregExp.
  366.  
  367. sregexp.library/NextFile                sregexp.library/NextFile
  368.  
  369.     NAME
  370.     NextFile -- return the next (or first) file matching the path.
  371.  
  372.     SYNOPSIS
  373.     len = NextFile(spi,buff,len,dirs)
  374.     D0           A0  A1    D0  D1
  375.     int NextFile(struct SpathInfo *, char *, int int);
  376.  
  377.     FUNCTION
  378.     This routine copies the path to the next (or first, if this is the
  379.     first call) file or directory matching the wildcard in the SpathInfo
  380.     structure created by a call to AnchorPath.
  381.  
  382.     The usual calling sequence would be:
  383.         AnchorPath
  384.         repeat while no errors and more files
  385.         NextFile
  386.         FreeSpathInfo
  387.  
  388.     The length of the path is returned, or if there is an error or there
  389.     are no more matches a negative result is returned.  Both the
  390.     negative number and the Value if IoErr will give more information
  391.     about why the routine returned.
  392.  
  393.     INPUTS
  394.     spi      - The pointer returned by a call to AnchorPath
  395.  
  396.     buff      - a buffer length len long to copy the path name into.
  397.  
  398.     len      - the length of the buffer, buff.
  399.  
  400.     dirs      - if this is greater than zero, only directories will
  401.             match; if it is zero, both files and directories will
  402.             match; if it is less than zero, only files will match.
  403.             See the defines in the include file.
  404.  
  405.     RESULTS
  406.     len      - on success this will be the length of the path copied
  407.             into the buffer. If it is less than zero, some kind of
  408.             special event is signalled.
  409.             SPE_ALL_DONE  - This signals there are no more matches
  410.                     to the path. IoErr will also be set to
  411.                     ERROR_NO_MORE_ENTRIES
  412.             SPE_ERROR      - Some error happened, see IoErr.
  413.             SPE_BUFF_FULL - The buffer you suplied was not big
  414.                     enough for the path name.  Get a bigger
  415.                     one and call BuildPath.
  416.             SPE_SIGBREAK  - One of the dos break signals was
  417.                     received by your process. This does not
  418.                     clear the signals, but since some
  419.                     searches can take a while it checks
  420.                     every now and again.  You can just clear
  421.                     the signal and call NextPath again to
  422.                     ignore the signal.
  423.  
  424.     NOTES
  425.     It is meaningless to mix calls with a different value of dirs.
  426.     Anything passed by in a call in which you did not ask for objects of
  427.     a given type will not reappear in subsequent calls in which you do
  428.     ask for that type.
  429.  
  430.     SEE ALSO
  431.     AnchorPath, BuildPath.
  432.  
  433.