revtree 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7c82aecb58c070a313c7d7e7897c7c038d66dfa35d717fae991eeeb19245f6f
-  data.tar.gz: 6ffc2b90332f026b0cd32c7f6daf7af377e28ced7c679633d6807416d1e9e1ff
+  metadata.gz: e1e3a7315f79eab2d444a7b708fa4412dc14fa0d17aff060848a74c4275eefcc
+  data.tar.gz: 712bbd90a68a4cd071c1bd647cb9c36752aa01c0c0122cff32d585895695bd1f
 SHA512:
-  metadata.gz: b21ee3950eae8d1c09f2d42124d68653c0c21f1f4c0efe1e582d9444cb4bcc90620cb8778a7ed900aeba9f3beab85ca6cca45dfa596ec3f49f29240b7a33cb13
-  data.tar.gz: 2c0762cb314b65c1c14b8904cef4c18d0d434001193fe84d7f136fe9923de4cfa3bf73bcc253ce295dacb6ecb941479f8f84547fa3760c49006b305c31e720e0
+  metadata.gz: abeccda61e8bd8afbdc553550d43a22e786e20e57e0563f2d3e64e8accf2b67152cfc449b9417a8f10ecc3acf9bd58be2a6cde8402d1d0709586368b3f34054b
+  data.tar.gz: a90318c8711df1e9ce50d0fde521c7713e4923316be3e5f65e18a73489fbb76a3b9563651a2031f5ba69e19c11f511eeb713f2700e85c64a13cb22817ed5f2f1

data/README.md

@@ -14,6 +14,8 @@ It also provides methods to print and serialize the tree structure, as well as t
 - **Serialization**: Supports serialization to and from JSON format for easy storage and transfer.
 - **Pretty Printing**: Provides a method to print the directory tree with statuses.
 - **Iterate with `for_each`**: Traverse the tree and apply a block to files matching specific statuses.
+- **Watch for Changes**: Automatically monitors a directory for changes with `watch`, and triggers actions based on file changes.
+- **Customizable Watch Interval**: Set a custom interval between checks with the `with_interval` method.
 
 ## Install
 
@@ -39,7 +41,7 @@ sudo make install
 git clone https://github.com/juliankahlert/revtree.git
 cd revtree
 gem build revtree.gemspec
-sudo gem install --local revtree-0.1.0.gem
+sudo gem install --local revtree-0.1.2.gem
 ```
 
 ## API Documentation
@@ -70,6 +72,18 @@ sudo gem install --local revtree-0.1.0.gem
   - `&block` (Proc): A block to execute for each file matching the given statuses.
 - **Behavior**: Iterates over files in the tree, executing the block for each file whose status matches one of the statuses in the whitelist.
 
+### `#watch(status_whitelist = [:modified, :added, :removed], &block)`
+
+- **Parameters**:
+  - `status_whitelist` (Array<Symbol>): List of statuses to watch (e.g., `[:added, :removed]`).
+  - `&block` (Proc): A block to execute when a file matching the given statuses is changed.
+
+### `#with_interval(interval)`
+
+- **Parameters**:
+  - `interval` (Integer): Interval (in seconds) between checks for changes.
+- **Returns**: The `RevTree` instance, enabling method chaining.
+
 ### `RevTree.from_h(h)`
 
 - **Parameters**:
@@ -84,6 +98,8 @@ sudo gem install --local revtree-0.1.0.gem
 
 ## Example Usage
 
+### Comparing two directory structures
+
 ```ruby
 #!/bin/env ruby
 
@@ -105,9 +121,27 @@ result_tree.for_each([:added, :removed]) do |file, full_path|
 end
 ```
 
+### Watching a directory for changes
+
+```ruby
+#!/bin/env ruby
+
+require 'revtree'
+
+# Create a RevTree for the current directory, including only .rb and .md files
+file_tree = RevTree.new('./', ['*.rb', '*.md'])
+
+# Watch for changes in the directory
+file_tree.with_interval(10).watch([:modified, :added, :removed]) do |file, full_path|
+  puts "File #{file.name} #{file.status} in #{full_path}"
+end
+```
+
+This second example demonstrates the `watch` method, which continuously monitors the directory tree for changes and triggers a block of code when changes (additions, modifications, or deletions) are detected. The `with_interval` method customizes the time between checks.
+
 ## Encouragement for Contribution
 
