smc-get 0.1.0 → 0.2.0.beta1

data/lib/smc_get/gui.rb

@@ -1,19 +1,20 @@
-#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/>.
-################################################################################
+#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/>.
+################################################################################
+# vim:set ts=8 sts=2 sw=2 et: #

data/lib/smc_get/local_repository.rb

@@ -0,0 +1,277 @@
+#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 LocalRepository contains all the packages that are installed locally, i.e.
+  #that have been downloaded and added to your local SMC installation.
+  #It provides the exact same methods as RemoteRepository, but works completely
+  #local and therefore doesn’t need an internet connection as RemoteRepository does.
+  #
+  #The only notable difference is that instances of this class have some
+  #attributes different from those defined for RemoteRepository, but usually
+  #you shouldn’t have to worry about that.
+  #
+  #Concluding, you’ll find the documentation of most of the methods of this class
+  #in the documentation of the RemoteRepository class, because duplicating docs
+  #doesn’t make much sense.
+  class LocalRepository < Repository
+    
+    #Directory where the package specs are kept.
+    SPECS_DIR            = Pathname.new("packages")
+    #Directory where downloaded packages are cached.
+    CACHE_DIR            = Pathname.new("cache")
+    #Directory where the packages’ level files are kept.
+    CONTRIB_LEVELS_DIR   = Pathname.new("levels") #Levels in subdirectories are currently not recognized by SMC
+    #Directory where the packages’ music files are kept.
+    CONTRIB_MUSIC_DIR    = Pathname.new("music") + "contrib-music"
+    #Directory where the packages’ graphic files are kept.
+    CONTRIB_GRAPHICS_DIR = Pathname.new("pixmaps") + "contrib-graphics"
+    #Directory where the packages’ sound files are kept.
+    CONTRIB_SOUNDS_DIR   = Pathname.new("sounds") + "contrib-sounds"
+    #Directory where the packages’ world files are kept
+    CONTRIB_WORLDS_DIR   = Pathname.new("world") #Worlds in subdirectores are currently not recognized by SMC
+    
+    #Root path of the local repository. Should be the same as your SMC’s
+    #installation path.
+    attr_reader :path
+    #This repository’s specs dir.
+    attr_reader :specs_dir
+    #This repository’s cache dir.
+    attr_reader :cache_dir
+    #This repository’s package levels dir.
+    attr_reader :contrib_level_dir
+    #This repository’s package music dir.
+    attr_reader :contrib_music_dir
+    #This repository’s package graphics dir.
+    attr_reader :contrib_graphics_dir
+    #This repository’s package sounds dir.
+    attr_reader :contrib_sounds_dir
+    #This repository’s package worlds dir.
+    attr_reader :contrib_worlds_dir
+    #An array of PackageSpecification objects containing the specs of
+    #all packages installed in this repository.
+    attr_reader :package_specs
+
+    #"Creates" a new local repository whose root is located at the given +path+.
+    #When instanciating this class, you should point it to the root of your
+    #SMC installation’s *share* directory, e.g. <b>/usr/share/smc</b>.
+    #==Parameter
+    #[path] The path to your SMC installation.
+    #==Return value
+    #The newly created LocalRepository.
+    #==Example
+    #  lr = SmcGet::LocalRepository.new("/usr/share/smc")
+    #==Remarks
+    #smc-get requires some additional directories in your SMC installation,
+    #namely (where +smc+ is your SMC’s *share* directory):
+    #  * smc/packages
+    #  * smc/music/contrib-music
+    #  * smc/sounds/contrib-sounds
+    #  * smc/pixmaps/contrib-graphics
+    #These will be created when you call this method, so make sure
+    #you have the appropriate permissions for these directories or
+    #you’ll get an Errno::EACCES exception when calling ::new.
+    def initialize(path)
+      @path         = Pathname.new(path)
+      @specs_dir    = @path + SPECS_DIR
+      @cache_dir    = @path + CACHE_DIR
+      @levels_dir   = @path + CONTRIB_LEVELS_DIR
+      @music_dir    = @path + CONTRIB_MUSIC_DIR
+      @graphics_dir = @path + CONTRIB_GRAPHICS_DIR
+      @sounds_dir   = @path + CONTRIB_SOUNDS_DIR
+      @worlds_dir   = @path + CONTRIB_WORLDS_DIR
+      
+      #Create the directories if they’re not there yet
+      [@specs_dir, @cache_dir, @levels_dir, @music_dir, @graphics_dir, @sounds_dir, @worlds_dir].each do |dir|
+        dir.mkpath unless dir.directory?
+      end
+      
+      @package_specs = []
+      @specs_dir.children.each do |spec_path|
+        next unless spec_path.to_s.end_with?(".yml")
+        @package_specs << PackageSpecification.from_file(spec_path)
+      end
+    end
+    
+    def fetch_spec(spec_file, directory = ".")
+      directory = Pathname.new(directory)
+      
+      spec_file_path = @specs_dir + spec_file
+      raise(Errors::NoSuchResourceError.new(:spec, spec_file), "Package specification '#{spec_file}' not found in the local repository '#{to_s}'!") unless spec_file_path.file?
+      
+      directory.mktree unless directory.directory?
+      
+      #No need to really "fetch" the spec--this is a *local* repository.
+      FileUtils.cp(spec_file_path, directory)
+      directory + spec_file
+    end
+    
+    def fetch_package(pkg_file, directory = ".")
+      directory = Pathname.new(directory)
+      
+      pkg_file_path = @cache_dir + pkg_file
+      raise(Errors::NoSuchPackageError.new(pkg_file.sub(/\.smcpak/, "")), "Package file '#{pkg_file}' not found in this repository's cache!") unless pkg_file_path.file?
+      
+      directory.mktree unless directory.directory?
+      
+      #No need to really "fetch" the package--this is a *local* repository
+      FileUtils.cp(pkg_file_path, directory)
+      directory + pkg_file
+    end
+
+    #Installs a package into this local repository in a way that SMC will find
+    #it’s contents.
+    #==Parameter
+    #[package] An instance of class Package. The package to install,
+    #==Example
+    #  lr.install(a_package)
+    #==Remarks
+    #Ensure you have write permissions to the repository, otherwise
+    #you’ll get an Errno::EACCES exception from this method.
+    def install(package)
+      path = package.decompress(SmcGet.temp_dir) + package.spec.name
+      
+      package.spec.save(@specs_dir)
+      
+      FileUtils.cp_r(path.join(Package::LEVELS_DIR).children, @levels_dir)
+      FileUtils.cp_r(path.join(Package::MUSIC_DIR).children, @music_dir)
+      FileUtils.cp_r(path.join(Package::GRAPHICS_DIR).children, @graphics_dir)
+      FileUtils.cp_r(path.join(Package::SOUNDS_DIR).children, @sounds_dir)
+      FileUtils.cp_r(path.join(Package::WORLDS_DIR).children, @worlds_dir)
+      
+      FileUtils.cp(package.path, @cache_dir)
+      
+      @package_specs << package.spec #This package is now installed and therefore the spec must be in that array
+    end
+
+    #call-seq:
+    #  uninstall(pkg_name)
+    #  uninstall(pkg_name){|path| ...}
+    #
+    #Uninstalls a package by removing all files it owns. This method checks the
+    #checksums specified in the respective package specifications and if it
+    #detects a user-modified file, the given block is invoked. If the block
+    #evaluates to a truth value, the modified file is copied to a file
+    #in the same directory as the original with ".MODIFIED" just before the
+    #file extension. The blockless form always discards all modified files.
+    #==Parameters
+    #[pkg_name]  The name of the package (without the .smcpak extension) to remove.
+    #[full_path] *Blockargument*. The full Pathname of a file that has been modified.
+    #==Example
+    #  # Delete a package and save all modified files
+    #  rr.uninstall("cool-world"){|file| true}
+    #  # Delete a package and discard all modified files
+    #  rr.uninstall("cool-world")
+    def uninstall(pkg_name)
+      spec = @package_specs.find{|spec| spec.name == pkg_name}
+      
+      [:levels, :music, :sounds, :graphics].each do |sym|
+        contrib_dir = @path + self.class.const_get(:"CONTRIB_#{sym.upcase}_DIR")
+        
+        #Delete all the files
+        files = spec[sym]
+        files.each do |filename|
+          full_path = contrib_dir + filename
+          #Check if the file was modified
+          if block_given? and Digest::SHA1.hexdigest(File.read(full_path)) != spec[:checksums][sym.to_s][filename] #to_s as the keys are strings there, see PackageSpecification.from_file
+            if yield(full_path) #Getting a truth value from the block means copying
+              FileUtils.cp(full_path, full_path.parent + filename.sub(/\.(.*?)$/, '.MODIFIED.\1'))
+            end
+          end
+          File.delete(full_path)
+        end
+        
+        #Delete now empty directories
+        loop do
+          empty_dirs = []
+          contrib_dir.find do |path|
+            next if path == contrib_dir #We surely don’t want to delete the toplevel dir.
+            empty_dirs << path if path.directory? and path.children.empty?
+          end
+          #If no empty directories are present anymore, break out of the loop.
+          break if empty_dirs.empty?
+          #Otherwise delete the empty directories and redo the process, because
+          #the parent directories could be empty now.
+          empty_dirs.each{|path| File.delete(path)}
+        end
+      end
+
+      #Delete worlds as well. Worlds can’t reside in subdirectories, therefore it’s unnecessary
+      #to check for the empty-directory thing.
+      spec[:worlds].each do |dirname|
+        full_path = @worlds_dir + dirname
+        #Check if any of the world’s files has been modified
+        ["description.xml", "layer.xml", "world.xml"].each do |wfile|
+          full_wfile_path = full_path + wfile
+          if block_given? and Digest::SHA1.hexdigest(full_wfile_path) != spec[:checksums]["worlds"][dirname][wfile] #"worlds" is a string for technical reasons, see PackageSpecification.from_file
+            if yield(full_wfile_path) #Getting a truth value from the block means copying
+              FileUtils.cp_r(full_path, full_path.parent + "#{dirname}.MODIFIED")
+              break #Break from the inner iteration, we just need to copy once
+            end
+          end
+        end
+        FileUtils.rm_r(full_path)
+      end
+
+      File.delete(@specs_dir + spec.spec_file_name) #Remove the spec itself
+      @package_specs.delete(spec) #Otherwise we have a stale package in the array
+    end
+
+    #Returns the path this repository refers to.
+    def to_s
+      @path.to_s
+    end
+    
+    def contain?(pkg)
+      if pkg.kind_of? Package
+        @package_specs.include?(pkg.spec)
+      else
+        @package_specs.any?{|spec| spec.name == pkg}
+      end
+    end
+    alias contains? contain?
+
+    def search(regexp, *attributes)
+      attributes << :name if attributes.empty? #Default value
+      
+      @package_specs.each do |spec|
+        attributes.each do |att|
+          case att
+          when :name        then yield(spec.name) if spec.name =~ regexp
+          when :title       then yield(spec.name) if spec.title =~ regexp
+          when :authors     then yield(spec.name) if spec.authors.any?{|a| a =~ regexp}
+          when :difficulty  then yield(spec.name) if spec.difficulty =~ regexp
+          when :description then yield(spec.name) if spec.description =~ regexp
+          when :levels      then yield(spec.name) if spec.levels.any?{|l| l =~ regexp}
+          when :music       then yield(spec.name) if spec.music.any?{|m| m =~ regexp}
+          when :sounds      then yield(spec.name) if spec.sound.any?{|s| s =~ regexp}
+          when :graphics    then yield(spec.name) if spec.graphics.any?{|g| g =~ regexp}
+          when :worlds      then yield(spec.name) if spec.worlds.any?{|w| w =~ regexp}
+          else
+            $stderr.puts("Warning: Unknown attribute #{att}, ignoring it.")
+          end #case
+        end #attributes.each
+      end # @package_specs.each
+    end #search
+    
+  end #LocalRepository
+  
+end

