imw 0.1.1 → 0.2.0

data/lib/imw/resources/formats/json.rb

@@ -0,0 +1,53 @@
+module IMW
+  module Resources
+    module Formats
+
+      # Defines methods for reading and writing JSON data.
+      module Json
+
+        # Return the content of this resource.
+        #
+        # Will try to be smart about iterating over the data when
+        # passed a block.
+        #
+        # - if the outermost JSON data structure is an array, then
+        #   yield each element
+        #
+        # - if the outermost JSON data structure is a mapping, then
+        #   yield each key, value pair
+        #
+        # - otherwise just yield the structure
+        #
+        # @return [Hash, Array, String, Fixnum] whatever the JSON contained
+        def load &block
+          require 'json'
+          json = JSON.parse(read)
+          if block_given?
+            case json
+            when Array
+              json.each      { |obj| yield obj }
+            when Hash
+              json.each_pair { |key, value| yield key, value }
+            else
+              yield json
+            end
+          else
+            json
+          end
+        end
+
+        # Dump the +data+ into this resource.  It must be opened for
+        # writing.
+        #
+        # @param [Hash, String, Array, Fixnum] data the Ruby object to dump
+        # @option options [true, false] :persist (false) Don't close the IO object after writing
+        def dump data, options={}
+          require 'json'
+          write(data.to_json)
+          io.close unless options[:persist]
+          self
+        end
+      end
+    end
+  end
+end

data/lib/imw/resources/formats/sgml.rb

@@ -0,0 +1,72 @@
+module IMW
+  module Resources
+    module Formats
+
+      # Defines methods to parse SGML-derived data formats (XML, HTML,
+      # &c.).  This module isn't directly used to extend resources.
+      # Instead, more specific modules (e.g. -
+      # IMW::Resources::Formats::Xml) are used.
+      module Sgml
+
+        # Parse this resource using Hpricot and return (or yield if
+        # given a block) the resulting Hpricot::Doc.
+        #
+        # @return [Hpricot::Doc]
+        # @yield [Hpricot::Doc]
+        def load &block
+          require 'hpricot'
+          sgml = Hpricot(io)
+          if block_given?
+            yield sgml
+          else
+            sgml
+          end
+        end
+
+        # Parse the Hpricot::Doc of this resource with the given
+        # +parser+.
+        #
+        # The parser can either be an IMW::Parsers::HtmlParser or a
+        # hash which will be used to build such a parser.  See the
+        # documentation for IMW::Parsers::HtmlParser for more
+        # information.
+        #
+        # @param [Hash, IMW::Parsers::HtmlParser] parser
+        # @return [Hash] the parser's output
+        def parse parser
+          if parser.is_a?(IMW::Parsers::HtmlParser)
+            parser.parse(load)
+          else
+            IMW::Parsers::HtmlParser.new(parser).parse(load)
+          end
+        end
+      end
+
+      # Defines methods for XML data.
+      module Xml
+        include Sgml
+      end
+
+      # Defines methods for XSL data.
+      module Xsl
+        include Sgml
+      end
+
+      # Defines methods for XHTML data.
+      module Xhtml
+        include Sgml
+      end
+
+      # Defines methods for HTML data.
+      module Html
+        include Sgml
+      end
+
+      # Defines methods for RDF data.
+      module Rdf
+        include Sgml
+      end
+    end
+  end
+end
+

data/lib/imw/resources/formats/yaml.rb

@@ -0,0 +1,53 @@
+module IMW
+  module Resources
+    module Formats
+
+      # Provides methods for reading and writing YAML data.
+      module Yaml
+
+        # Return the content of this resource.
+        #
+        # Will try to be smart about iterating over the data when
+        # passed a block.
+        #
+        # - if the outermost YAML data structure is an array, then
+        #   yield each element
+        #
+        # - if the outermost YAML data structure is a mapping, then
+        #   yield each key, value pair
+        #
+        # - otherwise just yield the structure
+        #
+        # @return [Hash, Array, String, Fixnum] whatever the YAML contained
+        def load &block
+          require 'yaml'
+          yaml = YAML.load(read)
+          if block_given?
+            case yaml
+            when Array
+              yaml.each      { |obj| yield obj }
+            when Hash
+              yaml.each_pair { |key, value| yield key, value }
+            else
+              yield yaml
+            end
+          else
+            yaml
+          end
+        end
+
+        # Dump the +data+ into this resource.  It must be opened for
+        # writing.
+        #
+        # @param [Hash, String, Array, Fixnum] data the Ruby object to dump
+        # @option options [true, false] :persist (false) Don't close the IO object after writing
+        def dump data, options={}
+          require 'yaml'
+          write(data.to_yaml)
+          io.close unless options[:persist]
+          self
+        end
+      end
+    end
+  end
+end

