cuprum-cli 0.1.0 → 0.2.0

data/lib/cuprum/cli/dependencies/file_system/mock.rb

@@ -32,7 +32,7 @@ module Cuprum::Cli::Dependencies
     def initialize(files: {}, root_path: Dir.pwd)
       super(root_path:)
 
-      @files     = files
+      @files     = split_files(files)
       @tempfiles = []
     end
 
@@ -44,7 +44,7 @@ module Cuprum::Cli::Dependencies
 
     # (see Cuprum::Cli::Dependencies::FileSystem#create_directory)
     def create_directory(path, recursive: false) # rubocop:disable Metrics/MethodLength
-      tools.assertions.validate_name(path, as: 'path')
+      validate_file_path(path, as: 'path')
 
       *dir_names, dir_name = split_path(resolve_path(path))
 
@@ -60,15 +60,69 @@ module Cuprum::Cli::Dependencies
           "unable to create directory #{path} - directory is a file"
       end
 
-      directory[dir_name] = {}
+      directory[dir_name] ||= {}
 
       path
     end
     alias make_directory create_directory
 
+    # (see Cuprum::Cli::Dependencies::FileSystem#delete_directory)
+    def delete_directory(path, force: false, recursive: false) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      validate_file_path(path, as: 'path')
+
+      *dir_names, dir_name = split_path(resolve_path(path))
+
+      dir = dir_names.reduce(files) do |dir, dir_name|
+        require_directory(action: 'delete directory', dir: dir[dir_name], path:)
+
+        dir[dir_name]
+      end
+
+      require_directory(action: 'delete directory', dir: dir[dir_name], path:)
+
+      is_empty =
+        (recursive && empty_directories?(dir[dir_name])) || dir[dir_name].empty?
+
+      if force || is_empty
+        dir.delete(dir_name)
+
+        return path
+      end
+
+      raise DirectoryNotEmptyError,
+        "unable to delete directory #{path} - directory is not empty"
+    end
+    alias remove_directory delete_directory
+
+    # (see Cuprum::Cli::Dependencies::FileSystem#delete_file)
+    def delete_file(path) # rubocop:disable Metrics/MethodLength
+      validate_file_path(path, as: 'path')
+
+      resolved = resolve_path(path)
+
+      if directory?(resolved)
+        raise FileIsADirectoryError,
+          "unable to delete file #{path} - file is a directory"
+      end
+
+      unless file?(resolved)
+        raise FileNotFoundError,
+          "unable to delete file #{path} - file not found"
+      end
+
+      *relative, file = split_path(resolved)
+
+      directory = relative.empty? ? files : files.dig(*relative)
+
+      directory.delete(file)
+
+      path
+    end
+    alias remove_file delete_file
+
     # (see Cuprum::Cli::Dependencies::FileSystem#directory?)
     def directory?(path)
-      tools.assertions.validate_name(path, as: 'path')
+      validate_file_path(path, as: 'path')
 
       path = resolve_path(path)
       mock = resolve_mock(path)
@@ -78,21 +132,33 @@ module Cuprum::Cli::Dependencies
     alias directory_exists? directory?
 
     # (see Cuprum::Cli::Dependencies::FileSystem#each_file)
-    def each_file(pattern, &)
+    def each_file(pattern, &) # rubocop:disable Metrics/AbcSize
       return enum_for(:each_file, pattern) unless block_given?
 
-      flattened_files.each do |file_path|
+      absolute_path = pattern.is_a?(String) && pattern.start_with?(root_path)
+
+      pattern = pattern[(root_path.length + 1)..] if absolute_path
+
+      [*expanded_dirs, *flattened_files].each do |file_path|
         next unless matches_pattern?(file_path:, pattern:)
 
-        yield File.join(root_path, file_path)
+        yield absolute_path ? File.join(root_path, file_path) : file_path
       end
 
       nil
     end
 
+    # @return [Array<String>] a list of the defined directory paths in the mock
+    #   file system.
+    def expanded_dirs = expand_dirs(files:).to_a.sort
+
+    # @return [Array<String>] a list of the defined file paths in the mock file
+    #   system.
+    def flattened_files = flatten_files(files:).sort
+
     # (see Cuprum::Cli::Dependencies::FileSystem#directory?)
     def file?(path)
-      tools.assertions.validate_name(path, as: 'path')
+      validate_file_path(path, as: 'path')
 
       path = resolve_path(path)
       mock = resolve_mock(path)
@@ -177,6 +243,32 @@ module Cuprum::Cli::Dependencies
 
     private
 
