revtree 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7c82aecb58c070a313c7d7e7897c7c038d66dfa35d717fae991eeeb19245f6f
-  data.tar.gz: 6ffc2b90332f026b0cd32c7f6daf7af377e28ced7c679633d6807416d1e9e1ff
+  metadata.gz: 3cfacc4513023ac62b90be3f9eed6fe2ab45af739aa6676413c947a214b7595f
+  data.tar.gz: cd7763aed7ca500ef2aaa1103d82e33667b9ad6d732839768b41100f3af435bb
 SHA512:
-  metadata.gz: b21ee3950eae8d1c09f2d42124d68653c0c21f1f4c0efe1e582d9444cb4bcc90620cb8778a7ed900aeba9f3beab85ca6cca45dfa596ec3f49f29240b7a33cb13
-  data.tar.gz: 2c0762cb314b65c1c14b8904cef4c18d0d434001193fe84d7f136fe9923de4cfa3bf73bcc253ce295dacb6ecb941479f8f84547fa3760c49006b305c31e720e0
+  metadata.gz: b723f8f00a74e68176bb3b9c60cfd09458cd0b67029ad903c76aee21a411394de498f04285fff7ae07436b35d2b55701e16a6f68fea1645c80acb1ebc6d1111d
+  data.tar.gz: c6d506353323eb333c849460132257f93abe1426c8fb8b3e6724c16499942409d99db0311c2e7ccd36da8bd401b8396e1689928ac3951b1aa9cc3fcff70a06fa

data/README.md

@@ -39,7 +39,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.1.gem
 ```
 
 ## API Documentation
@@ -107,7 +107,7 @@ end
 
 ## 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,7 +113,14 @@ 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)
@@ -90,6 +128,23 @@ class RevTree
 
   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 +153,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 +184,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 +197,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 +215,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 +250,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 +268,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 +283,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 +297,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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: revtree
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Julian Kahlert
@@ -10,6 +10,26 @@ bindir: bin
 cert_chain: []
 date: 2024-09-06 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