-Vontributions from the community are welcome!
+Contributions from the community are welcome!
 If you find any issues or have ideas for new features, please feel free to submit a pull request or open an issue.
 Your input helps make RevTree better for everyone.
 

data/lib/revtree.rb

@@ -26,9 +26,31 @@ require 'digest'
 require 'pathname'
 require 'json'
 
+# The `RevTree` class provides a tree structure representing file directories and
+# files, allowing for version tracking based on MD5 hashes.
+#
+# This class can traverse directories, compare versions of trees, and serialize/deserialize
+# itself to/from JSON.
 class RevTree
-  attr_reader :children, :type, :name, :rev, :status
+  # @return [Array<RevTree>] the list of children in the tree (empty for files)
+  attr_reader :children
+
+  # @return [Symbol] the type of the node (:folder or :file)
+  attr_reader :type
+
+  # @return [String] the name of the file or directory
+  attr_reader :name
+
+  # @return [String] the revision (MD5 hash) of the file or directory
+  attr_reader :rev
 
+  # @return [Symbol] the status of the file or directory (:unmodified, :modified, :added, :removed)
+  attr_reader :status
+
+  # Initializes a new `RevTree` object representing a directory or file.
+  #
+  # @param path [String, Pathname] the path to the file or directory
+  # @param whitelist [Array<String>, nil] a list of file patterns to include (optional)
   def initialize(path, whitelist = nil)
     @path = Pathname.new(path)
     @name = @path.basename.to_s
@@ -42,21 +64,19 @@ class RevTree
     end
   end
 
-  def calculate_file_rev
-    Digest::MD5.file(@path).hexdigest
-  end
-
-  def calculate_directory_rev
-    Digest::MD5.hexdigest(@children.map(&:rev).join)
-  end
-
+  # Prints the tree structure, including file names and statuses, to the console.
+  #
+  # @param indent [Integer] the indentation level (default: 0)
+  # @return [void]
   def print_tree(indent = 0)
     status_str = @status ? " (status: #{@status})" : ''
     puts "#{'  ' * indent}#{@type == :folder ? '[Folder]' : '[File]'} #{@name} (rev: #{@rev})#{status_str}"
     @children.each { |child| child.print_tree(indent + 1) }
   end
 
-  # Serialize the RevTree object to JSON
+  # Serializes the `RevTree` object to a hash.
+  #
+  # @return [Hash] a hash representing the object
   def to_h
     {
       type: @type,
@@ -67,14 +87,25 @@ class RevTree
     }
   end
 
-  def to_json(*_args)
+  # Converts the `RevTree` object to JSON format.
+  #
+  # @return [String] a JSON string representing the object
+  def to_json
     JSON.pretty_generate(self.to_h)
   end
 
+  # Reconstructs a `RevTree` object from a hash.
+  #
+  # @param h [Hash] the hash to deserialize
+  # @return [RevTree] the reconstructed `RevTree` object
   def self.from_h(h)
     new_tree(h[:name], h[:type].to_sym, h[:rev], h[:children], h[:status])
   end
 
+  # Reconstructs a `RevTree` object from a JSON string.
+  #
+  # @param json_str [String] the JSON string to deserialize
+  # @return [RevTree] the reconstructed `RevTree` object
   def self.from_json(json_str)
     data = JSON.parse(json_str, symbolize_names: true)
     file_tree = from_h(data)
@@ -82,14 +113,79 @@ class RevTree
     file_tree
   end
 