+    def empty_directories?(dir)
+      return false unless dir.is_a?(Hash)
+
+      return true if dir.empty?
+
+      dir.each_value.all? { |item| empty_directories?(item) }
+    end
+
+    def expand_dirs(files:, flat: Set.new, path: '')
+      files.each do |name, value|
+        qualified_path = path.empty? ? name : File.join(path, name)
+
+        next unless value.is_a?(Hash)
+
+        flat << qualified_path
+
+        qualified_path.split('/').reduce do |memo, segment|
+          "#{memo}/#{segment}".tap { |str| flat << str }
+        end
+
+        expand_dirs(files: value, flat:, path: qualified_path)
+      end
+
+      flat
+    end
+
     def flatten_files(files:, flat: [], path: '')
       files.each do |name, value|
         qualified_path = path.empty? ? name : File.join(path, name)
@@ -189,10 +281,6 @@ module Cuprum::Cli::Dependencies
       flat
     end
 
-    def flattened_files
-      @flattened_files || flatten_files(files:)
-    end
-
     def io_stream?(file_or_path)
       super || file_or_path.is_a?(MockTempfile)
     end
@@ -207,12 +295,19 @@ module Cuprum::Cli::Dependencies
 
       return false unless entry_names.length >= prefix_count + suffix_count
 
-      entry_names[...prefix_count]
-        .zip(prefix_strings)
-        .concat(entry_names[-suffix_count...].zip(suffix_strings))
-        .all? do |entry_name, pattern_string|
-          matches_pattern_string?(entry_name:, pattern_string:)
-        end
+      matchers = entry_names[...prefix_count].zip(prefix_strings)
+
+      if suffix_count.zero?
+        # For a globbed pattern, if there is no suffix there must still be at
+        # least one entry to match the '**' pattern.
+        matchers.push([entry_names[prefix_count], '*'])
+      else
+        matchers.concat(entry_names[-suffix_count...].zip(suffix_strings))
+      end
+
+      matchers.all? do |entry_name, pattern_string|
+        matches_pattern_string?(entry_name:, pattern_string:)
+      end
     end
 
     def matches_pattern?(file_path:, pattern:)
@@ -242,6 +337,16 @@ module Cuprum::Cli::Dependencies
       end
     end
 
+    def require_directory(action:, dir:, path:)
+      if io_stream?(dir)
+        raise DirectoryIsAFileError,
+          "unable to #{action} #{path} - directory is a file"
+      elsif dir.nil?
+        raise DirectoryNotFoundError,
+          "unable to #{action} #{path} - directory not found"
+      end
+    end
+
     def resolve_mock(path)
       return unless path.start_with?(root_path)
 
@@ -256,6 +361,33 @@ module Cuprum::Cli::Dependencies
       dir&.[](last)
     end
 
+    def split_files(files) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      files.each.with_object({}) do |(key, value), hsh|
+        value = split_files(value)  if value.is_a?(Hash)
+        value = StringIO.new(value) if value.is_a?(String)
+
+        next hsh[key] = value unless key.include?('/')
+
+        # Normalize key, removing root path and leading slash.
+        key = key[root_path.length..] if key.start_with?(root_path)
+        key = key[1..]                if key.start_with?('/')
+
+        *dir, file = key.split('/')
+
+        # Ensure that each directory is represented by a Hash.
+        dir.each do |segment|
+          hsh[segment] = {} unless hsh.key?(segment)
+
+          raise "invalid file path #{key}" unless hsh[segment].is_a?(Hash)
+
+          hsh = hsh[segment]
+        end
+
+        # Assign the file or directory value.
+        hsh[file] = value
+      end
+    end
+
     def split_path(path)
       path[(1 + root_path.length)..]
         &.split(File::SEPARATOR) || []

data/lib/cuprum/cli/dependencies/file_system.rb

@@ -17,9 +17,15 @@ module Cuprum::Cli::Dependencies
     # Exception raised when attempting to access a file as a directory.
     class DirectoryIsAFileError < FileError; end
 
+    # Exception raised when attempting to delete a non-empty directory.
+    class DirectoryNotEmptyError < FileError; end
+
     # Exception raised when attempting to access a non-existent directory.
     class DirectoryNotFoundError < FileError; end
 
+    # Exception raised when attempting to overwrite an existing file.
+    class FileAlreadyExistsError < FileError; end
+
     # Exception raised when attempting to access a directory as a file.
     class FileIsADirectoryError < FileError; end
 
@@ -35,6 +41,57 @@ module Cuprum::Cli::Dependencies
     # @return [String] the path to the root directory.
     attr_reader :root_path
 
