rflow-components-file 1.2.0 → 1.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b3fb18f29b55805334491346a6b5367fd9d2b0aa
-  data.tar.gz: 9d34329433db0a8bfe12ed2571407bcdcc60e087
+  metadata.gz: 445c9e66f4d8cd0990878daee9349741a9a2c957
+  data.tar.gz: 2ea84f5a1c971fbf5c5b2f803d5527a553cfc703
 SHA512:
-  metadata.gz: 7ca31d49b46b5cf32922db20d8cc3d2c9dfe11891c3805ddbebea19df4b0d08cb104918d1c2c3f468b2e0a6b8f03a5bb64022519078e46e9b3ae580d448962d3
-  data.tar.gz: 211b962929e93b7dd6f3147bad0336370e7ad653842dede1584d8005f7f2c0d3ab2fb13baf4447b4d443653a1d6ce9e77a3de89568230f374894d293decc02b6
+  metadata.gz: 85642e1fae29212da950b3607c2adabc08dc479353e1cdbdc60e01823260547fa377a0a733f21bbe60c9ab40689f29f7e4f7cc16b016a39be3d096c06a040746
+  data.tar.gz: fbeb8ca403c8a707a3e2cd683ad84c54b3d029c3d035071a78b532e3eb3b781d1eca13fdfea2988f9142a57f58eb3f0e0c78f250c547e03e3c40a744f49bb299

data/.gitignore

@@ -2,3 +2,5 @@
 .bundle
 Gemfile.lock
 pkg/*
+doc/
+.yardoc/

data/.yardopts

@@ -0,0 +1 @@
+--output ./doc --main README.md --files schema/*.avsc lib/**/*.rb - README.md LICENSE

data/Rakefile

@@ -1,6 +1,6 @@
 require 'bundler'
 require 'rspec/core/rake_task'
-require 'rdoc/task'
+require 'yard'
 Bundler::GemHelper.install_tasks
 
 RSpec::Core::RakeTask.new(:spec) do |t|
@@ -8,8 +8,4 @@ RSpec::Core::RakeTask.new(:spec) do |t|
   t.rspec_opts = '--tty --color'
 end
 
-Rake::RDocTask.new do |rd|
-  rd.main = "README.md"
-  rd.rdoc_files.include("README.md", "lib/**/*.rb")
-  rd.rdoc_dir = File.join('doc', 'html')
-end
+YARD::Rake::YardocTask.new

data/lib/rflow/components/file.rb

@@ -2,12 +2,17 @@ require 'rflow/components/file/extensions'
 require 'rflow/components/file/directory_watcher'
 require 'rflow/components/file/output_raw_to_files'
 
+# RFlow classes.
 class RFlow
+  # RFlow component classes.
   module Components
+    # File RFlow component classes.
     module File
       # Load the schemas
+      # @!visibility private
       SCHEMA_DIRECTORY = ::File.expand_path(::File.join(::File.dirname(__FILE__), '..', '..', '..', 'schema'))
 
+      # @!visibility private
       SCHEMA_FILES = {
         'file.avsc' => 'RFlow::Message::Data::File',
       }

data/lib/rflow/components/file/directory_watcher.rb

@@ -4,10 +4,31 @@ require 'digest/md5'
 class RFlow
   module Components
     module File
+      # Component that watches a directory for new files. When it does, it (optionally) deletes them
+      # and sends along +RFlow::Message+s of type {RFlow::Message::Data::File} and +RFlow::Message::Data::Raw+.
+      #
+      # Accepts config parameters:
+      # - +directory_path+ - the directory path to monitor
+      # - +file_name_glob+ - glob of filenames to monitor within +directory_path+
+      # - +poll_interval+ - how often, in seconds, to poll
+      # - +files_per_poll+ - maximum number of files to be brought in per poll
+      # - +remove_files+ - true to remove the files after they've been brought in
       class DirectoryWatcher < RFlow::Component
+        # @!attribute [r] file_port
+        #   Outputs +RFlow::Message+s of type {RFlow::Message::Data::File}
+        #   when detecting a new file in the directory.
+        #
+        #   @return [RFlow::Component::OutputPort]
         output_port :file_port
+        # @!attribute [r] raw_port
+        #   Outputs +RFlow::Message+s of type +RFlow::Message::Data::Raw+
+        #   when detecting a new file in the directory. The raw bytes are just
+        #   the contents of the file.
+        #
+        #   @return [RFlow::Component::OutputPort]
         output_port :raw_port
 
+        # Default config.
         DEFAULT_CONFIG = {
           'directory_path'  => '/tmp/import',
           'file_name_glob'  => '*',
@@ -16,8 +37,11 @@ class RFlow
           'remove_files'    => true,
         }
 
+        # @!visibility private
         attr_accessor :config, :poll_interval, :directory_path, :file_name_glob, :remove_files
 
+        # RFlow-called method at startup.
+        # @return [void]
         def configure!(config)
           @config = DEFAULT_CONFIG.merge config
           @directory_path  = ::File.expand_path(@config['directory_path'])
@@ -37,8 +61,10 @@ class RFlow
           # TODO: more error checking of input config
         end
 
-        # TODO: optimize sending of messages based on what is connected
+        # RFlow-called method at startup.
+        # @return [void]
         def run!
+          # TODO: optimize sending of messages based on what is connected
           timer = EventMachine::PeriodicTimer.new(poll_interval) do
             RFlow.logger.debug { "#{name}: Polling for files in #{::File.join(@directory_path, @file_name_glob)}" }
             file_paths = Dir.glob(::File.join(@directory_path, @file_name_glob)).
@@ -83,6 +109,7 @@ class RFlow
           end
         end
 
