From 2614d9ba2fb5ad171200cccc88f42fa659b527c6 Mon Sep 17 00:00:00 2001 From: drbrain Date: Fri, 13 Sep 2013 21:08:36 +0000 Subject: * dir.c (dir_s_glob): [DOC] Improve wording and layout. * dir.c (file_s_fnmatch): ditto. * dir.c (Init_Dir): [DOC] Document File::Constants::FNM_XXX constants. (These won't show up in RDoc until a new RDoc is imported.) git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@42940 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- dir.c | 189 ++++++++++++++++++++++++++++++++++++++++-------------------------- 1 file changed, 115 insertions(+), 74 deletions(-) (limited to 'dir.c') diff --git a/dir.c b/dir.c index f42a769..40e5537 100644 --- a/dir.c +++ b/dir.c @@ -1792,49 +1792,56 @@ dir_s_aref(int argc, VALUE *argv, VALUE obj) /* * call-seq: - * Dir.glob( pattern, [flags] ) -> array - * Dir.glob( pattern, [flags] ) {| filename | block } -> nil - * - * Returns the filenames found by expanding pattern which is - * an +Array+ of the patterns or the pattern +String+, either as an - * array or as parameters to the block. Note that this pattern - * is not a regexp (it's closer to a shell glob). See - * File::fnmatch for the meaning of the flags - * parameter. Note that case sensitivity depends on your system (so - * File::FNM_CASEFOLD is ignored), as does the order - * in which the results are returned. - * - * *:: Matches any file. Can be restricted by - * other values in the glob. * - * will match all files; c* will - * match all files beginning with - * c; *c will match - * all files ending with c; and - * \*c\* will match all files that - * have c in them (including at - * the beginning or end). Equivalent to - * / .* /x in regexp. Note, this - * will not match Unix-like hidden files (dotfiles). - * In order to include those in the match results, - * you must use something like "{*,.*}". - * **:: Matches directories recursively. - * ?:: Matches any one character. Equivalent to - * /.{1}/ in regexp. - * [set]:: Matches any one character in +set+. - * Behaves exactly like character sets in - * Regexp, including set negation - * ([^a-z]). - * {p,q}:: Matches either literal p or - * literal q. Matching literals - * may be more than one character in length. - * More than two literals may be specified. - * Equivalent to pattern alternation in - * regexp. - * \\ :: Escapes the next metacharacter. - * Note that this means you cannot use backslash - * in windows as part of a glob, - * i.e. Dir["c:\\foo*"] will not work, - * use Dir["c:/foo*"] instead. + * Dir.glob( pattern, [flags] ) -> matches + * Dir.glob( pattern, [flags] ) { |filename| block } -> nil + * + * Expands +pattern+, which is an Array of patterns or a pattern String, and + * returns the results as +matches+ or as arguments given to the block. + * + * Note that this pattern is not a regexp, it's closer to a shell glob. See + * File::fnmatch for the meaning of the +flags+ parameter. Note that case + * sensitivity depends on your system (so File::FNM_CASEFOLD is ignored), as + * does the order in which the results are returned. + * + * *:: + * Matches any file. Can be restricted by other values in the glob. + * Equivalent to / .* /x in regexp. + * + * *:: Matches all files + * c*:: Matches all files beginning with c + * *c:: Matches all files ending with c + * \*c\*:: Match all files that have c in them + * (including at the beginning or end). + * + * Note, this will not match Unix-like hidden files (dotfiles). In order + * to include those in the match results, you must use the + * File::FNM_DOTMATCH flag or something like "{*,.*}". + * + * **:: + * Matches directories recursively. + * + * ?:: + * Matches any one character. Equivalent to /.{1}/ in regexp. + * + * [set]:: + * Matches any one character in +set+. Behaves exactly like character sets + * in Regexp, including set negation ([^a-z]). + * + * {p,q}:: + * Matches either literal p or literal q. + * Equivalent to pattern alternation in regexp. + * + * Matching literals may be more than one character in length. More than + * two literals may be specified. + * + * \\ :: + * Escapes the next metacharacter. + * + * Note that this means you cannot use backslash on windows as part of a + * glob, i.e. Dir["c:\\foo*"] will not work, use + * Dir["c:/foo*"] instead. + * + * Examples: * * Dir["config.?"] #=> ["config.h"] * Dir.glob("config.?") #=> ["config.h"] @@ -1983,37 +1990,44 @@ fnmatch_brace(const char *pattern, VALUE val, void *enc) * File.fnmatch( pattern, path, [flags] ) -> (true or false) * File.fnmatch?( pattern, path, [flags] ) -> (true or false) * - * Returns true if path matches against pattern The - * pattern is not a regular expression; instead it follows rules - * similar to shell filename globbing. It may contain the following - * metacharacters: - * - * *:: Matches any file. Can be restricted by - * other values in the glob. * - * will match all files; c* will - * match all files beginning with - * c; *c will match - * all files ending with c; and - * \*c* will match all files that - * have c in them (including at - * the beginning or end). Equivalent to - * / .* /x in regexp. - * **:: Matches directories recursively or files - * expansively. - * ?:: Matches any one character. Equivalent to - * /.{1}/ in regexp. - * [set]:: Matches any one character in +set+. - * Behaves exactly like character sets in - * Regexp, including set negation - * ([^a-z]). - * \ :: Escapes the next metacharacter. - * {a,b}:: Matches pattern a and pattern b if - * File::FNM_EXTGLOB flag is enabled. - * Behaves like a Regexp union ((?:a|b)). - * - * flags is a bitwise OR of the FNM_xxx - * parameters. The same glob pattern and flags are used by - * Dir::glob. + * Returns true if +path+ matches against +pattern+. The pattern is not a + * regular expression; instead it follows rules similar to shell filename + * globbing. It may contain the following metacharacters: + * + * *:: + * Matches any file. Can be restricted by other values in the glob. + * Equivalent to / .* /x in regexp. + * + * *:: Matches all files regular files + * c*:: Matches all files beginning with c + * *c:: Matches all files ending with c + * \*c*:: Matches all files that have c in them + * (including at the beginning or end). + * + * To match hidden files (that start with a . set the + * File::FNM_DOTMATCH flag. + * + * **:: + * Matches directories recursively or files expansively. + * + * ?:: + * Matches any one character. Equivalent to /.{1}/ in regexp. + * + * [set]:: + * Matches any one character in +set+. Behaves exactly like character sets + * in Regexp, including set negation ([^a-z]). + * + * \ :: + * Escapes the next metacharacter. + * + * {a,b}:: + * Matches pattern a and pattern b if File::FNM_EXTGLOB flag is enabled. + * Behaves like a Regexp union ((?:a|b)). + * + * +flags+ is a bitwise OR of the FNM_XXX constants. The same + * glob pattern and flags are used by Dir::glob. + * + * Examples: * * File.fnmatch('cat', 'cat') #=> true # match entire string * File.fnmatch('cat', 'category') #=> false # only match partial string @@ -2197,10 +2211,37 @@ Init_Dir(void) rb_define_singleton_method(rb_cFile,"fnmatch", file_s_fnmatch, -1); rb_define_singleton_method(rb_cFile,"fnmatch?", file_s_fnmatch, -1); + /* Document-const: File::Constants::FNM_NOESCAPE + * + * Disables escapes in File.fnmatch and Dir.glob patterns + */ rb_file_const("FNM_NOESCAPE", INT2FIX(FNM_NOESCAPE)); + + /* Document-const: File::Constants::FNM_PATHNAME + * + * Wildcards in File.fnmatch and Dir.glob patterns do not match directory + * separators + */ rb_file_const("FNM_PATHNAME", INT2FIX(FNM_PATHNAME)); + + /* Document-const: File::Constants::FNM_DOTMATCH + * + * The '*' wildcard matches filenames starting with "." in File.fnmatch + * and Dir.glob patterns + */ rb_file_const("FNM_DOTMATCH", INT2FIX(FNM_DOTMATCH)); + + /* Document-const: File::Constants::FNM_CASEFOLD + * + * Makes File.fnmatch patterns case insensitive (but not Dir.glob + * patterns). + */ rb_file_const("FNM_CASEFOLD", INT2FIX(FNM_CASEFOLD)); + + /* Document-const: File::Constants::FNM_EXTGLOB + * + * Allows file globbing through "{a,b}" in File.fnmatch patterns. + */ rb_file_const("FNM_EXTGLOB", INT2FIX(FNM_EXTGLOB)); rb_file_const("FNM_SYSCASE", INT2FIX(FNM_SYSCASE)); } -- cgit v1.1