+    # @overload copy_file(source_path, destination_path, force: false)
+    #   Copies the contents of the source file to the destination path.
+    #
+    #   @param source_path [String] the path of the file to copy.
+    #   @param target_path [String] the path to write the file to.
+    #   @param force [true, false] if true, overwrites an existing file (not a
+    #     directory) at the destination path. Defaults to false.
+    #
+    #   @return [Integer] the number of bytes written.
+    #
+    #   @raise [FileNotFoundError] if the file to copy does not exist.
+    #   @raise [FileIsADirectoryError] if the file to copy is a directory, or if
+    #     there is a directory at the destination path.
+    #   @raise [FileAlreadyExistsError] if there is a file at the destination
+    #     path and the force: option is false.
+    #
+    # @overload copy_file(source_path, destination_path, force: false) { |source| }
+    #   Reads the source file and generates a new file with modified contents.
+    #
+    #   @param source_path [String] the path of the file to copy.
+    #   @param target_path [String] the path to write the file to.
+    #   @param force [true, false] if true, overwrites an existing file (not a
+    #     directory) at the destination path. Defaults to false.
+    #
+    #   @return [Integer] the number of bytes written.
+    #
+    #   @yield the transformation function used to modify the contents of the
+    #     file.
+    #   @yieldparam source [String] the contents of the source file.
+    #   @yieldreturn [String] the contents of the destination file.
+    #
+    #   @raise [FileNotFoundError] if the file to copy does not exist.
+    #   @raise [FileIsADirectoryError] if the file to copy is a directory, or if
+    #     there is a directory at the destination path.
+    #   @raise [FileAlreadyExistsError] if there is a file at the destination
+    #     path and the force: option is false.
+    def copy_file(source_path, destination_path, force: false, &block)
+      validate_file_path(source_path,      as: 'source_path')
+      validate_file_path(destination_path, as: 'destination_path')
+
+      if !force && file?(destination_path)
+        raise FileAlreadyExistsError,
+          "unable to write file #{destination_path} - file already exists"
+      end
+
+      contents = read_file(source_path)
+      contents = block.call(contents) if block
+
+      write_file(destination_path, contents)
+    end
+
     # Creates a directory at the requested path.
     #
     # @param path [String] the path to the directory.
@@ -43,13 +100,13 @@ module Cuprum::Cli::Dependencies
     #
     # @return [String] the path to the created directory.
     def create_directory(path, recursive: false)
-      tools.assertions.validate_name(path, as: 'path')
+      validate_file_path(path, as: 'path')
 
       resolved = resolve_path(path)
 
       return path if directory?(resolved)
 
-      handle_create_errors(path) do
+      handle_create_directory_errors(path) do
         recursive ? FileUtils.mkdir_p(resolved) : FileUtils.mkdir(resolved)
       end
 
@@ -57,6 +114,58 @@ module Cuprum::Cli::Dependencies
     end
     alias make_directory create_directory
 
+    # Removes the directory at the requested path.
+    #
+    # Fails if the directory contains any files or child directories. The
+    # :recursive option enables removing empty child or descendent directories,
+    # while the :force option enables removing both files and directories.
+    #
+    # @param path [String] the path to the directory.
+    # @param force [true, false] if true, removes nested files and directories.
+    # @param recursive [true, false] if true, removes nested empty directories.
+    #
+    # @return [String] the path to the removed directory.
+    def delete_directory(path, force: false, recursive: false)
+      validate_file_path(path, as: 'path')
+
+      resolved = resolve_path(path)
+
+      handle_delete_directory_errors(path) do
+        if force || (recursive && empty_directories?(resolved))
+          FileUtils.remove_dir(resolved)
+        else
+          Dir.rmdir(resolved)
+        end
+      end
+
+      path
+    end
+    alias remove_directory delete_directory
+
+    # Removes the file at the requested path.
+    #
+    # @param path [String] the path to the file.
+    #
+    # @return [String] the path to the removed file.
+    def delete_file(path) # rubocop:disable Metrics/MethodLength
+      validate_file_path(path, as: 'path')
+
+      resolved = resolve_path(path)
+
+      if directory?(resolved)
+        raise FileIsADirectoryError,
+          "unable to delete file #{path} - file is a directory"
+      end
+
+      File.delete(resolved)
+
+      path
+    rescue Errno::ENOENT, Errno::EPERM
+      raise FileNotFoundError,
+        "unable to delete file #{path} - file not found"
+    end
+    alias remove_file delete_file
+
     # Checks if the requested directory exists.
     #
     # @param path [String] the path to the requested directory.