+        # @!visibility private
         def to_boolean(string)
           case string
           when /^true$/i, '1', true; true

data/lib/rflow/components/file/extensions.rb

@@ -1,9 +1,51 @@
 class RFlow
+  # @!parse
+  #   # Fake classes in this tree to document the actual message types.
+  #   class Message
+  #     # Fake classes in this tree to document the actual message types.
+  #     class Data
+  #       # A message representing a file on disk, including its contents. The file might no longer exist.
+  #       class File
+  #         # @!attribute path
+  #         #   The file's pathname.
+  #         #   @return [String]
+  #
+  #         # @!attribute size
+  #         #   The file's size.
+  #         #   @return [Integer]
+  #
+  #         # @!attribute content
+  #         #   The file's binary content.
+  #         #   @return [String]
+  #
+  #         # @!attribute creation_timestamp
+  #         #   The file's creation timestamp as an XML schema-compatible dateTime string.
+  #         #   @return [String]
+  #
+  #         # @!attribute modification_timestamp
+  #         #   The file's modification timestamp as an XML schema-compatible dateTime string.
+  #         #   @return [String]
+  #
+  #         # @!attribute access_timestamp
+  #         #   The file's access timestamp as an XML schema-compatible dateTime string.
+  #         #   @return [String]
+  #
+  #         # Just here to force Yard to create documentation.
+  #         # @!visibility private
+  #         def initialize; end
+  #       end
+  #     end
+  #   end
+
+  # RFlow component classes.
   module Components
     module File
+      # @!visibility private
       module Extensions
         # Need to be careful when extending to not clobber data already in data_object
+        # @!visibility private
         module FileExtension
+          # @!visibility private
           def self.extended(base_data)
             base_data.data_object ||= {
               'path' => '/', 'size' => 0, 'content' => '',

data/lib/rflow/components/file/output_raw_to_files.rb

@@ -6,10 +6,18 @@ require 'rflow/components/file/output_to_disk'
 class RFlow
   module Components
     module File
+      # Component that receives +RFlow::Message+s of type +RFlow::Message::Data::Raw+
+      # and writes new files to disk whose contents are the raw bytes of the message.
       class OutputRawToFiles < RFlow::Component
         include RFlow::Components::File::OutputToDisk
+
+        # Input port where +RFlow::Message+s of type +RFlow::Message::Data::Raw+ are
+        # received. When one is, a new file is written based on the message's properties.
+        # @return [RFlow::Component::InputPort]
         input_port :raw_port
 
+        # RFlow-called method when a message is received.
+        # @return [void]
         def process_message(input_port, input_port_key, connection, message)
           return unless message.data_type_name == 'RFlow::Message::Data::Raw'
           write_to_file(message.properties) {|file| file.write(message.data.raw) }

data/lib/rflow/components/file/output_to_disk.rb

@@ -3,15 +3,29 @@ require 'uuidtools'
 class RFlow
   module Components
     module File
+      # To be included into any component that plans to output files to disk.
+      # Provides default configuration and a {write_to_file} method.
+      #
+      # Best not to depend on the filename other than the prefix and suffix
+      # portions as it is implementation-dependent.
+      #
+      # Mixed-in component will support the following config parameters:
+      # - +directory_path+ - directory to write files into
+      # - +file_name_prefix+ - written files will always begin with this prefix
+      # - +file_name_suffix+ - written files will always end with this suffix
       module OutputToDisk
+        # Default config.
         DEFAULT_CONFIG = {
           'directory_path'  => '/tmp',
           'file_name_prefix' => 'output.',
           'file_name_suffix' => '.out',
         }
 
+        # @!visibility private
         attr_accessor :config, :directory_path, :file_name_prefix, :file_name_suffix
 
+        # RFlow-called method at startup.
+        # @return [void]
         def configure!(config)
           @config = DEFAULT_CONFIG.merge config
           @directory_path  = ::File.expand_path(@config['directory_path'])
@@ -29,7 +43,14 @@ class RFlow
           # TODO: more error checking of input config
         end
 
-        # if passed properties, will look for data_uuid property and use as suffix preamble
+        # Write out a file to disk based on message properties. Filename is implementation-dependent
+        # but will certainly contain the data UUID, priority, filename prefix, suffix, and a timestamp
+        # (properties +data_uuid+, +priority+ plus config variables).
+        #
+        # Opens the file and +yield+s it back to the caller for actual writing. Caller should return
+        # the number of bytes written.
+        #
+        # @return [String] the final output file path
         def write_to_file(properties)
           properties ||= {}
           begin

data/lib/rflow/components/file/version.rb

@@ -1,7 +1,8 @@
 class RFlow
   module Components
     module File
-      VERSION = "1.2.0"
+      # The gem version.
+      VERSION = "1.2.1"
     end
   end
 end

data/rflow-components-file.gemspec

@@ -27,4 +27,5 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'rspec', '~> 3.0'
   s.add_development_dependency 'rspec-collection_matchers', '~> 1.0'
   s.add_development_dependency 'rake', '>= 10.3'
+  s.add_development_dependency 'yard', '~> 0.9'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rflow-components-file
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.1
 platform: ruby
 authors:
 - Michael L. Artz
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-15 00:00:00.000000000 Z
+date: 2017-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rflow
@@ -66,6 +66,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '10.3'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: Components that operate on files for the RFlow FBP framework.  Also includes
   the File schema
 email:
@@ -79,6 +93,7 @@ files:
 - ".ruby-gemset"
 - ".ruby-version"
 - ".travis.yml"
+- ".yardopts"
 - Gemfile
 - LICENSE
 - README.md