-  def for_each(status_whitelist, &block)
+  # Executes a block of code for each file matching the provided status whitelist.
+  #
+  # @param status_whitelist [Array<Symbol>] the list of statuses to match (:added, :modified, etc.)
+  # @yield [node, full_path] the block to be executed for each matching file
+  # @yieldparam node [RevTree] the current node being traversed
+  # @yieldparam full_path [String] the full path of the current node
+  # @return [void]
+  def for_each(status_whitelist = [:unmodified, :modified, :added, :removed], &block)
     return unless block_given?
 
     RevTree.traverse_tree(self, status_whitelist, @path, &block)
   end
 
+  # Watches the tree for changes
+  #
+  # Compares the refreshed tree to its last version and calls the provided block
+  # for each node that matches the statuses in the `status_whitelist`.
+  #
+  # @param status_whitelist [Array<Symbol>] the list of statuses to match (:added, :modified, etc.)
+  # @yield [node, full_path] the block to be executed for each matching file
+  # @yieldparam node [RevTree] the node that was changed
+  # @yieldparam full_path [String] the full path of the node
+  # @return [void]
+  def watch(status_whitelist = [:modified, :added, :removed], &block)
+    current_tree = self
+    @interval ||= 5
+
+    Signal.trap('INT') { exit }
+    Signal.trap('TERM') { exit }
+    loop do
+      sleep @interval
+
+      new_tree = RevTree.new(@path, @whitelist)
+      diff_tree = RevTree.compare(current_tree, new_tree)
+
+      next if diff_tree.nil?
+
+      diff_tree.for_each(status_whitelist) do |node, full_path|
+        block.call(node, full_path)
+      end
+
+      current_tree = new_tree
+    end
+  end
+
+  # Sets the interval for the watch method's sleep duration.
+  #
+  # @param interval [Integer] the number of seconds to sleep between checks
+  # @return [RevTree] the current instance for chaining
+  def with_interval(interval)
+    @interval = interval
+    self
+  end
+
   private
 
+  # Calculates the MD5 hash for the file.
+  #
+  # @return [String] the MD5 hash of the file
+  def calculate_file_rev
+    Digest::MD5.file(@path).hexdigest
+  end
+
+  # Calculates the MD5 hash for the directory based on its children.
+  #
+  # @return [String] the MD5 hash of the directory
+  def calculate_directory_rev
+    Digest::MD5.hexdigest(@children.map(&:rev).join)
+  end
+
+  # Initializes the directory node by traversing its children.
+  #
+  # @return [void]
   def init_dir
     @type = :folder
     @children = @path.children
@@ -98,12 +194,23 @@ class RevTree
     @rev = calculate_directory_rev
   end
 
+  # Initializes the file node by calculating its revision.
+  #
+  # @return [void]
   def init_file
     @type = :file
     @children = []
     @rev = calculate_file_rev
   end
 
+  # Rebuilds a `RevTree` from its serialized components.
+  #
+  # @param name [String] the name of the node
+  # @param type [Symbol] the type of the node (:folder or :file)
+  # @param rev [String] the revision hash of the node
+  # @param children [Array<Hash>] the child nodes (if any)
+  # @param status [Symbol] the status of the node (:unmodified, :modified, etc.)
+  # @return [RevTree] the reconstructed tree
   def self.new_tree(name, type, rev, children, status = :unmodified)
     tree = allocate
     tree.instance_variable_set(:@name, name)
@@ -118,6 +225,10 @@ class RevTree
     tree
   end
 
+  # Determines whether a file or directory should be included in the tree.
+  #
+  # @param path [Pathname] the path to the file or directory
+  # @return [Boolean] `true` if the path should be included, `false` otherwise
   def include_in_tree?(path)
     return false if path.directory? && path.basename.to_s.start_with?('.')
 
@@ -127,6 +238,11 @@ class RevTree
     @whitelist.any? { |p| File.fnmatch?(p, path.basename.to_s) }
   end
 
+  # Compares two `RevTree` nodes (old and new) and returns a tree with appropriate status.
+  #
+  # @param old [RevTree, nil] the old version of the tree
+  # @param new [RevTree, nil] the new version of the tree
+  # @return [RevTree, nil] the resulting tree with status updates or `nil`
   def self.compare(old, new)
     return nil if old.nil? && new.nil?
 
