file_structure 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0896ec610bd688790fad3b0f995766076ffee13148ff16ee3f9e9ae7a646b34
-  data.tar.gz: e3a445ce085c12d7a7971dbed9469b48247d0a130fdb91acb2b28696f84d9a62
+  metadata.gz: dae1876a15464dfd56776c428808812ccf15c3b8c8a3b95e75c2fe5da9d6421e
+  data.tar.gz: 4e2d794364f2c8c9ea6179f7b8f4807394e9c0757c1ea8d4c443dc9b508c8730
 SHA512:
-  metadata.gz: 48cd8e05e96096a21265e5c3e69f7bc5bb2bf11e5094984006f938dc79fd186fcbe8ac9f97d31d11a431db756f940780741924abdac37fccdc555e51bba75f6a
-  data.tar.gz: c12c1441fd3dc451fdbe179bec7c4b0a90f8f473990de86273b9200db757aa75f173a12b35b7c071e5ccb1642b55c58aff5554666549cdafc95ba147dde4e2ee
+  metadata.gz: bd568fb6108962e88a0fa6f2300ed642e76f837d896f4d099f2250235e8f435f43168632d8b934be497090ef9c1ee2d2b3d9478b6fa49744c256aa6fefef7dfb
+  data.tar.gz: 78822356b462ca915d8f57b2e080781d8a0b6ade7811b2701857a35a6628076acf08e36a21754e525e9c6e70a96363ff895d428dc3c99ce79df836e2ea46a6a7

data/.rubocop.yml

@@ -34,6 +34,10 @@ Metrics/BlockLength:
     - file_structure.gemspec
     - test/**/test_*.rb
 
+Metrics/ClassLength:
+  Exclude:
+    - test/**/test_*.rb
+
 Metrics/MethodLength:
   Max: 15 # default: 10
 

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/Gemfile

@@ -2,7 +2,6 @@
 
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in file_structure.gemspec
 gemspec
 
 group :development do
@@ -17,6 +16,7 @@ end
 group :test do
   gem 'minitest', '~> 5.0'
   gem 'minitest-reporters', '~> 1.5'
+  gem 'simplecov', '~> 0.21.2', require: false
 end
 
 group :development, :test do

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    file_structure (0.1.0)
+    file_structure (0.2.0)
 
 GEM
   remote: https://rubygems.org/
@@ -12,6 +12,7 @@ GEM
     debug (1.4.0)
       irb (>= 1.3.6)
       reline (>= 0.2.7)
+    docile (1.4.0)
     io-console (0.5.11)
     irb (1.4.1)
       reline (>= 0.3.0)
@@ -49,6 +50,12 @@ GEM
     rubocop-rake (0.6.0)
       rubocop (~> 1.0)
     ruby-progressbar (1.11.0)
+    simplecov (0.21.2)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
     unicode-display_width (2.1.0)
     webrick (1.7.0)
     yard (0.9.27)
@@ -67,6 +74,7 @@ DEPENDENCIES
   rubocop-minitest (~> 0.17.2)
   rubocop-performance (~> 1.13)
   rubocop-rake (~> 0.6.0)
+  simplecov (~> 0.21.2)
   yard (~> 0.9.27)
 
 BUNDLED WITH

data/README.md

@@ -1,20 +1,47 @@
 # file_structure
 