@@ -64,7 +173,7 @@ module Cuprum::Cli::Dependencies
     # @return [true, false] true if the directory exists and is a directory,
     #   otherwise false.
     def directory?(path)
-      tools.assertions.validate_name(path, as: 'path')
+      validate_file_path(path, as: 'path')
 
       path = resolve_path(path)
 
@@ -90,9 +199,7 @@ module Cuprum::Cli::Dependencies
     def each_file(pattern, &)
       return enum_for(:each_file, pattern) unless block_given?
 
-      path = resolve_path(pattern)
-
-      Dir[path].each(&)
+      Dir.glob(pattern, base: root_path, &)
 
       nil
     end
@@ -104,7 +211,7 @@ module Cuprum::Cli::Dependencies
     # @return [true, false] true if the file exists and is a file,
     #   otherwise false.
     def file?(path)
-      tools.assertions.validate_name(path, as: 'path')
+      validate_file_path(path, as: 'path')
 
       path = resolve_path(path)
 
@@ -180,17 +287,21 @@ module Cuprum::Cli::Dependencies
 
       path = resolve_path(file_or_path)
 
-      handle_write_errors(file_or_path) { File.write(path, data) }
+      handle_write_file_errors(file_or_path) { File.write(path, data) }
     end
     alias write write_file
 
     private
 
+    def empty_directories?(dir)
+      Dir[File.join(dir, '**', '*')].all? { |dir| File.directory?(dir) }
+    end
+
     def empty_file_message(as:)
       tools.assertions.error_message_for('presence', as:)
     end
 
-    def handle_create_errors(path)
+    def handle_create_directory_errors(path)
       yield
     rescue Errno::EEXIST
       raise Cuprum::Cli::Dependencies::FileSystem::DirectoryIsAFileError,
@@ -198,9 +309,25 @@ module Cuprum::Cli::Dependencies
     rescue Errno::ENOENT
       raise Cuprum::Cli::Dependencies::FileSystem::DirectoryNotFoundError,
         "unable to create directory #{path} - directory not found"
+    rescue Errno::ENOTDIR
+      raise DirectoryIsAFileError,
+        "unable to create directory #{path} - directory is a file"
+    end
+
+    def handle_delete_directory_errors(path)
+      yield
+    rescue Errno::ENOENT
+      raise DirectoryNotFoundError,
+        "unable to delete directory #{path} - directory not found"
+    rescue Errno::ENOTDIR
+      raise DirectoryIsAFileError,
+        "unable to delete directory #{path} - directory is a file"
+    rescue Errno::ENOTEMPTY
+      raise DirectoryNotEmptyError,
+        "unable to delete directory #{path} - directory is not empty"
     end
 
-    def handle_write_errors(file_or_path)
+    def handle_write_file_errors(file_or_path)
       yield
     rescue Errno::EISDIR
       raise FileIsADirectoryError,
@@ -243,5 +370,13 @@ module Cuprum::Cli::Dependencies
         raise ArgumentError, invalid_file_message(as:)
       end
     end
+
+    def validate_file_path(path, as:)
+      tools.assertions.validate_presence(path, as:) if path.nil?
+
+      tools.assertions.validate_instance_of(path, as:, expected: String)
+
+      tools.assertions.validate_presence(path, as:)
+    end
   end
 end

data/lib/cuprum/cli/dependencies.rb

@@ -7,6 +7,7 @@ require 'cuprum/cli'
 module Cuprum::Cli
   # Dependencies provide standard functionality to commands.
   module Dependencies
+    autoload :Clock,         'cuprum/cli/dependencies/clock'
     autoload :FileSystem,    'cuprum/cli/dependencies/file_system'
     autoload :StandardIo,    'cuprum/cli/dependencies/standard_io'
     autoload :SystemCommand, 'cuprum/cli/dependencies/system_command'
