diff --git a/lib/fileutils.rb b/lib/fileutils.rb index cbf7f52..f417154 100644 --- a/lib/fileutils.rb +++ b/lib/fileutils.rb @@ -18,6 +18,38 @@ # # Namespace for several file utility methods for copying, moving, removing, etc. # +# == About the Examples +# +# Some examples here involve trees of file entries. +# For these, we sometimes display trees using the +# {tree command-line utility}[https://en.wikipedia.org/wiki/Tree_(command)], +# which is a recursive directory-listing utility that produces +# a depth-indented listing of files and directories. +# +# We use a helper method to launch the command and control the format: +# +# def tree(dirpath = '.') +# command = "tree --noreport --charset=ascii #{dirpath}" +# system(command) +# end +# +# To illustrate, here's the tree for the test directory for \FileUtils: +# tree('test') +# test +# |-- fileutils +# | |-- clobber.rb +# | |-- fileasserts.rb +# | |-- test_dryrun.rb +# | |-- test_fileutils.rb +# | |-- test_nowrite.rb +# | |-- test_verbose.rb +# | `-- visibility_tests.rb +# `-- lib +# |-- core_assertions.rb +# |-- envutil.rb +# |-- find_executable.rb +# `-- helper.rb +# # === Module Functions # # require 'fileutils' @@ -839,7 +871,7 @@ def cp_r(src, dest, preserve: nil, noop: nil, verbose: nil, # # If +src+ is a directory, recursively copies +src+ to +dest+: # - # system('tree --charset=ascii src1') + # tree('src1') # src1 # |-- dir0 # | |-- src0.txt @@ -848,7 +880,7 @@ def cp_r(src, dest, preserve: nil, noop: nil, verbose: nil, # |-- src2.txt # `-- src3.txt # FileUtils.copy_entry('src1', 'dest1') - # system('tree --charset=ascii dest1') + # tree('dest1') # dest1 # |-- dir0 # | |-- src0.txt @@ -923,14 +955,14 @@ def copy_stream(src, dest) # If +src+ is the path to a single file or directory and +dest+ does not exist, # moves +src+ to +dest+: # - # system('tree --charset=ascii src0') + # tree('src0') # src0 # |-- src0.txt # `-- src1.txt # File.exist?('dest0') # => false # FileUtils.mv('src0', 'dest0') # File.exist?('src0') # => false - # system('tree --charset=ascii dest0') + # tree('dest0') # dest0 # |-- src0.txt # `-- src1.txt @@ -940,13 +972,13 @@ def copy_stream(src, dest) # copies from each path in the array to +dest+: # # File.file?('src1.txt') # => true - # system('tree --charset=ascii src1') + # tree('src1') # src1 # |-- src.dat # `-- src.txt # Dir.empty?('dest1') # => true # FileUtils.mv(['src1.txt', 'src1'], 'dest1') - # system('tree --charset=ascii dest1') + # tree('dest1') # dest1 # |-- src1 # | |-- src.dat @@ -1076,7 +1108,7 @@ def rm_f(list, noop: nil, verbose: nil) # # For each directory path, recursively removes files and directories: # - # system('tree --charset=ascii src1') + # tree('src1') # src1 # |-- dir0 # | |-- src0.txt