+[![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)
 
-Define a file structure with a `Hash` with support for files, file content,
-directories and symlinks across the structure. Mount and unmount the structure
-in a directory on the file system.
 
-Useful for creating test environment for programs that manipulate
-files but can be used as is for something else entirely.
+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
+fly.
+
+Though it *is* useful in the context of testing, `file_structure` does not make
+assumptions about what it is being used for and deliberately does not handle
+things such as temporary file structures or mock file structures.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'file_structure'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install file_structure
+
 
 ## Usage
 
+Visit the [API documentation](https://www.rubydoc.info/github/durierem/file_structure/)
+for more details.
+
 ```ruby
 # Example creating the following file hierarchy:
-# /tmp/mydir
+# /home/john/mydir
 # ├── dir1
 # │  ├── dir2
 # │  │  └── file2
@@ -22,31 +49,33 @@ files but can be used as is for something else entirely.
 # │  └── link_to_file2 -> /tmp/mydir/dir1/dir2/file2
 # └── file1
 
-fs = FileStructure.new([
-  { type: :file, name: 'file1' },
-  {
-    type: :directory,
-    name: 'dir1',
-    children: [
-      {
-        type: :directory,
-        name: 'dir2',
-        children: [
-          { type: :file, name: 'file2', ref: 'ref_file2', content: 'abc' }
-        ]
-      },
-      { type: :file, name: 'file3' },
-      { type: :symlink, name: 'link_to_file2', to: 'ref_file2' }
-    ]
-  }
-])
-
-fs.mount('/tmp/mydir') # also creates the /tmp/mydir directory if it doesn't exist
+# Use the DSL to easily describe the structure
+fs = FileStructure.build do
+  file 'file1'
+  directory 'dir1' do
+    directory 'dir2' do
+      file 'file2'
+    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 # => "/tmp/mydir"
-fs.unmount # deletes all files in /tmp/mydir
+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 tip 1: can be mounted in a temporary directory
+Dir.mktmpdir do |dirname|
+  fs.mount(dir)
+  # do stuff
+  fs.unmount
+end
 
-JSON.dump(fs.structure) # (bonus) easily serializable :D
+# Bonus tip 2: easily serializable structure (who knows what could be done with this :O)
+JSON.dump(fs.structure)
 ```
 
 ## License

data/Rakefile

@@ -14,7 +14,7 @@ RuboCop::RakeTask.new
 
 desc 'Generate documentation with Yard'
 task :doc do
-  sh 'yard doc --no-private'
+  sh 'yard doc'
 end
 
 task default: %i[test rubocop doc]

data/file_structure.gemspec

@@ -9,23 +9,16 @@ Gem::Specification.new do |spec|
   spec.email = ['mail@remidurieu.dev']
 
   spec.summary = <<-TEXT
-    Manage file structures (ie: files and directories) on the file system.
-  TEXT
-  spec.description = <<-TEXT
-    Describe a file structure with a Ruby Hash. Supports files, file content,
-    directories and symlinks across the structure.
-
-    Mount and unmount the desired structured in a directory on the file system.
-
-    Useful for creating test environment for programs that manipulate
-    files but can be used as is for something else entirely.
+    Describe a file hierarchy and mount it in a directory on the file system.
   TEXT
+  spec.description = spec.summary
   spec.homepage = 'https://github.com/durierem/file_structure'
   spec.license = 'MIT'
   spec.required_ruby_version = '>= 2.6.0'
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['documentation_uri'] = 'https://www.rubydoc.info/github/durierem/file_structure/'
 
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject do |f|

data/lib/file_structure/dsl.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+class FileStructure
+  # Provide a DSL to easily create file structure definitions.
+  #
+  #
+  #
+  # @example
+  #   structure = FileStructure::DSL.eval do
+  #     directory 'dir_a' do
+  #       file 'file_a'
+  #       symlink 'point_to_file_c', to: 'file_c_ref'
+  #       directory 'dir_b' do
+  #         file 'file_b'
+  #         file 'file_c', ref: 'file_c_ref'
+  #       end
+  #     end
+  #   end
+  #   # => [{ type: :directory, name: 'dir_a', children: [ ... ] }]
+  class DSL
+    # @return [Hash] the resulting file structure definition
+    attr_reader :structure
+
+    # Return the file structure definition builded with the given block.
+    #
+    # @see structure
+    def self.eval(&block)
+      dsl = new
+      dsl.instance_eval(&block)
+      dsl.structure
+    end
+
+    def initialize
+      @structure = []
+    end
+
+    # Add a file definition to the parent structure.
+    #
+    # @param name     [String]  the name of the file
+    # @param content  [String]  the content of the file
+    # @param ref      [String]  the reference to use for symlinks
+    # @return         [Hash]    the created file definition
+    def file(name, content: nil, ref: name)
+      file = { type: :file, name: name }
+      file[:content] = content if content
+      file[:ref] = ref
+      @structure << file and return file
+    end
+
+    # Add a symlink to the parent structure.
+    #
+    # @param name [String]  the name of the symlink
+    # @param to   [String]  the reference of the file to point to
+    # @return     [Hash]    the created symlink definition
+    def symlink(name, to:)
+      symlink = { type: :symlink, name: name, to: to }
+      @structure << symlink and return symlink
+    end
+
+    # Add a directory to the parent structure.
+    #
+    # @param name [String]  the name of the directory
+    # @param ref  [String]  the reference to use for symlinks
+    # @return     [Hash]    the created directory definition
+    def directory(name, ref: name, &block)
+      dsl = self.class.new
+      dsl.instance_eval(&block)
+      children = dsl.structure
+      directory = {
+        type: :directory,
+        name: name,
+        children: children,
+        ref: ref
+      }
+      @structure << directory and return directory
+    end
+  end
+end

data/lib/file_structure/version.rb

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

data/lib/file_structure.rb

@@ -2,26 +2,38 @@
 
 require 'fileutils'
 require_relative 'file_structure/contract'
+require_relative 'file_structure/dsl'
 require_relative 'file_structure/validator'
 require_relative 'file_structure/version'
 
-# Manage files, directories and links described with a file structure
-# definition as a Ruby Hash. A valid file structure definition is an Array
-# of Hashes with the following possible file definitions:
-#
-# rubocop:disable Layout/LineLength
-# @example
-#   { name: 'myfile', type: :file, content: 'abc', ref: 'fileref'} # :content and :ref are optional
-#   { name: 'mydir' type: :directory, children: [<another valid file structure definition>], ref: 'dirref' } # :ref is optional
-#   { name: 'mylink', type: :link, to: 'fileref' } # link to 'myfile' refereced earlier by 'fileref'
-# rubocop:enable Layout/LineLength
 class FileStructure
-  attr_reader :structure, :mountpoint
+  include Contract
+
+  # @return [Hash] the file structure definition
+  attr_reader :structure
+
+  # @return [String, nil] the current mountpoint
+  attr_reader :mountpoint
+
+  # Build a new {FileStructure} using the {FileStructure::DSL}.
+  #
+  # @example
+  #   FileStructure.build do
+  #     dir 'foo' do
+  #       file 'bar'
+  #     end
+  #   end
+  #
+  # @see FileStructure::DSL
+  # @return [FileStructure]
+  def self.build(&block)
+    new(FileStructure::DSL.eval(&block))
+  end
 
   # @param structure [Array<Hash>] a valid file structure definition.
   # @raise [AssertionError] if the file structure is invalid
   def initialize(structure)
-    Contract.assert(valid_file_structure?(structure), 'invalid file structure')
+    assert(valid_file_structure?(structure), 'invalid file structure')
 
     @structure = structure
     @mountpoint = nil
@@ -34,13 +46,13 @@ class FileStructure
   # @return void
   # @see unmount
   def mount(dirname)
-    Contract.assert(!mounted?, 'file structure is already mounted')
+    assert(!mounted?, 'file structure is already mounted')
 
     mountpoint = File.absolute_path(dirname)
     FileUtils.mkdir_p(mountpoint) unless Dir.exist?(mountpoint)
     begin
       create_file_structure(mountpoint, @structure)
-    rescue StandardErrror => e
+    rescue StandardError => e
       FileUtils.rm_r(Dir.glob("#{mountpoint}/*")) # clear residuals
       raise e
     end
@@ -52,7 +64,7 @@ class FileStructure
   # @return void
   # @see mount
   def unmount
-    Contract.assert(mounted?, 'file structure is not mounted')
+    assert(mounted?, 'file structure is not mounted')
 
     FileUtils.rm_r(Dir.glob("#{@mountpoint}/*"))
     @mountpoint = nil
@@ -70,10 +82,11 @@ class FileStructure
   #
   # @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
+  # @return [String] the full path to the specified file/directory if found
+  # @return [nil] if no file/directory has been found
   # @raise [AssertionError] if the file structure is not mounted
   def path_for(*args)
-    Contract.assert(mounted?, 'file structure is not mounted')
+    assert(mounted?, 'file structure is not mounted')
 
     finder = [*args].flatten.map(&:to_sym)
     build_path(finder, @structure)
@@ -103,14 +116,16 @@ class FileStructure
 
   # @param dirname [String] root directory
   # @param structure [Array] file structure definition
-  # @param symlinks [Hash] current symlinks refs (recursive accumulator)
-  def create_file_structure(dirname, structure, symlinks = {})
+  # @param symlinks [Hash<ref, path>] symlinks map (don't use directly)
+  # @return void
+  def create_file_structure(dirname, structure, symlinks = nil)
+    symlinks = extract_symlinks_map(dirname, structure) if symlinks.nil?
+
     structure.each do |element|
       path = File.join(File.absolute_path(dirname), element[:name])
       case element[:type]
       when :file
         File.write(path, element[:content])
-        symlinks.merge!(element[:ref] => path) if element[:ref]
       when :symlink
         FileUtils.symlink(symlinks[element[:to]], path)
       when :directory
@@ -119,4 +134,22 @@ class FileStructure
       end
     end
   end
+
+  # @param dirname [String] root directory
+  # @param structure [Array] file structure definition
+  # @param result [Hash] recursive accumulator (don't use directly)
+  # @return [Hash<ref, path>] the resulting symlinks map
+  def extract_symlinks_map(dirname, structure, result = {})
+    structure.each do |element|
+      next unless element[:ref]
+
+      path = File.join(File.absolute_path(dirname), element[:name])
+      result[element[:ref]] = path
+
+      next unless element[:type] == :directory
+
+      extract_symlinks_map(dirname, element[:children], result)
+    end
+    result
+  end
 end

metadata

@@ -1,23 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: file_structure
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Rémi Durieu
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-02-26 00:00:00.000000000 Z
+date: 2022-03-05 00:00:00.000000000 Z
 dependencies: []
-description: |2
-      Describe a file structure with a Ruby Hash. Supports files, file content,
-      directories and symlinks across the structure.
-
-      Mount and unmount the desired structured in a directory on the file system.
-
-      Useful for creating test environment for programs that manipulate
-      files but can be used as is for something else entirely.
+description: Describe a file hierarchy and mount it in a directory on the file system.
 email:
 - mail@remidurieu.dev
 executables: []
@@ -25,6 +18,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rubocop.yml"
+- ".yardopts"
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -33,6 +27,7 @@ files:
 - file_structure.gemspec
 - lib/file_structure.rb
 - lib/file_structure/contract.rb
+- lib/file_structure/dsl.rb
 - lib/file_structure/validator.rb
 - lib/file_structure/version.rb
 homepage: https://github.com/durierem/file_structure
@@ -41,6 +36,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/durierem/file_structure
   source_code_uri: https://github.com/durierem/file_structure
+  documentation_uri: https://www.rubydoc.info/github/durierem/file_structure/
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
@@ -60,5 +56,5 @@ requirements: []
 rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
-summary: 'Manage file structures (ie: files and directories) on the file system.'
+summary: Describe a file hierarchy and mount it in a directory on the file system.
 test_files: []