class RbFind::Done

Usage

See the README file or “rbfind -h” for a documentation of the command line tool.

In Ruby programs, you may call:

RbFind.run                do puts path end
RbFind.run "dir"          do puts path end
RbFind.run "dir1", "dir2" do puts path end
RbFind.run %w(dir1 dir2)  do puts path end
RbFind.run "dir", :max_depth => 3 do puts path end

File properties

name          # file name (*)
path          # file path relative to working directory (*)
fullpath      # full file path (*)
path!         # directories with a slash appended (*)
fullpath!     # directories with a slash appended (*)
dirname       # dirname of path
ext           # file name extension
without_ext   # file name without extension
depth         # step depth
hidden?       # filename starting with "." (No Windows version, yet.)
visible?      # not hidden?
stat          # file status information (File::Stat object)
mode          # access mode (like 0755, 0644)
mtime         # modify time (atime, ctime as well)
mage          # age in seconds since walk started
age           # alias for mage
user          # owner
owner         # dto. (alias)
group         # group owner
user!         # owner, "." if process owner
owner!        # dto. (alias)
group!        # group owner, "." if process owner
readlink      # symlink pointer or nil (*)
broken_link?  # what you expect
arrow         # ls-style "-> symlink" suffix (*)

              # (*) = colored version available (see below)

empty?               # directory is empty
entries              # directory entries

open  { |o| ... }    # open file
read n = nil         # read first n bytes, nil reads to eof
lines { |l,i| ... }  # open file and yield each |line,lineno|
grep re              # lines with `l =~ re and colsep path, i, l'
binary? n = 1   # test whether first n blocks contain null characters
bin?            # alias for binary?

vimswap?      # it is a Vim swapfile

Further will be redirected to the stat object (selective):

directory?
executable?
file?
pipe?
socket?
symlink?

readable?
writable?
size
zero?

uid
gid
owned?
grpowned?

dir?         # alias for directory?

Derivated from stat:

stype        # one-letter (short) version of ftype
modes        # rwxr-xr-x style modes

filesize                    # returns size for files, else nil
filesize { |s| s > 1024 }   # returns block result for files

Actions

done    # exit from current entry
done!   # dto.
prune   # do not descend directory; abort current entry
prune!  # dto.
no_vcs  # omit .svn, CVS and .git directories
novcs   # dto.

colsep path, ...   # output parameters in a line separated by colons
col_sep            #   dto. (alias)
tabsep path, ...   # separate by tabs
tab_sep            #
spcsep path, ...   # separate by spaces
spc_sep            #
spacesep path, ... #
space_sep          #
p                  # alias for space_sep
csv sep, path, ... # separate by user-defined separator

rename newname   # rename, but leave it in the same directory
mv newname       # dto.
rm               # remove

Color support

cname       # colorized name
cpath       # colorized path
cpath!      # colorized path!
cfullpath   # colorized fullpath
cfullpath!  # colorized fullpath!
creadlink   # colored symlink pointer
carrow      # colored "-> symlink" suffix

color arg   # colorize argument
colour arg  # alias

RbFind.colors str      # define colors
RbFind.colours str     # alias

Default color setup is "xxHbexfxcxdxbxegedabagacadAx".
In case you did not call RbFind::Walk.colors, the environment variables
RBFIND_COLORS and RBFIND_COLOURS are looked up. If neither is given
but LSCOLORS is set, the fields 2-13 default to that.
A Gnu LS_COLOR-style string may also be given, though glob patterns will
not be unregarded. If LS_COLORS is set, the colors default to that.

The letters mean:
  a = black, b = red, c = green, d = brown, e = blue,
  f = magenta, g = cyan, h = light grey
  upper case = bold (resp. dark grey, yellow)

  first character = foreground, second character = background

The character pairs map the following types:
   0  regular file
   1  nonexistent (broken link)
   2  directory
   3  symbolic link
   4  socket
   5  pipe
   6  executable
   7  block special
   8  character special
   9  executable with setuid bit set
  10  executable with setgid bit set
  11  directory writable to others, with sticky bit
  12  directory writable to others, without sticky bit
  13  whiteout
  14  unknown

suffix      # ls-like suffixes |@=/%* for pipe, ..., executable

Encoding issues

Ruby raises an ArgumentError if, for example, an ISO8859-1-encoded string gets read in as UTF-8-encoded and then is matched against a UTF-8-encoded regular expression. This will happen if you are running RbFind::Walk from an environment with something like LANG=“de_DE.UTF-8” and if you are searching directories containing single-byte encoded file names or files with single-byte or binary content.

The grep facility will condone encoding mismatches by calling the String#scrub! method. But neither the lines and read function will do any transformation nor will the file names and the path specifications be changed.

In short, if you are using the grep method, or the -g option on the command line you will not need to care about encoding problems. On the other hand, if you specify the =~ operator, you will be responsible for calling the String#scrub method yourself. Please do not try to call the String#scrub! (bang) method for the name and path variables because these will be used in the further processing.

Examples

Find them all:

RbFind.run do puts path end

Omit version control:

RbFind.run "myproject" do
  prune if name == ".svn"
  puts path
end

# or even
RbFind.run "myproject" do
  novcs
  puts path
end

Mention directory contents before directory itself:

RbFind.run "myproject", depth_first: true do
  puts path
end

Limit search depth:

RbFind.run max_depth: 2 do
  puts path
end

Unsorted (alphabetical sort is default):

RbFind.run sort: false do
  puts path
end

Reverse sort:

RbFind.run sort: true, reverse: true do
  puts path
end

Sort without case sensitivity and preceding dot:

s = proc { name =~ /^\.?/ ; $'.downcase }
RbFind.run sort: s do
  puts path
end