data/lib/imw/resources/formats.rb

@@ -0,0 +1,32 @@
+module IMW
+  module Resources
+    module Formats
+      autoload :Csv,   'imw/resources/formats/delimited'
+      autoload :Tsv,   'imw/resources/formats/delimited'
+      autoload :Excel, 'imw/resources/formats/excel'
+      autoload :Json,  'imw/resources/formats/json'
+      autoload :Xml,   'imw/resources/formats/sgml'
+      autoload :Xsl,   'imw/resources/formats/sgml'
+      autoload :Html,  'imw/resources/formats/sgml'
+      autoload :Xhtml, 'imw/resources/formats/sgml'
+      autoload :Rdf,   'imw/resources/formats/sgml'      
+      autoload :Yaml,  'imw/resources/formats/yaml'
+
+      # Handlers which augment a resource with data format specific
+      # methods.
+      FORMAT_HANDLERS = [
+                         [ "Formats::Csv",   /\.csv$/    ],
+                         [ "Formats::Tsv",   /\.tsv$/    ],
+                         [ "Formats::Excel", /\.xslx?$/  ],
+                         [ "Formats::Json",  /\.json$/   ],
+                         [ "Formats::Xml",   /\.xml$/    ],
+                         [ "Formats::Xsl",   /\.xsl$/    ],                         
+                         [ "Formats::Html",  /\.html?$/  ],
+                         [ "Formats::Xhtml", /\.xhtml?$/ ],
+                         [ "Formats::Rdf",   /\.rdf?$/   ],
+                         [ "Formats::Yaml",  /\.ya?ml$/  ]
+                        ]
+    end
+  end
+end
+

data/lib/imw/resources/local.rb

@@ -0,0 +1,198 @@
+module IMW
+  module Resources
+
+    # Defines methods appropriate for any file (or directory) on the
+    # local machine.  Includes methods from the File class like
+    # File#exist?, File#size, &c.
+    #
+    # When extending with this module, it will automatically also
+    # extend with either IMW::Resources::LocalDirectory or
+    # IMW::Resources::LocalFile, as appropriate.
+    module LocalObj
+
+      def self.extended obj
+        # also extend with file or directory as appropriate
+        obj.extend(obj.directory? ? LocalDirectory : LocalFile)
+      end
+      
+      # Steal a bunch of class methods from File which only take a
+      # path as a first argument.
+      [:executable?, :executable_real?, :exist?, :file?, :directory?, :ftype, :owned?, :pipe?, :readable?, :readable_real?, :setgid?, :setuid?, :size, :size?, :socket?, :split, :stat, :sticky?, :writable?, :writable_real?, :zero?].each do |class_method|
+        define_method class_method do
+          File.send(class_method, path)
+        end
+      end
+      alias_method :exists?, :exist?
+
+      # Return the path to this local object.
+      #
+      # @return [String]
+      def path
+        @path ||= File.expand_path(@encoded_uri ? Addressable::URI.decode(uri.to_s) : uri.to_s)
+      end
+
+      # Is this file on the local machine?
+      #
+      # @return [true, false]
+      def is_local?
+        true
+      end
+
+      # Copy this resource to the +new_uri+.
+      #
+      # @param [String, IMW::Resource] new_uri
+      # @return [IMW::Resource] the new resource
+      def cp new_uri
+        IMW::Transforms::Transferer.new(:cp, self, new_uri).transfer!
+      end
+
+      # Move this resource to the +new_uri+.
+      #
+      # @param [String, IMW::Resource] new_uri
+      # @return [IMW::Resource] the new resource
+      def mv new_uri
+        IMW::Transforms::Transferer.new(:mv, self, new_uri).transfer!
+      end
+      
+    end
+
+    # Defines methods for appropriate for a local file.
+    module LocalFile
+
+      # Delete this resource.
+      def rm
+        should_exist!("Cannot delete")
+        FileUtils.rm path
+        self
+      end
+      alias_method :rm!, :rm
+
+      # Return the IO object at this path.
+      #
+      # @return [File]
+      def io
+        @io ||= open(path, mode)
+      end
+
+      # Read from this file.
+      #
+      # @param [Fixnum] length bytes to read
+      # @return [String]
+      def read length=nil
+        io.read(length)
+      end
+
+      # Write to this file
+      #
+      # @param [String, #to_s] text text to write
+      # @return [Fixnum] bytes written
+      def write text
+        io.write text
+      end
+
+      # Return the lines in this file.
+      #
+      # If passed a block, yield each line of the file to the block.
+      #
+      # @yield [String] each line of the file
+      # @return [Array] the lines in the file
+      def load &block
+        if block_given?
+          io.each do |line|
+            yield line
+          end
+        else
+          read.split("\n")
+        end
+      end
+
+      # Map over the lines in this file.
+      #
+      # @yield [String] each line of the file
+      def map &block
+        io.map(&block)
+      end
+
+      # Dump +data+ into this file.
+      #
+      # @param [String, Array, #each] data object to dump
+      # @option options [true, false] :persist (false) Don't close the file after writing
+      def dump data, options={}
+        data.each do |element|  # works if data is an Array or a String
+          io.puts(element.to_s)
+        end
+        io.close unless options[:persist]
+      end
+
+    end
+
+
+    module LocalDirectory
+
+      # Delete this directory.
+      #
+      # @return [IMW::Resource] the deleted directory
+      def rmdir
+        FileUtils.rmdir path
+        self
+      end
+
+      # Delete this directory recursively.
+      #
+      # @return [IMW::Resource] the deleted directory
+      def rm_rf
+        FileUtils.rm_rf path
+        self
+      end
+
+      # Return a list of paths relative to this directory which match
+      # the +selector+.  Works just like Dir[].
+      #
+      # @param [String] selector
+      # @return [Array] the matched paths
+      def [] selector='*'
+        Dir[File.join(path, selector)]
+      end
+
+      # Return a list of all paths directly within this directory.
+      #
+      # @return [Array]
+      def contents
+        self['*']
+      end
+
+      # Does this directory contain +obj+?
+      #
+      # @param [String, IMW::Resource] obj
+      # @return [true, false]
+      def contains? obj
+        require 'find'
+        obj_path = obj.is_a?(String) ? obj : obj.path
+        Find.find(path) do |sub_path|
+          return true if sub_path.ends_with?(obj_path)
+        end
+        false
+      end
+
+      # Return all paths within this directory, recursively.
+      #
+      # @return [Array<String>]
+      def all_contents
+        self['**/*']
+      end
+
+      # Return all resources within this directory, i.e. - all paths
+      # converted to IMW::Resource objects.
+      #
+      # @return [Array<IMW::Resource>]
+      def resources
+        all_contents.map do |path|
+          IMW.open(path) unless File.directory?(path)
+        end.compact
+      end
+
+    end
+  end
+end
+
+

data/lib/imw/resources/remote.rb

@@ -0,0 +1,110 @@
+module IMW
+  module Resources
+
+    # Defines methods appropriate for accessing a remote resource, no
+    # matter what the protocol.
+    module RemoteObj
+
+      #
+      # TODO -- self.extended should extend by RemoteDirectory when appropriate
+      #
+      
+      def self.extended obj
+        obj.extend(RemoteFile)
+      end
+
+      # Is this resource on a remote host?
+      #
+      # @return [true,false]
+      def is_remote?
+        true
+      end
+
+      # The host of this resource.
+      #
+      # @return [String]
+      def host
+        @host ||= uri.host
+      end
+
+      # Return the query string part of this resource's URI.  Will
+      # likely be +nil+ for local resources.
+      #
+      # @return [String]
+      def query_string
+        @query_string ||= uri.query
+      end
+
+      # Return the fragment part of this resource's URI.  Will likely be
+      # +nil+ for local resources.
+      #
+      # @return [String]
+      def fragment
+        @fragment ||= uri.fragment
+      end
+
+      # Return the path part of this resource's URI.  Will _not_
+      # include the +query_string+ or +fragment+.
+      #
+      # @return [String]
+      def path
+        @path ||= uri.path
+      end
+
+    end
+    
+    module RemoteFile
+
+      # Return the IO object for this remote file.
+      #
+      # The mode of this resource is ignored.
+      #
+      # @return [StringIO]
+      def io
+        require 'open-uri'
+        @io ||= open(uri.to_s)              # ignore mode
+      end
+
+      # Read the contents of this remote file.
+      #
+      # @return [String]
+      def read
+        io.read
+      end
+
+      # Return the lines of this remote file.
+      #
+      # If passed a block then yield each line to the block.
+      #
+      # @return [Array] the lines of this remote file
+      # @yield [String] each line of this remote file
+      def load &block
+        if block_given?
+          io.each do |line|
+            yield line
+          end
+        else
+          read.split("\n")
+        end
+      end
+
+      # Map over the lines in this remote file.
+      #
+      # @yield [String] each line of the file
+      def map &block
+        io.map(&block)
+      end
+    end
+
+
+    module RemoteDirectory
+
+      #
+      # TODO -- bloody everything
+      #
+
+      
+    end
+  end
+end
+