amp 0.5.2 → 0.5.3

data/lib/amp/repository/abstract/abstract_local_repo.rb

@@ -0,0 +1,181 @@
+module Amp
+  module Repositories
+    ##
+    # This class contains the functionality of all repositories ever.
+    # Methods here rely on certain base methods that are unimplemented,
+    # left as an exercise for the reader.
+
+    class AbstractLocalRepository
+      include CommonLocalRepoMethods
+      
+      ##
+      # Returns the root of the repository (not the .hg/.git root)
+      #
+      # @return [String]
+      def root
+        raise NotImplementedError.new("root() must be implemented by subclasses of AbstractLocalRepository.")
+      end
+      
+      ##
+      # Returns the staging area for the repository, which provides the ability to add/remove
+      # files in the next commit.
+      #
+      # @return [AbstractStagingArea]
+      def staging_area
+        raise NotImplementedError.new("staging_area() must be implemented by subclasses of AbstractLocalRepository.")
+      end
+      
+      ##
+      # Has the file been modified from node1 to node2?
+      # 
+      # @param [String] file the file to check
+      # @param [Hash] opts needs to have :node1 and :node2
+      # @return [Boolean] has the +file+ been modified?
+      def file_modified?(file, opts={})
+        raise NotImplementedError.new("file_modified?() must be implemented by subclasses of AbstractLocalRepository.")
+      end
+      
+      ##
+      # Write +text+ to +filename+, where +filename+
+      # is local to the root.
+      #
+      # @param [String] filename The file as relative to the root
+      # @param [String] text The text to write to said file
+      def working_write(filename, text)
+        raise NotImplementedError.new("working_write() must be implemented by subclasses of AbstractLocalRepository.")
+      end
+      
+      ##
+      # Commits a changeset or set of files to the repository. You will quite often
+      # use this method since it's basically the basis of version control systems.
+      #
+      # @api
+      # @param [Hash] opts the options to this method are all optional, so it's a very
+      #   flexible method. Options listed below.
+      # @option opts [Array] :modified ([]) which files have been added or modified
+      #   that you want to be added as a changeset.
+      # @option opts [Array] :removed ([]) which files should be removed in this
+      #   commit?
+      # @option opts [Hash] :extra ({}) any extra data, such as "close" => true
+      #   will close the active branch.
+      # @option opts [String] :message ("") the message for the commit. An editor
+      #   will be opened if this is not provided.
+      # @option opts [Boolean] :force (false) Forces the commit, ignoring minor details
+      #   like when you try to commit when no files have been changed.
+      # @option opts [Match] :match (nil) A match object to specify how to pick files
+      #   to commit. These are useful so you don't accidentally commit ignored files,
+      #   for example.
+      # @option opts [Array<String>] :parents (nil) the node IDs of the parents under
+      #   which this changeset will be committed. No more than 2 for mercurial.
+      # @option opts [Boolean] :empty_ok (false) Is an empty commit message a-ok?
+      # @option opts [Boolean] :force_editor (false) Do we force the editor to be
+      #   opened, even if :message is provided?
+      # @option opts [String] :user (ENV["HGUSER"]) the username to associate with the commit.
+      #   Defaults to AmpConfig#username.
+      # @option opts [DateTime, Time, Date] :date (Time.now) the date to mark with
+      #   the commit. Useful if you miss a deadline and want to pretend that you actually
+      #   made it!
+      # @return [String] the digest referring to this entry in the changelog
+      def commit(opts={})
+        raise NotImplementedError.new("commit() must be implemented by subclasses of AbstractLocalRepository.")
+      end
+  
+      ##
+      # Pushes changesets to a remote repository.
+      #
+      # @param [Repository] remote_repo the remote repository object to push to
+      # @param [Hash] options extra options for pushing
+      # @option options [Boolean] :force (false) Force pushing, even if it would create
+      #   new heads (or some other error arises)
+      # @option options [Array<Fixnum, String>] :revs ([]) specify which revisions to push
+      # @return [Boolean] for success/failure
+      def push(remote_repo, options = {})
+        raise NotImplementedError.new("push() must be implemented by subclasses of AbstractLocalRepository.")
+      end
+
+      ##
+      # Pulls changesets from a remote repository 
+      # Does *not* apply them to the working directory.
+      #
+      # @param [Repository] remote_repo the remote repository object to pull from
+      # @param [Hash] options extra options for pulling
+      # @option [Array<String, Fixnum>] :heads ([]) which repository heads to pull, such as
+      #   a branch name or a sha-1 identifier
+      # @option [Boolean] :force (false) force the pull, ignoring any errors or warnings
+      # @return [Boolean] for success/failure
+      def pull(remote_repo, options = {})
+        raise NotImplementedError.new("pull() must be implemented by subclasses of AbstractLocalRepository.")
+      end
+  
+      ##
+      # Returns a changeset for the given revision.
+      # Must support at least integer indexing as well as a string "node ID", if the repository
+      # system has such IDs. Also "tip" should return the tip of the revision tree.
+      #
+      # @return [AbstractChangeset]
+      def [](revision)
+        raise NotImplementedError.new("[]() must be implemented by subclasses of AbstractLocalRepository.")
+      end
+  
+      ##
+      # Returns the number of changesets in the repository.
+      #
+      # @return [Fixnum]
+      def size
+        raise NotImplementedError.new("size() must be implemented by subclasses of AbstractLocalRepository.")
+      end
+  
+      ##
+      # Gets a given file at the given revision, in the form of an AbstractVersionedFile object.
+      #
+      # @return [AbstractVersionedFile]
+      def get_file(file, revision)
+        raise NotImplementedError.new("get_file() must be implemented by subclasses of AbstractLocalRepository.")
+      end
+  
+      ##
+      # In whatever conflict-resolution system your repository format defines, mark a given file
+      # as in conflict. If your format does not manage conflict resolution, re-define this method as
+      # a no-op.
+      #
+      # @return [Boolean]
+      def mark_conflicted(*filenames)
+        raise NotImplementedError.new("mark_conflicted() must be implemented by subclasses of AbstractLocalRepository.")
+      end
+  
+      ##
+      # In whatever conflict-resolution system your repository format defines, mark a given file
+      # as no longer in conflict (resolved). If your format does not manage conflict resolution,
+      # re-define this method as a no-op.
+      #
+      # @return [Boolean]
+      def mark_resolved(*filenames)
+        raise NotImplementedError.new("mark_resolved() must be implemented by subclasses of AbstractLocalRepository.")
+      end
+      
+      ##
+      # Attempts to resolve the given file, according to how mercurial manages
+      # merges. Needed for api compliance.
+      #
+      # @api
+      # @param [String] filename the file to attempt to resolve
+      def try_resolve_conflict
+        raise NotImplementedError.new("try_resolve_conflict() must be implemented by subclasses of AbstractLocalRepository.")
+      end
+      
+      ##
+      # Returns all files that have not been merged. In other words, if we're 
+      # waiting for the user to fix up their merge, then return the list of files
+      # we need to be correct before merging.
+      #
+      # @todo think up a better name
+      #
+      # @return [Array<Array<String, Symbol>>] an array of String-Symbol pairs - the
+      #   filename is the first entry, the status of the merge is the second.
+      def uncommitted_merge_files
+        raise NotImplementedError.new("uncommitted_merge_files() must be implemented by subclasses of AbstractLocalRepository.")
+      end
+      
+    end
+  end
+end

data/lib/amp/repository/abstract/abstract_staging_area.rb

@@ -0,0 +1,180 @@
+module Amp
+  module Repositories
+    class AbstractStagingArea
+      include CommonStagingAreaMethods
+      
+      ##
+      # Marks a file to be added to the repository upon the next commit.
+      # 
+      # @param [[String]] filenames a list of files to add in the next commit
+      # @return [Boolean] true for success, false for failure
+      def add(*filenames)
+        raise NotImplementedError.new("add() must be implemented by subclasses of AbstractStagingArea.")
+      end
+      
+      ##
+      # Marks a file to be removed from the repository upon the next commit. Last argument
+      # can be a hash, which can take an :unlink key, specifying whether the files should actually
+      # be removed or not.
+      # 
+      # @param [[String]] filenames a list of files to remove in the next commit
+      # @return [Boolean] true for success, false for failure
+      def remove(*filenames)
+        raise NotImplementedError.new("remove() must be implemented by subclasses of AbstractStagingArea.")
+      end
+        
+      ##
+      # Set +file+ as normal and clean. Un-removes any files marked as removed, and
+      # un-adds any files marked as added.
+      # 
+      # @param  [Array<String>] files the name of the files to mark as normal
+      # @return [Boolean] success marker
+      def normal(*files)
+        raise NotImplementedError.new("normal() must be implemented by subclasses of AbstractStagingArea.")
+      end
+      
+      ##
+      # Mark the files as untracked.
+      # 
+      # @param  [Array<String>] files the name of the files to mark as untracked
+      # @return [Boolean] success marker
+      def forget(*files)
+        raise NotImplementedError.new("forget() must be implemented by subclasses of AbstractStagingArea.")
+      end
+      
+      ##
+      # Marks a file to be copied from the +from+ location to the +to+ location
+      # in the next commit, while retaining history.
+      # 
+      # @param [String] from the source of the file copy
+      # @param [String] to the destination of the file copy
+      # @return [Boolean] true for success, false for failure
+      def copy(from, to)
+        raise NotImplementedError.new("copy() must be implemented by subclasses of AbstractStagingArea.")
+      end
+      
+      ##
+      # Marks a file to be moved from the +from+ location to the +to+ location
+      # in the next commit, while retaining history.
+      # 
+      # @param [String] from the source of the file move
+      # @param [String] to the destination of the file move
+      # @return [Boolean] true for success, false for failure
+      def move(from, to)
+        raise NotImplementedError.new("move() must be implemented by subclasses of AbstractStagingArea.")
+      end
+      
+      ##
+      # Marks a modified file to be included in the next commit.
+      # If your VCS does this implicitly, this should be defined as a no-op.
+      # 
+      # @param [[String]] filenames a list of files to include for committing
+      # @return [Boolean] true for success, false for failure
+      def include(*filenames)
+        raise NotImplementedError.new("include() must be implemented by subclasses of AbstractStagingArea.")
+      end
+      alias_method :stage, :include
+      
+      ##
+      # Mark a modified file to not be included in the next commit.
+      # If your VCS does not include this idea because staging a file is implicit, this should
+      # be defined as a no-op.
+      # 
+      # @param [[String]] filenames a list of files to remove from the staging area for committing
+      # @return [Boolean] true for success, false for failure
+      def exclude(*filenames)
+        raise NotImplementedError.new("exclude() must be implemented by subclasses of AbstractStagingArea.")
+      end
+      alias_method :unstage, :exclude
+      
+      ##
+      # Returns a Symbol.
+      # Possible results:
+      # :added (subset of :included)
+      # :removed
+      # :untracked
+      # :included
+      # :normal
+      #
+      def file_status(filename)
+        raise NotImplementedError.new("file_status() must be implemented by subclasses of AbstractStagingArea.")
+      end
+      
+      ##
+      # The directory used by the VCS to store magical information (.hg, .git, etc.).
+      #
+      # @api
+      # @return [String] relative to root
+      def vcs_dir
+        raise NotImplementedError.new("vcs_dir() must be implemented by subclasses of AbstractStagingArea.")
+      end
+      
+      
+      ##
+      # Returns all files tracked by the repository *for the working directory* - not
+      # to be confused with the most recent changeset.
+      #
+      # @api
+      # @return [Array<String>] all files tracked by the repository at this moment in
+      #   time, including just-added files (for example) that haven't been committed yet.
+      def all_files
+        raise NotImplementedError.new("all_files() must be implemented by subclasses of AbstractStagingArea.")
+      end
+      
+      ##
+      # Returns whether the given directory is being ignored. Optional method - defaults to
+      # +false+ at all times.
+      #
+      # @api-optional
+      # @param [String] directory the directory to check against ignoring rules
+      # @return [Boolean] are we ignoring this directory?
+      def ignoring_directory?(directory)
+        false
+      end
+      
+      ##
+      # Returns whether the given file is being ignored. Optional method - defaults to
+      # +false+ at all times.
+      #
+      # @api-optional
+      # @param [String] file the file to check against ignoring rules
+      # @return [Boolean] are we ignoring this file?
+      def ignoring_file?(file)
+        false
+      end
+      
+      ##
+      # Does a detailed look at a file, to see if it is clean, modified, or needs to have its
+      # content checked precisely.
+      #
+      # Supplements the built-in #status command so that its output will be cleaner.
+      #
+      # Defaults to report files as normal - it cannot check if a file has been modified
+      # without this method being overridden.
+      #
+      # @api-optional
+      #
+      # @param [String] file the filename to look up
+      # @param [File::Stats] st the current results of File.lstat(file)
+      # @return [Symbol] a symbol representing the current file's status
+      def file_precise_status(file, st)
+        return :lookup
+      end
+      
+      ##
+      # Calculates the difference (in bytes) between a file and its last tracked state.
+      #
+      # Defaults to zero - in other words, it deactivates the delta feature.
+      #
+      # @api-optional
+      # @param [String] file the filename to look up
+      # @param [File::Stats] st the current results of File.lstat(file)
+      # @return [Fixnum] the number of bytes difference between the file and
+      #  its last tracked state.
+      def calculate_delta(file, st)
+        0
+      end
+      
+    end
+  end
+end

data/lib/amp/repository/abstract/abstract_versioned_file.rb

@@ -0,0 +1,100 @@
+module Amp
+  module Repositories
+    class AbstractVersionedFile
+      include CommonVersionedFileMethods
+      
+      ##
+      # The changeset to which this versioned file belongs.
+      # 
+      # @return [AbstractChangeset]
+      def changeset
+        raise NotImplementedError.new("changeset() must be implemented by subclasses of AbstractVersionedFile.")
+      end
+      
+      ##
+      # The repo to which this {VersionedFile} belongs
+      # 
+      # @return [AbstractLocalRepository]
+      def repo
+        raise NotImplementedError.new("repo() must be implemented by subclasses of AbstractVersionedFile.")
+      end
+      alias_method :repository, :repo
+      
+      ##
+      # The path to this file
+      # 
+      # @return [String]
+      def path
+        raise NotImplementedError.new("path() must be implemented by subclasses of AbstractVersionedFile.")
+      end
+      
+      ##
+      # The revision of the file. This can be vague, so let me explain:
+      # This is the revision of the repo from which this VersionedFile is.
+      # If this is unclear, please submit a patch fixing it.
+      # 
+      # @return [Integer]
+      def revision
+        raise NotImplementedError.new("revision() must be implemented by subclasses of AbstractVersionedFile.")
+      end
+      
+      ##
+      # The size of this file
+      # 
+      # @return [Integer]
+      def size
+        raise NotImplementedError.new("size() must be implemented by subclasses of AbstractVersionedFile.")
+      end
+      
+      ##
+      # The contents of a file at the given revision
+      # 
+      # @return [String] the data at the current revision
+      def data
+        raise NotImplementedError.new("data() must be implemented by subclasses of AbstractVersionedFile.")
+      end
+      
+      ##
+      # The hash value for sticking this fucker in a hash.
+      # 
+      # @return [Integer]
+      def hash
+        raise NotImplementedError.new("hash() must be implemented by subclasses of AbstractVersionedFile.")
+      end
+      
+      ##
+      # Has this file been renamed? If so, return some useful info
+      def renamed?
+        raise NotImplementedError.new("renamed() must be implemented by subclasses of AbstractVersionedFile.")
+      end
+      
+      ##
+      # Compares to either a bit of text or another versioned file.
+      # Returns true if different, false for the same.
+      # (much like <=> == 0 for the same)
+      # 
+      # @param [AbstractVersionedFile, String] item what we're being compared to
+      # @return [Boolean] true if different, false if same.
+      def cmp(item)
+        raise NotImplementedError.new("cmp() must be implemented by subclasses of AbstractVersionedFile.")
+      end
+      
+      ##
+      # Are two versioned files the same? This means same path and revision indexes.
+      # 
+      # @param [AbstractVersionedFile] vfile what we're being compared to
+      # @return [Boolean]
+      def ==(vfile)
+        raise NotImplementedError.new("==() must be implemented by subclasses of AbstractVersionedFile.")
+      end
+      
+      ##
+      # Gets the flags for this file ('x', 'l', or '')
+      # 
+      # @return [String] 'x', 'l', or ''
+      def flags
+        raise NotImplementedError.new("flags() must be implemented by subclasses of AbstractVersionedFile.")
+      end
+    end
+  end
+end