@@ -140,18 +256,31 @@ class RevTree
     end
   end
 
+  # Handles the addition of a new node.
+  #
+  # @param new [RevTree] the new node
+  # @return [RevTree] the node with the status set to `:added`
   def self.handle_addition(new)
     with_status = new.dup
     with_status.instance_variable_set(:@status, :added)
     with_status
   end
 
+  # Handles the removal of an old node.
+  #
+  # @param old [RevTree] the old node
+  # @return [RevTree] the node with the status set to `:removed`
   def self.handle_removal(old)
     with_status = old.dup
     with_status.instance_variable_set(:@status, :removed)
     with_status
   end
 
+  # Handles the modification of a node.
+  #
+  # @param old [RevTree] the old node
+  # @param new [RevTree] the new node
+  # @return [RevTree] the node with the status set to `:modified`
   def self.handle_modification(old, new)
     if old.type == :folder && new.type == :folder
       compare_folders(old, new, :modified)
@@ -162,6 +291,12 @@ class RevTree
     end
   end
 
+  # Compares two folder nodes and returns a merged node with status updates.
+  #
+  # @param old [RevTree] the old folder node
+  # @param new [RevTree] the new folder node
+  # @param status [Symbol] the status to apply (:modified or :unmodified)
+  # @return [RevTree] the resulting folder node with status updates
   def self.compare_folders(old, new, status)
     combined_children = merge_children(old.children, new.children)
     with_status = new.dup
@@ -174,6 +309,11 @@ class RevTree
     with_status
   end
 
+  # Handles the unmodified status of a node.
+  #
+  # @param old [RevTree] the old node
+  # @param new [RevTree] the new node
+  # @return [RevTree] the node with the status set to `:unmodified`
   def self.handle_unmodified(old, new)
     if old.type == :folder && new.type == :folder
       compare_folders(old, new, :unmodified)
@@ -184,6 +324,11 @@ class RevTree
     end
   end
 
+  # Merges the children of two nodes.
+  #
+  # @param old_children [Array<RevTree>] the children of the old node
+  # @param new_children [Array<RevTree>] the children of the new node
+  # @return [Array<Array<RevTree, RevTree>>] an array of paired old and new children
   def self.merge_children(old_children, new_children)
     all_names = (old_children.map(&:name) + new_children.map(&:name)).uniq
     all_names.map do |name|
@@ -193,6 +338,15 @@ class RevTree
     end
   end
 
+  # Traverses the tree and executes a block for each file matching the provided status whitelist.
+  #
+  # @param node [RevTree] the current node being traversed
+  # @param status_whitelist [Array<Symbol>] the list of statuses to match
+  # @param current_path [Pathname] the current path
+  # @yield [node, full_path] the block to be executed for each matching file
+  # @yieldparam node [RevTree] the current node being traversed
+  # @yieldparam full_path [String] the full path of the current node
+  # @return [void]
   def self.traverse_tree(node, status_whitelist, current_path, &block)
     if node.type == :file && status_whitelist.include?(node.status)
       block.call(node, File.expand_path(current_path.to_s))

metadata

@@ -1,15 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: revtree
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Julian Kahlert
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-09-06 00:00:00.000000000 Z
+date: 2024-09-07 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.37
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.37
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -31,7 +51,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.4'
 description: RevTree builds a recursive directory tree and compares file revisions.
-  It can mark files and folders as added, removed, modified, or unmodified.
+  It can mark files and folders as added, removed, modified, or unmodified. For convenience,
+  RevTree also allows you to watch for changes in a directory tree.
 email:
 - 90937526+juliankahlert@users.noreply.github.com
 executables: []
@@ -43,7 +64,9 @@ files:
 homepage: https://github.com/juliankahlert/revtree
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/juliankahlert/revtree
+  source_code_uri: https://github.com/juliankahlert/revtree
 post_install_message: 
 rdoc_options: []
 require_paths: