file_structure 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dae1876a15464dfd56776c428808812ccf15c3b8c8a3b95e75c2fe5da9d6421e
-  data.tar.gz: 4e2d794364f2c8c9ea6179f7b8f4807394e9c0757c1ea8d4c443dc9b508c8730
+  metadata.gz: 92b6133564fb1000278be3e8551eb8ce5b04ed9001de9ea61ce30e66141c4ea8
+  data.tar.gz: 17558a2b2874346b2b36a2ee308c4fdef02ac5fa0797389ede81129191cd0ecd
 SHA512:
-  metadata.gz: bd568fb6108962e88a0fa6f2300ed642e76f837d896f4d099f2250235e8f435f43168632d8b934be497090ef9c1ee2d2b3d9478b6fa49744c256aa6fefef7dfb
-  data.tar.gz: 78822356b462ca915d8f57b2e080781d8a0b6ade7811b2701857a35a6628076acf08e36a21754e525e9c6e70a96363ff895d428dc3c99ce79df836e2ea46a6a7
+  metadata.gz: 9e10b2ac0de13bff81acc8b7f7d7fb3d90b71dc0a524d59ede4c23b9e5f08faa09326d3d0ef8ba6443ef03b4338c973fd0f879d6d312735ddb99c8d3b8b5e2ab
+  data.tar.gz: b01504789e95ddf2d13a96a79e73395c05527b7e65a6d3b60733d0a616cd142ae5acaa3be2af19831d28102232ed852f66529b40523bd32277285b4c29627e6d

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+# Unreleased
+(nothing yet!)
+
+## [0.3.0] - 2022-09-09
+### Changed
+- `FileStructure#path_for` is more efficient and the API is simpler, expecting
+the argument to be a relative path instead of a list of recursive names.
+- `FileStructure#mount` does not handle cleaning "residuals" anymore and
+requires the target directory to be empty upon mounting.
+
+## [0.2.0] - 2022-03-05
+### Added
+- New DSL to more easily describe file structure (`FileStructure::DSL`).
+- New method `FileStructure.build` to use the DSL.
+### Fixed
+- Incorrect error handling preventing cleaning of residual files when `FileStructure#mount` fails.
+
+## [0.1.0] - 2022-02-26
+### Added
+- Initial working set of functionalities.
+
+[Unreleased]: https://github.com/durierem/file_structure/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/durierem/file_structure/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/durierem/file_structure/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/durierem/file_structure/releases/tag/v0.1.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    file_structure (0.2.0)
+    file_structure (0.3.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,5 +1,6 @@
 # file_structure
 
+[![MIT License](https://img.shields.io/github/license/durierem/file_structure)](https://github.com/durierem/file_structure/blob/main/LICENSE.txt)
 [![Gem Version](https://badge.fury.io/rb/file_structure.svg)](https://badge.fury.io/rb/file_structure)
 [![Test](https://github.com/durierem/file_structure/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/durierem/file_structure/actions/workflows/test.yml)
 [![Lint](https://github.com/durierem/file_structure/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/durierem/file_structure/actions/workflows/lint.yml)
@@ -10,7 +11,7 @@ Describe a file hierarchy and mount it in a directory on the file system.
 ## About
 
 This gem was extracted from another project tests for which structures
-containing files, directories and symlinks had to be easily reacreated on the
+containing files, directories and symlinks had to be easily recreated on the
 fly.
 
 Though it *is* useful in the context of testing, `file_structure` does not make
@@ -44,9 +45,9 @@ for more details.
 # /home/john/mydir
 # ├── dir1
 # │  ├── dir2
-# │  │  └── file2
+# │  │  └── file2 (containing "Hello, World!")
 # │  ├── file3
-# │  └── link_to_file2 -> /tmp/mydir/dir1/dir2/file2
+# │  └── link_to_file2 -> /home/john/mydir/dir1/dir2/file2
 # └── file1
 
 # Use the DSL to easily describe the structure
@@ -54,30 +55,39 @@ fs = FileStructure.build do
   file 'file1'
   directory 'dir1' do
     directory 'dir2' do
-      file 'file2'
+      file 'file2', content: 'Hello, World!'
     end
     file 'file3'
     symlink 'link_to_file2', to: 'file2'
   end
 end
 
-fs.mount('/home/john/mydir') # also creates the directory if it doesn't exist
-fs.mounted? # => true
-fs.mountpoint # => "/home/john/mydir"
-fs.path_for(:dir1, :file3) # => /home/john/mydir/dir1/file3
-fs.unmount # deletes all files in /home/john/mydir
+# Operations on file structures
+fs.mount('/home/john/mydir')    # also creates the directory if it doesn't exist
+fs.mounted?                     # => true
+fs.mountpoint                   # => "/home/john/mydir"
+fs.path_for('dir1/file3')       # => "/home/john/mydir/dir1/file3"
+fs.unmount                      # deletes all files in /home/john/mydir
+```
+
+## Bonus
 
-# Bonus tip 1: can be mounted in a temporary directory
+```ruby
+# Can be mounted in a temporary directory
 Dir.mktmpdir do |dirname|
-  fs.mount(dir)
+  fs.mount(dirname)
   # do stuff
   fs.unmount
 end
 
-# Bonus tip 2: easily serializable structure (who knows what could be done with this :O)
+# Easily serializable structure (who knows what could be done with this :O)
 JSON.dump(fs.structure)
 ```
 
+## Changelog
+
+See [CHANGELOG.md](https://github.com/durierem/file_structure/blob/main/CHANGELOG.md).
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/file_structure/dsl.rb

@@ -3,8 +3,6 @@
 class FileStructure
   # Provide a DSL to easily create file structure definitions.
   #
-  #
-  #
   # @example
   #   structure = FileStructure::DSL.eval do
   #     directory 'dir_a' do
@@ -18,7 +16,7 @@ class FileStructure
   #   end
   #   # => [{ type: :directory, name: 'dir_a', children: [ ... ] }]
   class DSL
-    # @return [Hash] the resulting file structure definition
+    # @return [Array] the resulting file structure definition
     attr_reader :structure
 
     # Return the file structure definition builded with the given block.

data/lib/file_structure/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class FileStructure
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/file_structure.rb

@@ -30,7 +30,7 @@ class FileStructure
     new(FileStructure::DSL.eval(&block))
   end
 
-  # @param structure [Array<Hash>] a valid file structure definition.
+  # @param structure [Array<Hash>] a valid file structure definition (see {DSL})
   # @raise [AssertionError] if the file structure is invalid
   def initialize(structure)
     assert(valid_file_structure?(structure), 'invalid file structure')
@@ -42,26 +42,26 @@ class FileStructure
   # Effectively creates files and directories in the specified directory.
   #
   # @param dirname [String] the target directory
-  # @raise [AssertionError] if the FileStructure is already mounted
+  # @raise [AssertionError] if the file structure is already mounted
+  # @raise [AssertionError] if the target directory is not empty
   # @return void
   # @see unmount
   def mount(dirname)
     assert(!mounted?, 'file structure is already mounted')
+    if Dir.exist?(dirname)
+      assert(Dir.empty?(dirname), 'target directory is not empty')
+    end
 
     mountpoint = File.absolute_path(dirname)
     FileUtils.mkdir_p(mountpoint) unless Dir.exist?(mountpoint)
-    begin
-      create_file_structure(mountpoint, @structure)
-    rescue StandardError => e
-      FileUtils.rm_r(Dir.glob("#{mountpoint}/*")) # clear residuals
-      raise e
-    end
+    create_file_structure(mountpoint, @structure)
     @mountpoint = mountpoint
   end
 
   # Remove all files from the mountpoint.
   #
   # @return void
+  # @raise [AssertionError] if the file structure is not mounted
   # @see mount
   def unmount
     assert(mounted?, 'file structure is not mounted')
@@ -70,26 +70,28 @@ class FileStructure
     @mountpoint = nil
   end
 
+  # Check if the file structure is currently mounted.
+  #
+  # @return [Boolean]
   def mounted?
     !!@mountpoint
   end
 
-  # Get the full path for a file in the mounted file structure.
+  # Get the absolute path for a file in the mounted file structure.
   #
   # @example
-  #   path_for(:foo, :bar, :file)
+  #   path_for('foo/bar/file')
   #   # => "/path/to/mountpoint/foo/bar/file"
   #
-  # @param args [Symbol, String Array<Symbol, String>] the recursive names to
-  #   the desired file or directory
-  # @return [String] the full path to the specified file/directory if found
-  # @return [nil] if no file/directory has been found
+  # @param target [String] the relative path of the target in the file structure
+  # @return [String] the full path to the target
+  # @return [nil] if no target has been found
   # @raise [AssertionError] if the file structure is not mounted
-  def path_for(*args)
+  def path_for(target)
     assert(mounted?, 'file structure is not mounted')
 
-    finder = [*args].flatten.map(&:to_sym)
-    build_path(finder, @structure)
+    absolute_path = File.join(@mountpoint, target)
+    File.exist?(absolute_path) ? absolute_path : nil
   end
 
   private
@@ -98,22 +100,6 @@ class FileStructure
     FileStructure::Validator.new(structure).valid?
   end
 
-  # @param finder [Array] such as :foo, :bar
-  # @param structure [Array] file structure definition
-  # @param path [String] starting path (recursive accumulator)
-  def build_path(finder, structure, path = @mountpoint)
-    return path if finder.empty? || structure.nil?
-
-    base = structure.find { |item| item[:name].to_s == finder.first.to_s }
-    return nil if base.nil?
-
-    build_path(
-      finder[1..],
-      base[:children],
-      File.join(path, base[:name])
-    )
-  end
-
   # @param dirname [String] root directory
   # @param structure [Array] file structure definition
   # @param symlinks [Hash<ref, path>] symlinks map (don't use directly)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: file_structure
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Rémi Durieu
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-03-05 00:00:00.000000000 Z
+date: 2022-09-09 00:00:00.000000000 Z
 dependencies: []
 description: Describe a file hierarchy and mount it in a directory on the file system.
 email:
@@ -19,6 +19,7 @@ extra_rdoc_files: []
 files:
 - ".rubocop.yml"
 - ".yardopts"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt