smc-get 0.1.0 → 0.2.0.beta1

data/lib/smc_get/package_archive.rb

@@ -0,0 +1,80 @@
+#Encoding: UTF-8
+################################################################################
+# This file is part of smc-get.
+# Copyright (C) 2010-2011 Entertaining Software, Inc.
+# Copyright (C) 2011 Marvin Gülker
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+################################################################################
+
+module SmcGet
+  
+  #This class allows for easy compression and decompression of .smcpak
+  #files. Please note that during this process no validations are performed,
+  #i.e. you have to ensure that the directory you want to compress is in
+  #smc package layout and the .smcpak files you want to decompress are
+  #really smc packages.
+  class PackageArchive
+    
+    #The location of this archive.
+    attr_reader :path
+    
+    #Compresses all files in +directory+ into a TAR.XZ file with the
+    #extension ".smcpak".
+    #Returns an object of this class.
+    #  smcpak = PackageArchive.compress("mypackage")
+    #  puts smcpak.path #=> mypackage.smcpak
+    def self.compress(directory, goal_file)
+      directory = Pathname.new(directory).expand_path
+      tar_file = Pathname.new("#{goal_file}.tar").expand_path
+      xz_file = Pathname.new(goal_file).expand_path
+      
+      Dir.chdir(directory.parent) do
+        tar_file.open("wb") do |file|
+          Archive::Tar::Minitar.pack(directory.relative_path_from(Pathname.new(".").expand_path).to_s, file)
+        end
+      end
+      XZ.compress_file(tar_file, xz_file)
+      
+      tar_file.delete #We don’t need it anymore
+      
+      new(xz_file)
+    end
+    
+    #Creates a new PackageArchive from an existing .smcpak file.
+    def initialize(archive)
+      @path = Pathname.new(archive)
+    end
+    
+    #Decompresses this archive into +directory+, creating a subdirectory
+    #named after the archive without the extension, and returns the path
+    #to that subdirectory (a Pathname object).
+    #  smcpak = PackageArchive.new("mypackage.smcpak")
+    #  puts smcpak.decompress #=> #<Pathname:mypackage>
+    def decompress(directory)
+      directory = Pathname.new(directory)
+      tar_file = directory + @path.basename.to_s.sub(/\.smcpak$/, ".tar")
+      dest_dir = directory + tar_file.basename.to_s.sub(/\.tar$/, "")
+      
+      XZ.decompress_file(@path.to_s, tar_file.to_s)
+      Archive::Tar::Minitar.unpack(tar_file.to_s, dest_dir.to_s)
+      
+      tar_file.delete #We don’ŧ need it anymore
+      
+      dest_dir
+    end
+    
+  end
+  
+end

data/lib/smc_get/package_specification.rb

@@ -0,0 +1,253 @@
+#Encoding: UTF-8
+################################################################################
+# This file is part of smc-get.
+# Copyright (C) 2010-2011 Entertaining Software, Inc.
+# Copyright (C) 2011 Marvin Gülker
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+################################################################################
+
+module SmcGet
+
+  #A PackageSpecification object is a mostly informational object
+  #directly related to Package objects. That is, each and every
+  #Package instance has a Package#spec method that will retrieve
+  #the PackageSpecification, an instance of this class, for you:
+  #
+  #  puts pkg.spec.title #=> Cool package
+  #
+  #Instances of this class can be understood as the parsed content of
+  #a package’s specification file. It has getter and setter methods
+  #reflecting the keys that are allowed in the specification (see
+  #the smcpak.rdoc file), but unless you want to build smc packages,
+  #there’s no need for you to use the setter methods.
+  class PackageSpecification
+    
+    #The keys listed here must be mentioned inside a package spec,
+    #otherwise the package is considered broken.
+    SPEC_MANDATORY_KEYS = [:title, :last_update, :authors, :difficulty, :description, :checksums].freeze
+    
+    ##
+    # :attr_accessor: title
+    #The package’s title.
+
+    ##
+    # :attr_accessor: last_update
+    #The time (an instance of class Time) indicating when the package
+    #was last updated.
+    
+    ##
+    # :attr_accessor: authors
+    #The authors of this package. An array.
+    
+    ##
+    # :attr_accessor: difficulty
+    #The difficulty of this package as a string.
+    
+    ##
+    # :attr_accessor: description
+    #The description of this package.
+    
+    ##
+    # :attr_accessor: install_message
+    #A message to display during installation of this package or nil if
+    #no message shall be displayed.
+    
+    ##
+    # :attr_accessor: remove_message
+    #A message to display during removing of this package or nil if no
+    #message shall be displayed.
+    
+    ##
+    # :attr_accessor: dependecies
+    #An array of package names this package depends on, i.e. packages that
+    #need to be installed before this one can be installed. The array is
+    #empty if no dependecies exist.
+    
+    ##
+    # :attr_accessor: levels
+    #An array of level file names (strings).
+    
+    ##
+    # :attr_accessor: music
+    #An array of music file names (strings).
+    
+    ##
+    # :attr_accessor: sounds
+    #An array of sound file names (strings).
+    
+    ##
+    # :attr_accessor: graphics
+    #An array of graphic file names (strings).
+    
+    ##
+    # :attr_accessor: worlds
+    #An array of graphic file names (strings).
+
+    ##
+    # :attr_accessor: checksums
+    #A hash that maps each filename in this package to it’s SHA1 checksum.
+    
+    #The name of the package this specification is used in, without any
+    #file extension.
+    attr_reader :name
+    
+    ##
+    # :attr_reader: compressed_file_name
+    #The name of the compressed file this specification should belong to.
+    #The same as name, but the extension .smcpak was appended.
+    
+    ##
+    # :attr_reader: spec_file_name
+    #The name of the specification file. The same as name, but
+    #the extension .yml was appended.
+
+    #Creates a PackageSpecification by directly reading a complete
+    #spec from a YAML file.
+    #==Parameter
+    #[path] The path to the file to read.
+    #==Return value
+    #An instance of this class.
+    #==Raises
+    #[InvalidSpecification] +path+ was not found or was malformatted.
+    #==Example
+    #  path = remote_repo.fetch_spec("cool_pkg.yml")
+    #  spec = SmcGet::PackageSpecification.from_file(path)
+    #  puts spec.title #=> "Cool package"
+    #==Remarks
+    #This method may be useful if you don’t need a full-blown
+    #Package object and just want to deal with it’s most important
+    #attributes.
+    def self.from_file(path)
+      info = nil
+      begin
+        info = YAML.load_file(path.to_s)
+      rescue Errno::ENOENT => e
+        raise(Errors::InvalidSpecification, "File '#{path}' doesn't exist!")
+      rescue => e
+        raise(Errors::InvalidSpecification, "Invalid YAML: #{e.message}")
+      end
+      
+      spec = new(File.basename(path).sub(/\.yml$/, ""))
+      info.each_pair do |key, value|
+        spec.send(:"#{key}=", value)
+      end
+      #TODO: Convert the strings in :checksums to strings, except the
+      #filenames, those should be strings. Anyone???
+      
+      raise(Errors::InvalidSpecification, spec.validate.first) unless spec.valid?
+      
+      spec
+    end
+    
+    #Returns the matching package name from the package specification’s name
+    #by replacing the .yml extension with .smcpak.
+    #==Return value
+    #A string ending in ".smcpak".
+    #==Example
+    #  p SmcGet::PackageSpecification.spec2pkg("cool_pkg.yml") #=> "cool_pkg.smcpak")
+    def self.spec2pkg(spec_file_name) # :nodoc:
+      spec_file_name.to_s.sub(/\.yml$/, ".smcpak")
+    end
+    
+    #Returns the matching specification file name from the package’s name
+    #by replacing the .smcpak extension with .yml.
+    #==Return value
+    #A string ending in ".yml"
+    #==Example
+    #  p SmcGet::PackageSpecification.pkg2spec("cool_pkg.smcpak") #=> "cool_pkg.yml"
+    def self.pkg2spec(package_file_name) # :nodoc:
+      package_file_name.to_s.sub(/\.smcpak$/, ".yml")
+    end
+    
+    def initialize(pkg_name)
+      @info = {:dependencies => [], :levels => [], :music => [], :sounds => [], :graphics => [], :worlds => []}
+      @name = pkg_name
+    end
+    
+    #See attribute.
+    def compressed_file_name # :nodoc:
+      "#@name.smcpak"
+    end
+    
+    #See attribute.
+    def spec_file_name # :nodoc:
+      "#@name.yml"
+    end
+    
+    [:title, :last_update, :authors, :difficulty, :description, :install_message, :remove_message, :dependencies, :levels, :music, :sounds, :graphics, :worlds, :checksums].each do |sym|
+      define_method(sym){@info[sym]}
+      define_method(:"#{sym}="){|val| @info[sym] = val}
+    end
+    
+    def [](sym)
+      if respond_to?(sym)
+        send(sym)
+      else
+        raise(IndexError, "No such specification key: #{sym}!")
+      end
+    end
+    
+    def valid?
+      validate.empty?
+    end
+    
+    def validate
+      errors = []
+      
+      SPEC_MANDATORY_KEYS.each do |sym|
+        errors << "Mandatory key #{sym} is missing!" unless @info.has_key?(sym)
+      end
+      
+      errors
+    end
+    
+    #Compares two specifications. They are considered equal if all their
+    #attributes (levels, difficulty, etc.) are equal.
+    def ==(other)
+      return false unless other.respond_to? :info
+      @info == other.info
+    end
+
+    #Saves the package specification in YAML format into a file.
+    #==Parameter
+    #[directory] The directory where to save the file to. The filename is automatically
+    #            detected from the attributes set for the specification.
+    #==Raises
+    #[InvalidSpecification] The specification was not valid, i.e. contained incorrect
+    #                       or missing values.
+    #==Example
+    #  p spec.name                  #=> "cool_pkg"
+    #  spec.save(".")
+    #  p File.file?("cool_pkg.yml") #=> true
+    def save(directory)
+      raise(Errors::InvalidSpecification, validate.first) unless valid?
+      
+      path = Pathname.new(directory) + "#{@name}.yml"
+      #Turn the spec keys for serialization into strings
+      hsh = {}
+      @info.each_pair{|k, v| hsh[k.to_s] = v}
+      path.open("w"){|f| YAML.dump(hsh, f)}
+    end
+    
+    protected
+
+    #Returns the complete internal information hash.
+    def info
+      @info
+    end
+    
+  end
+  
+end

data/lib/smc_get/remote_repository.rb

@@ -0,0 +1,272 @@
+#Encoding: UTF-8
+################################################################################
+# This file is part of smc-get.
+# Copyright (C) 2010-2011 Entertaining Software, Inc.
+# Copyright (C) 2011 Marvin Gülker
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+################################################################################
+
+module SmcGet
+  
+  #A RemoteRepository represents a web location from which <tt>smc-get</tt>
+  #is able to download packages. The structure of those repositories is
+  #explained in the smcpak.rdoc file in the <i>Repostories</i> section.
+  class RemoteRepository < Repository
+    
+    #Name of the remote directory containing the <tt>.smcpak</tt> files.
+    PACKAGES_DIR = "packages"
+    #Name of the remote directory containing the packages specifications.
+    SPECS_DIR    = "specs"
+    #Name of the file containg the names of all packages in this repository.
+    LIST_FILE    = "packages.lst"
+    #Number of bytes to read while downloading a file.
+    CHUNK_SIZE   = 1024
+    
+    ##
+    # :attr_reader: packages
+    #Returns an array of remote Packages that contains all packages
+    #in this repository. This is a very time-intensive operation, depending
+    #on how many packages the repository contains, because it downloads all
+    #the package specifications of all the packages. It’s not a good idea
+    #to call this.
+    
+    #An URI object representing the repository’s URI.
+    attr_reader :uri
+    #A list of all package names (without an extension).
+    attr_reader :packages_list
+    
+    #Creates a "new" Repository.
+    #==Parameters
+    #[uri] The URI of the repository, something like
+    #      "\http://my-host.org/smc-repo".
+    #==Raises
+    #[InvalidRepository] The repository is either nonexistant or doesn’t obey
+    #                    the repository structure format.
+    #==Return value
+    #The newly created repository.
+    #==Usage
+    #  r = Repository.new("http://myrepo.org")
+    #  r = Repository.new("https://my-host.org/smc-repo")
+    #  r = Repository.new("ftp://ftp.my-host.org/smc")
+    def initialize(uri)
+      @uri = URI.parse(uri)
+      #Download the packages list. Usually it’s small enough to fit into RAM.
+      begin
+        @packages_list = open(@uri + LIST_FILE){|tmpfile| tmpfile.read}.split
+      rescue SocketError, Errno::ECONNREFUSED, OpenURI::HTTPError => e #open-uri raises HTTPError even in case of other protocols
+        raise(Errors::InvalidRepository.new(@uri), e.message)
+      end
+    end
+    
+    #Downloads the given package specification from this repository and
+    #places it in +directory+.
+    #
+    #If the file already exists, it’s overwritten.
+    #==Parameters
+    #[spec_file] The package specification file you want to download. It must
+    #            end with the <tt>.yml</tt> extension.
+    #[directory] (".") The directory where you want to download the file to.
+    #            Created if it doesn’t exist.
+    #==Raises
+    #[NoSuchResourceError] The package name for this specification couldn’t be
+    #                      found in the repository. Note that the spec may be
+    #                      there despite of this, but packages not listed
+    #                      in the repository’s contents file are treated as if
+    #                      they weren’t there.
+    #==Return value
+    #The path to the downloaded file as a Pathname object.
+    #==Usage
+    #  my_repo.fetch_spec("mypackage.yml", "/home/freak/Downloads")
+    #
+    #  my_repo.fetch_spec("mypackage.yml")
+    def fetch_spec(spec_file, directory = ".")
+      directory = Pathname.new(directory)
+      pkg_name = spec_file.sub(/\.yml$/, "")
+      goal_file = directory + spec_file
+      
+      unless @packages_list.include?(pkg_name)
+        raise(Errors::NoSuchResourceError.new(:spec, spec_file), "Package '#{pkg_name}' not found in the repository!")
+      end
+      
+      directory.mktree unless directory.directory?
+      
+      #I am quite sure that URI#merge has a bug. Example:
+      #  uri = URI.parse("http://www.ruby-lang.org")
+      #Now try to append the path test/test2:
+      #  uri2 = uri + "test" + "test2"
+      #What do you think contains uri2? This:
+      #  http://www.ruby-lang.org/test2
+      #Something missing, eh? Even more surprising, this one works as
+      #expected:
+      #  uri + "test/test2"
+      #The second one is the workaround I use in the following line.
+      open(@uri.merge("#{SPECS_DIR}/#{spec_file}")) do |tempfile|
+        File.open(goal_file, "w") do |file|
+          file.write(tempfile.read) #Specs almost ever are small enough to fit in RAM
+        end
+      end
+      goal_file
+    end
+    
+    #Downloads the given package from this repository and places it in
+    #+directory+. Yields the package’s total size in bytes and how many
+    #bytes have already been downloaded. If the size is unknown for some
+    #reason, +bytes_total+ is nil. For the last block call, +bytes_total+
+    #and +bytes_done+ are guaranteed to be equal, except if +bytes_total+
+    #couldn’t be determined in which case it’s still nil.
+    #
+    #If the file does already exist in +directory+, it is overwritten.
+    #==Parameters
+    #[pkg_file]  The package file you want to download. It must end in
+    #            the <tt>.smcpak</tt> extension.
+    #[directory] (".") The directory where you want to download the file to.
+    #            Created if it doesn’t exist.
+    #==Raises
+    #[NoSuchPackageError] The package name for this package couldn’t be
+    #                     found in the repository. Note that the package may be
+    #                     there despite of this, but packages not listed
+    #                     in the repository’s contents file are treated as if
+    #                     they weren’t there.
+    #[OpenURI::HTTPError] Connection error.
+    #==Return value
+    #The path to the downloaded file as a Pathname object.
+    #==Usage
+    #  my_repo.fetch_package("mypackage.smcpak", "/home/freak/downloads")
+    #
+    #  my_repo.fetch_package("mypackage.smcpak") do |bytes_total, bytes_done|
+    #    print("\rDownloaded #{bytes_done} bytes of #{bytes_total}.") if bytes_total
+    #  end
+    def fetch_package(pkg_file, directory = ".")
+      directory = Pathname.new(directory)
+      pkg_name = pkg_file.sub(/\.smcpak$/, "")
+      goal_file = directory + pkg_file
+      
+      unless @packages_list.include?(pkg_name)
+        raise(Errors::NoSuchPackageError.new(pkg_name), "ERROR: Package '#{pkg_name}' not found in the repository!")
+      end
+      
+      directory.mktree unless directory.directory?
+      
+      bytes_total = nil
+      size_proc = lambda{|content_length| bytes_total = content_length}
+      prog_proc = lambda{|bytes_done| yield(bytes_total, bytes_done)}
+      
+      #See the source of #fetch_spec for an explanation on the obscure
+      #URI concatenation.
+      open(@uri + "#{PACKAGES_DIR}/#{pkg_file}", "rb", content_length_proc: size_proc, progress_proc: prog_proc) do |tempfile|
+        #The packages may be too big for fitting into RAM, therefore we’re going
+        #to read and write the packages chunk by chunk. Btw. please notice me
+        #if you find a SMC package that’s larger than 4 GiB! I’d be curious
+        #about what it contains!
+        File.open(goal_file, "wb") do |file|
+          while chunk = tempfile.read(CHUNK_SIZE)
+            file.write(chunk)
+          end
+        end
+      end
+      
+      goal_file
+    end
+    
+    #Not implemented yet.
+    def install(package, &block)
+      raise(NotImplementedError, "Can't automatically upload to remote repositories yet!")
+    end
+    
+    #Not implemented yet.
+    def uninstall(pkg_name)
+      raise(NotImplementedError, "Can't automatically remove from remote repositories yet!")
+    end
+
+    #Returns the URI of the remote repository.
+    def to_s
+      @uri.to_s
+    end
+    
+    #See attribute.
+    # def packages # :nodoc:
+    #   @packages_list.map do |pkg_name|
+    #     Package.from_repository(self, "#{pkg_name}.yml")
+    #   end
+    # end
+    
+    #True if a package with the given name (without the .smcpak extension)
+    #exists in the repository.
+    def contain?(pkg)
+      if pkg.kind_of? Package
+        @packages_list.include?(pkg.spec.name)
+      else
+        @packages_list.include?(pkg_name)
+      end
+    end
+    alias contains? contain?
+
+    #call-seq:
+    #  search(regexp [, *attributes ]){|pkgname|...}
+    #
+    #Searches for a specific package and yields each candidate to the
+    #given block.
+    #==Parameters
+    #[regexp]      The Regular Expression to use as the search pattern.
+    #[*attributes] (<tt>[:name]</tt>) A list of all attributes to match
+    #              the Regular Expression against (note that only
+    #              passing :name is siginificantly faster, because
+    #              there’s no need to download the specs).
+    #              Possible attributes:
+    #              * name
+    #              * title
+    #              * authors
+    #              * difficulty
+    #              * description
+    #              * levels
+    #              * music
+    #              * sounds
+    #              * graphics
+    #              * worlds
+    #[pkgname]     *Blockargument*. The package name (not title!) of
+    #              a package matching the search criteria.
+    #==Examples
+    #  rp.search(/cool/){|pkgname| p pkgname}            #=> "cool_levels"
+    #  rp.search(/Luiji/i, :authors){|pkgname| p pkgname} #=> All packages created by Luiji or luiji...
+    def search(regexp, *attributes)
+      attributes << :name if attributes.empty? #Default value
+      if attributes == [:name] #Good, no need to download all the specs
+        @packages_list.each{|name| yield(name) if name =~ regexp}
+      else #OK, so we need to download one spec after the other...
+        @packages_list.each do |pkgname|
+          spec = PackageSpecification.from_file(fetch_spec("#{pkgname}.yml", SmcGet.temp_dir))
+          attributes.each do |att|
+            case att
+            when :name        then yield(pkgname) if spec.name =~ regexp
+            when :title       then yield(pkgname) if spec.title =~ regexp
+            when :authors     then yield(pkgname) if spec.authors.any?{|a| a =~ regexp}
+            when :difficulty  then yield(pkgname) if spec.difficulty =~ regexp
+            when :description then yield(pkgname) if spec.description =~ regexp
+            when :levels      then yield(pkgname) if spec.levels.any?{|l| l =~ regexp}
+            when :music       then yield(pkgname) if spec.music.any?{|m| m =~ regexp}
+            when :sounds      then yield(pkgname) if spec.sound.any?{|s| s =~ regexp}
+            when :graphics    then yield(pkgname) if spec.graphics.any?{|g| g =~ regexp}
+            when :worlds      then yield(pkgname) if spec.worlds.any?{|w| w =~ regexp}
+            else
+              $stderr.puts("Warning: Unknown attribute #{att}, ignoring it.")
+            end #case
+          end #attributes.each
+        end # @packages.each
+      end #if only :name
+    end #search
+    
+  end #RemoteRepository
+  
+end #SmcGet