@@ -15,6 +16,7 @@ module Cuprum::Cli
     def self.provider
       @provider ||= Plumbum::ManyProvider.new(
         values: {
+          clock:          Clock.new,
           file_system:    FileSystem.new,
           standard_io:    StandardIo.new,
           system_command: SystemCommand.new

data/lib/cuprum/cli/errors.rb

@@ -5,7 +5,6 @@ require 'cuprum/cli'
 module Cuprum::Cli
   # Namespace for errors, which represent failure states of commands.
   module Errors
-    autoload :Files,                'cuprum/cli/errors/files'
     autoload :SystemCommandFailure, 'cuprum/cli/errors/system_command_failure'
   end
 end

data/lib/cuprum/cli/{commands/file/generate_file.rb → files/create_file.rb}

@@ -3,22 +3,18 @@
 require 'cuprum/command'
 require 'plumbum'
 
-require 'cuprum/cli/commands/file'
-require 'cuprum/cli/commands/file/render_erb'
 require 'cuprum/cli/dependencies'
 require 'cuprum/cli/dependencies/file_system'
-require 'cuprum/cli/errors/files/missing_template'
+require 'cuprum/cli/files'
 require 'cuprum/cli/options'
 
-module Cuprum::Cli::Commands::File
-  # Utility command for generating a file from a template.
-  class GenerateFile < Cuprum::Command
+module Cuprum::Cli::Files
+  # Utility command for creating a file with specified contents.
+  class CreateFile < Cuprum::Command
     include Plumbum::Consumer
     prepend Plumbum::Parameters
     include Cuprum::Cli::Dependencies::StandardIo::Helpers
     extend  Cuprum::Cli::Options::ClassMethods
-    include Cuprum::Cli::Options::Quiet
-    include Cuprum::Cli::Options::Verbose
 
     dependency :file_system
     dependency :standard_io
@@ -77,28 +73,10 @@ module Cuprum::Cli::Commands::File
     end
 
     def file_not_writeable_error(**)
-      Cuprum::Cli::Errors::Files::FileNotWriteable.new(**)
+      Cuprum::Cli::Files::Errors::FileNotWriteable.new(**)
     end
 
-    def load_template(file_path:, template_path:)
-      file_system.read_file(template_path)
-    rescue Cuprum::Cli::Dependencies::FileSystem::FileNotFoundError
-      error = Cuprum::Cli::Errors::Files::MissingTemplate.new(
-        message:       "unable to generate file #{file_path}",
-        template_path:
-      )
-      failure(error)
-    end
-
-    def process(file_path:, parameters:, template_path:)
-      say "Generating file #{file_path}..."
-
-      template = step { load_template(file_path:, template_path:) }
-      contents =
-        step { render_template(parameters:, template:, template_path:) }
-
-      report_file_contents(contents)
-
+    def process(contents:, file_path:)
       step { create_directory(file_path:) }
 
       step { write_file(contents:, file_path:) }
@@ -106,26 +84,6 @@ module Cuprum::Cli::Commands::File
       file_path
     end
 
-    def render_template(parameters:, template:, template_path:)
-      case File.extname(template_path)
-      when '.erb'
-        RenderErb.new(template_name: template_path).call(template, **parameters)
-      else
-        template
-      end
-    end
-
-    def report_file_contents(contents)
-      say "\n", verbose: true
-      say(
-        contents
-          .each_line
-          .map { |line| line == "\n" ? "\n" : "  #{line}" }.join,
-        verbose: true
-      )
-      say "\n", verbose: true
-    end
-
     def write_file(contents:, file_path:)
       step { check_if_file_is_directory(file_path:) }
       step { check_if_file_already_exists(file_path:) }

data/lib/cuprum/cli/{commands/file → files/engines}/render_erb.rb

@@ -3,10 +3,10 @@
 require 'cuprum/command'
 require 'herb'
 
-require 'cuprum/cli/commands/file'
-require 'cuprum/cli/errors/files/missing_parameter'
+require 'cuprum/cli/files/engines'
+require 'cuprum/cli/files/errors/missing_parameter'
 
-module Cuprum::Cli::Commands::File
+module Cuprum::Cli::Files::Engines
   # Utility command for generating file contents from an .erb template.
   class RenderErb < Cuprum::Command
     class RenderingContext < BasicObject; end
@@ -29,7 +29,7 @@ module Cuprum::Cli::Commands::File
       message = 'unable to render ERB template'
       message = "#{message} #{template_name}" if template_name
 
-      Cuprum::Cli::Errors::Files::TemplateError.new(message:, details:)
+      Cuprum::Cli::Files::Errors::TemplateError.new(message:, details:)
     end
 
     def empty_binding = RenderingContext.new.instance_exec { Kernel.binding }
@@ -50,7 +50,7 @@ module Cuprum::Cli::Commands::File
     end
 
     def missing_parameter_error(parameter_name)
-      Cuprum::Cli::Errors::Files::MissingParameter.new(
+      Cuprum::Cli::Files::Errors::MissingParameter.new(
         message:        'unable to render ERB template',
         parameter_name:,
         template_name:
@@ -79,7 +79,7 @@ module Cuprum::Cli::Commands::File
     end
 
     def template_error(message)
-      Cuprum::Cli::Errors::Files::TemplateError.new(
+      Cuprum::Cli::Files::Errors::TemplateError.new(
         message:       "unable to render ERB template - #{message}",
         template_name:
       )