data/lib/smc_get/package.rb

@@ -1,279 +1,260 @@
-#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
-  
-  #An object of this class represents a package. Wheather it is installed or
-  #not, doesn't matter (call #installed? to find out), but everything you
-  #want to manage your packages can be found here. For example, to install
-  #a remote package, do:
-  #  pkg = SmcGet::Package.new("mypackage")
-  #  pkg.install
-  #Don't forget to set up smc-get before you use the library:
-  #  require "smc_get/"
-  #  SmcGet.setup(
-  #    "https://github.com/Luiji/Secret-Maryo-Chronicles-Contributed-Levels/raw/master/",
-  #    "dir/where/you/hava/smc/installed"
-  #  end
-  class Package
-    
-    #The package specification file for this packages. This file may not
-    #exist if the package is not installed. This is a Pathname object.
-    attr_reader :spec_file
-    #The name of this package.
-    attr_reader :name
-    
-    class << self
-      
-      #Searches through the package repostitory and returns an array
-      #of matching package objects.
-      #
-      #Pass in the regular expression to search for (or a string, which
-      #then is treated as a regular expression without anchors), the
-      #keys of the specification to search through as an array of symbols,
-      #and wheather you want to query only locally installed packages (by
-      #default, only remote packages are searched).+query_fields+ indicates
-      #which fields of the package specification shall be searched. You can
-      #pass them as an array of symbols. +only_local+ causes smc-get to
-      #do a local search instead of a remote one.
-      #
-      #With solely :pkgname specified, just the specifications for the packages
-      #whose package file names match +regexp+ are downloaded, causing a
-      #massive speedup.
-      def search(regexp, query_fields = [:pkgname], only_local = false)
-        regexp = Regexp.new(Regexp.escape(regexp)) if regexp.kind_of? String
-        ary = []
-      
-        list = if only_local
-          Errors::LibraryNotInitialized.throw_if_needed!
-          installed_packages.map(&:name)
-        else
-          Tempfile.open("smc-get") do |listfile|
-            SmcGet.download(PACKAGE_LIST_FILE, listfile.path)
-            listfile.readlines.map(&:chomp)
-          end
-        end
-      
-        list.each do |pkg_name|
-          pkg = Package.new(pkg_name)
-          #If the user wants to query just the pkgname, we can save
-          #much time by not downloading all the package specs.
-          if query_fields == [:pkgname]
-            ary << pkg if pkg_name =~ regexp
-          else
-            spec = only_local ? pkg.spec : pkg.getinfo
-            query_fields.each do |field|
-              if field == :pkgname #This field is not _inside_ the spec.
-                ary << pkg if pkg_name =~ regexp
-              else
-                #First to_s: Convert Symbol to string used in the specs.
-                #Second to_s: Ensure array values such as "author" are
-                #             handled correctly.
-                ary << pkg if spec[field.to_s].to_s =~ regexp
-              end
-            end
-          end
-        end
-        ary
-      end
-      
-      #Returns a list of all currently installed packages as an array of
-      #Package objects.
-      def installed_packages
-        Errors::LibraryNotInitialized.throw_if_needed!
-        specs_dir = SmcGet.datadir + PACKAGE_SPECS_DIR
-        specs_dir.mkpath unless specs_dir.directory?
-        
-        #We need to chdir here, because Dir.glob returns the path
-        #relative to the current working directory and it should be
-        #a bit more performant if I don't have to strip off the relative
-        #prefix of the filenames (which are the names of the packages + .yml).
-        Dir.chdir(specs_dir.to_s) do
-          Dir.glob("**/*.yml").map{|filename| new(filename.match(/\.yml$/).pre_match)}
-        end
-      end
-      
-    end
-    
-    #Creates a new package object from it's name. This doesn't do anything,
-    #especially it doesn't install the package. It just creates an object for
-    #you you can use to inspect or install pacakges. It doesn't even check if
-    #the package name is valid.
-    def initialize(package_name)
-      Errors::LibraryNotInitialized.throw_if_needed!
-      @name = package_name
-      @spec_file = SmcGet.datadir.join(PACKAGE_SPECS_DIR, "#{@name}.yml")
-    end
-    
-    # Install a package from the repository. Yields the name of the file
-    # currently being downloaded, how many percent of that
-    # file have already been downloaded and wheather or not this is a retry (if
-    # so, the exception object is yielded, otherwise false).
-    # The maximum number of retries is specified via the +max_tries+ parameter.
-    def install(max_tries = 3) # :yields: file, percent_file, retrying
-      try = 1 #For avoiding retrying infinitely
-      begin
-        SmcGet.download("packages/#{@name}.yml", SmcGet.datadir + PACKAGE_SPECS_DIR + "#{@name}.yml") do |file, percent_done|
-          yield(file, percent_done, false) if block_given?
-        end
-      rescue Errors::DownloadFailedError => e
-        if try > max_tries
-          File.delete(SmcGet.datadir + PACKAGE_SPECS_DIR + "#{@name}.yml") #There is an empty file otherwise
-          if e.class == Errors::ConnectionTimedOutError
-            raise #Bubble up
-          else
-            raise(Errors::NoSuchPackageError.new(@name), "ERROR: Package not found in the repository: #{@name}.")
-          end
-        else
-          try += 1
-          yield(e.download_url, 0, e) if block_given?
-          retry
-        end
-      end
-      
-      pkgdata = YAML.load_file(SmcGet.datadir + PACKAGE_SPECS_DIR + "#{@name}.yml")
-      package_parts = [["levels", :level], ["music", :music], ["graphics", :graphic]]
-      
-      package_parts.each_with_index do |ary, i|
-        part, sym = ary
-        try = 1
-        
-        if pkgdata.has_key?(part)
-          pkgdata[part].each do |filename|
-            begin
-              SmcGet.download("#{part}/#{filename}", SmcGet.datadir + SmcGet.const_get(:"PACKAGE_#{part.upcase}_DIR") + filename) do |file, percent_done|
-                yield(file, percent_done, false) if block_given?
-              end
-            rescue Errors::DownloadFailedError => e
-              if try > max_tries
-                if e.class == Errors::ConnectionTimedOutError
-                  raise #Bubble up
-                else
-                  raise(Errors::NoSuchResourceError.new(sym, error.download_url), "ERROR: #{sym.capitalize} not found in the repository: #{filename}.")
-                end
-              else
-                try += 1
-                yield(e.download_url, 0, e) if block_given?
-                retry
-              end #if try > max_tries
-            end #begin
-          end #each part
-        end #has_key?
-      end #each part and sym
-    end #install
-    
-    # Uninstall a package from the local database. If a block is given,
-    # it is yielded the package part currently being deleted and
-    # how many percent of the files have already been deleted for the current package
-    # part.
-    def uninstall
-      package_file = SmcGet.datadir + PACKAGE_SPECS_DIR + "#{@name}.yml"
-      begin
-        pkgdata = YAML.load_file(package_file)
-      rescue Errno::ENOENT
-        raise(Errors::NoSuchPackageError.new(@name), "ERROR: Local package not found: #{@name}.")
-      end
-      
-      %w[music graphics levels].each_with_index do |part, part_index|
-        if pkgdata.has_key? part
-          total_files = pkgdata[part].count
-          pkgdata[part].each_with_index do |filename, index|
-            begin
-              File.delete(SmcGet.datadir + SmcGet.const_get("PACKAGE_#{part.upcase}_DIR") + filename)
-            rescue Errno::ENOENT
-            end
-            yield(part, ((index + 1) / total_files) * 100) if block_given? #+1, because index is 0-based
-          end
-        end
-      end
-      
-      #Delete the package file
-      File.delete(package_file)
-      
-      #Delete the directories the package file was placed in IF THEY'RE EMPTY.
-      rel_dir, file = package_file.relative_path_from(SmcGet.datadir + PACKAGE_SPECS_DIR).split
-      #rel_dir now holds the path difference between the package directory
-      #and the package spec file. If it is ".", no further dirs have been
-      #introduced.
-      return if rel_dir == Pathname.new(".")
-      #For simplifying the deletion procedure, we change the working directory
-      #to the package spec dir. Otherwise we'd have to keep track of both
-      #the absolute and relative paths, this way just of the latter.
-      Dir.chdir(SmcGet.datadir.join(PACKAGE_SPECS_DIR).to_s) do
-        #Remove from the inmost to the outmost directory, so that
-        #empty directories contained in directories just containg that
-        #empty directory don't get prohibited from deletion.
-        rel_dir.ascend do |dir|
-          dir.rmdir if dir.children.empty?
-        end
-      end
-      
-    end
-    
-    #Returns true if the package is installed locally. Returns false
-    #otherwise.
-    def installed?
-      SmcGet.datadir.join(PACKAGE_SPECS_DIR, "#{@name}.yml").file?
-    end
-    
-    #Get package information on a remote package. This method never
-    #retrieves any information from a locally installed package, look
-    #at #spec for that. Return value is the package specification in form
-    #of a hash.
-    #
-    #WARNING: This function is not thread-safe.
-    def getinfo
-      yaml = nil
-      Tempfile.open('pkgdata') do |tmp|
-        begin
-          SmcGet.download("packages/#{@name}.yml", tmp.path)
-        rescue Errors::DownloadFailedError
-          raise(Errors::NoSuchPackageError.new(@name), "ERROR: Package not found in the repository: #{@name}")
-        end
-        yaml = YAML.load_file(tmp.path)
-      end
-      return yaml
-    end
-    
-    #Retrieves the package specification from a locally installed package
-    #in form of a hash. In order to fetch information from a remote package,
-    #you have to use the #getinfo method.
-    def spec
-      if installed?
-        YAML.load_file(@spec_file)
-      else
-        raise(Errors::NoSuchPackageError, "ERROR: Package not installed locally: #@name.")
-      end
-    end
-    
-    #Returns the name of the package.
-    def to_s
-      @name
-    end
-    
-    #Human-readable description of form
-    #  #<SmcGet::Package package_name (installation_status)>
-    def inspect
-      "#<#{self.class} #{@name} (#{installed? ? 'installed' : 'not installed'})>"
-    end
-    
-  end
-  
-end
+#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
+  
+  #Packages are the main objects you will have to deal with. An instance of
+  #class Package encapsulates all known information from a smc package file
+  #(these files are described in the smcpak.rdoc file), and the most important
+  #attribute of this class is +spec+, which is your direct interface to the
+  #package’s specification by providing you with a fitting instance of class
+  #PackageSpecification.
+  #
+  #Apart from inspecting existing packages, you can also use the Package class
+  #to create new pacakges by calling the ::create method (inspecting a given
+  #package file is possible with ::from_file). ::create expects a path to
+  #the directoy which you want to compress into a new SMC package, validates
+  #it against the packaging guidelines and will then either fail or do
+  #the actual compression, outputting an instance of class Package that
+  #(you guessed it) describes the newly created SMC package.
+  #
+  #==Example of building a SMC package
+  #The following is an example that shows you how to build a basic
+  #SMC package by use of the ::create method.
+  #
+  #First you have to decide how you want to name your package. If you
+  #have decided (remember: This is a decision for life!), create a
+  #directory named after the package, note that it isn’t allowed to
+  #contain whitespace.
+  #
+  #Inside the directory, say you named it +cool+, create the following
+  #structure:
+  #
+  #  cool/
+  #    - cool.yml
+  #    - README.txt
+  #    levels/
+  #    music/
+  #    pixmaps/
+  #    sounds/
+  #    worlds/
+  #
+  #If your package doesn’t contain a specific component, e.g. sounds, you
+  #may ommit the corresponding directory.
+  #
+  #Then add all the levels you want to include in the package to the +levels+
+  #subdirectory, e.g. if you have a level named "awesome_1" and one named
+  #"awesome_2", copy them from your personal SMC directory (usually
+  #<b>~/.smc/levels</b>) so that your structure looks like this:
+  #
+  #  cool/
+  #    - cool.yml
+  #    - README.txt
+  #    levels/
+  #      - awesome_1.smclvl
+  #      - awesome_2.smclvl
+  #    music/
+  #    pixmaps/
+  #    sounds/
+  #    worlds/
+  #
+  #Now the most important step. Open up *cool.yml* in your favourite text
+  #editor and write the package specification. You can read about the exact
+  #format with all available options in the smcpak.rdoc file,but for now
+  #just write the following:
+  #
+  #  ---
+  #  title: Cool levels
+  #  last_update: 01-01-2011 04:07:00Z
+  #  levels:
+  #    - awesome_1.smclvl
+  #    - awesome_2.smclvl
+  #  authors:
+  #    - Your Name Here
+  #  difficulty: medium
+  #  description: |
+  #    Here goes your description
+  #    which may span multiple lines.
+  #
+  #Of course put something appropriate into the +last_update+ field
+  #(the format is DD-MM-YYYY hh:mm:ssZ, time zone is UTC).
+  #
+  #After you wrote something into your README.txt (whatever it is),
+  #you *could* build the package the easy way with
+  #  $ cd /path/to/dir/above/cool
+  #  $ smc-get build cool
+  #on the commandline. But I promised you to show the use of
+  #Package.create, so instead do:
+  #  $ cd /path/to/dir/above/cool
+  #  $ ruby -Ipath/to/smcget/lib -rsmc_get -e 'SmcGet::Package.create("cool")'
+  #Either way, you should now end up with a file called *cool.smcpak* in the
+  #parent directory of <b>cool/</b>.
+  class Package
+    
+    #A package name is considered valid if it matches this Regular
+    #expression.
+    VALID_PKG_NAME = /^[a-zA-Z_\-0-9]+$/
+    #Name of the directory the levels reside in the package.
+    LEVELS_DIR   = "levels"
+    #Name of the directory the music resides in the package.
+    MUSIC_DIR    = "music"
+    #Name of the directory the sounds reside in the package.
+    SOUNDS_DIR   = "sounds"
+    #Name of the dierctory the graphics reside in the pacakge.
+    GRAPHICS_DIR = "pixmaps"
+    #Name of the directory the worlds reside in the package.
+    WORLDS_DIR   = "worlds"
+    
+    #The PackageSpecification of this package.
+    attr_reader :spec
+    #The Pathname of the .smcpak file.
+    attr_reader :path
+    
+    class << self
+      
+      #Creates a new Package from a local .smcpak file.
+      #==Parameter
+      #[file] The path to the SMC package.
+      #==Return value
+      #An instance of class Package.
+      #==Example
+      #  pkg = SmcGet::Package.from_file("/home/freak/mycoolpackage.smcpak")
+      #==Remarks
+      #As this needs to decompress the package temporarily, this method
+      #may take some time to complete.
+      def from_file(file)
+        pkg_name = File.basename(file).sub(/\.smcpak$/, "")
+        #No spec file is provided, we therefore need to extract it from
+        #the archive.
+        path = PackageArchive.new(file).decompress(SmcGet.temp_dir) + pkg_name + "#{pkg_name}.yml"
+        new(path, file)
+      end
+
+      #Validates +directory+ against the packaging guidelines and compresses it
+      #into a .smcpak file.
+      #==Parameter
+      #[directory] The path to the directory you want to compress.
+      #==Return value
+      #An instance of this class describing the newly created package.
+      #==Example
+      #  pkg = SmcGet::Package.create("/home/freak/mycoollevels")
+      #==Remarks
+      #The .smcpak file is placed in the parent
+      #directory of +directory+, you should therefore ensure you have write
+      #permissions for it.
+      def create(directory)
+        #0. Determine the names of the important files
+        directory = Pathname.new(directory)
+        pkg_name = directory.basename.to_s
+        spec_file = directory + "#{pkg_name}.yml"
+        readme = directory + "README.txt"
+        smcpak_file = directory.parent + "#{pkg_name}.smcpak"
+        
+        #1. Validate the package name
+        raise(Errors::BrokenPackageError, "Invalid package name!") unless pkg_name =~ VALID_PKG_NAME
+        
+        #2. Validate the package spec
+        spec = PackageSpecification.from_file(spec_file) #Raises if necessary
+        
+        #3. Validate the rest of the structure
+        $stderr.puts("Warning: No README.txt found.") unless readme.file?
+        $stderr.puts("Warning: No levels found.") if spec.levels.empty?
+        
+        #4. Compress the whole thing
+        #The process is as follows: A temporary directory is created, in which
+        #a subdirectory that is named after the package is created. The
+        #spec, the README and the levels, music, etc. are then copied into
+        #that subdirectory which in turn is then compressed. The resulting
+        #.smcpak file is copied back to the original directory’s parent dir.
+        #After that, the mktmpdir block ends and deletes the temporary
+        #directory.
+        path = Dir.mktmpdir("smc-get-create-#{pkg_name}") do |tmpdir|
+          goal_dir = Pathname.new(tmpdir) + pkg_name
+          goal_dir.mkdir
+          
+          FileUtils.cp(spec_file, goal_dir)
+          FileUtils.cp(readme, goal_dir) if readme.file? #Optional
+          [:levels, :graphics, :music, :sounds, :worlds].each do |sym|
+            #4.1. Create the group’s subdir
+            dirname = const_get(:"#{sym.upcase}_DIR")
+            goal_group_dir = goal_dir + dirname
+            goal_group_dir.mkdir
+            #4.2. Copy all the group’s files over to it
+            spec[sym].each do |filename|
+              FileUtils.cp(directory + dirname + filename, goal_group_dir)
+            end
+          end
+          #4.3. actual compression
+          PackageArchive.compress(goal_dir, smcpak_file).path
+        end
+        #5. Return a new instance of Package
+        from_file(path)
+      end
+      
+    end
+
+    #Creates a new Package from the given specification file. You shouldn’t
+    #use this method directly, because you would duplicate the
+    #work the ::from_file method already does for you.
+    #==Parameters
+    #[spec_file]    The path to the YAML specification file.
+    #[pkg_location] The path to the SMC package.
+    #==Return value
+    #The newly created Package instance.
+    #==Example
+    #  pkg = SmcGet::Package.new("/home/freak/cool.yml", "/home/freak/cool.smcpak")
+    def initialize(spec_file, pkg_location)
+      @spec = PackageSpecification.from_file(spec_file)
+      @path = pkg_location
+    end
+    
+    #Decompresses this package.
+    #==Parameter
+    #[directory] Where to extract the SMC package to. A subdirectory named after
+    #            the package is automatically created in this directory.
+    #==Return value
+    #The Pathname to the created subdirectory.
+    #==Example
+    #  pkg.decompress(".") #=> /home/freak/cool
+    def decompress(directory)
+      PackageArchive.new(@path).decompress(directory)
+    end
+    
+    #Compares two packages. They’re considered equal if their package
+    #specifications are equal. See PackageSpecification#==.
+    def ==(other)
+      return false unless other.respond_to? :spec
+      @spec == other.spec
+    end
+
+    #Shorthand for:
+    #  pkg.spec.name
+    def to_s
+      @spec.name
+    end
+    
+    #Human-readabe description of form
+    #  #<SmcGet::Package <package name>>
+    def inspect
+      "#<#{self.class} #{@spec.name}>"
+    end
+    
+  end
+  
+end