# Copyright 2009 the Melange authors.

#

# Licensed under the Apache License, Version 2.0 (the "License");

# you may not use this file except in compliance with the License.

# You may obtain a copy of the License at

#

#   http://www.apache.org/licenses/LICENSE-2.0

#

# Unless required by applicable law or agreed to in writing, software

# distributed under the License is distributed on an "AS IS" BASIS,

# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

# See the License for the specific language governing permissions and

# limitations under the License.

"""Subversion commandline wrapper.

This module provides access to a restricted subset of the Subversion

commandline tool. The main functionality offered is an object wrapping

a working copy, providing version control operations within that

working copy.

A few standalone commands are also implemented to extract data from

arbitrary remote repositories.

"""

__authors__ = [

    # alphabetical order by last name, please

    '"David Anderson" <dave@natulte.net>',

    ]

import error

import util

def export(url, revision, dest_path):

  """Export the contents of a repository to a local path.

  Note that while the underlying 'svn export' only requires a URL, 

  we require that both a URL and a revision be specified, to fully

  qualify the data to export.

  Args:

    url: The repository URL to export.

    revision: The revision to export.

    dest_path: The destination directory for the export. Note that

      this is an absolute path, NOT a working copy relative path.

    """

  assert os.path.isabs(dest_path)

  if os.path.exists(dest_path):

    raise error.ObstructionError('Cannot export to obstructed path %s' %

                                 dest_path)

  util.run(['svn', 'export', '-r', str(revision), url, dest_path])

def find_tag_rev(url):

  """Return the revision at which a remote tag was created.

  Since tags are immutable by convention, usually the HEAD of a tag

  should be the tag creation revision. However, mistakes can happen,

  so this function will walk the history of the given tag URL,

  stopping on the first revision that was created by copy.

  This detection is not foolproof. For example: it will be fooled by a

  tag that was created, deleted, and recreated by copy at a different

  revision. It is not clear what the desired behavior in these edge

  cases are, and no attempt is made to handle them. You should request

  user confirmation before using the result of this function.

  Args:

    url: The repository URL of the tag to examine.

  """

  try:

    output = util.run(['svn', 'log', '-q', '--stop-on-copy', url],

                      capture=True)

  except util.SubprocessFailed:

    raise error.ExpectationFailed('No tag at URL ' + url)

  first_rev_line = output[-2]

  first_rev = int(first_rev_line.split()[0][1:])

  return first_rev

def diff(url, revision):

  """Retrieve a revision from a remote repository as a unified diff.

  Args:

    url: The repository URL on which to perform the diff.

    revision: The revision to extract at the given url.

  Returns:

    A string containing the changes extracted from the remote

    repository, in unified diff format suitable for application using

    'patch'.

  """

  try:

    return util.run(['svn', 'diff', '-c', str(revision), url],

                    capture=True, split_capture=False)

  except util.SubprocessFailed:

    raise error.ExpectationFailed('Could not get diff for r%d '

                                  'from remote repository' % revision)

class WorkingCopy(util.Paths):

  """Wrapper for operations on a Subversion working copy.

  An instance of this class is bound to a specific working copy

  directory, and provides an API to perform various Subversion

  operations on this working copy.

  Some methods take a 'depth' argument. Depth in Subversion is a

  feature that allows the creation of arbitrarily shallow or deep

  working copies on a per-directory basis. Possible values are

  'none' (no files or directories), 'files' (only files in .),

  'immediates' (files and directories in ., directories checked out

  at depth 'none') or 'infinity' (a normal working copy with

  everything).

  Note that this wrapper also doubles as a Paths object, offering an

  easy way to get or check the existence of paths in the working

  copy.

  """

  def __init__(self, wc_dir):

    util.Paths.__init__(self, wc_dir)

  def _unknownAndMissing(self, path):

    """Returns lists of unknown and missing files in the working copy.

    Args:

      path: The working copy path to scan.

    Returns:

      Two lists. The first is a list of all unknown paths

      (subversion has no knowledge of them), the second is a list

      of missing paths (subversion knows about them, but can't

      find them). Paths in either list are relative to the input

      path.

    """

    assert self.exists()

    unknown = []

    missing = []

    for line in self.status(path):

      if not line.strip():

        continue

      if line[0] == '?':

        unknown.append(line[7:])

      elif line[0] == '!':

        missing.append(line[7:])

    return unknown, missing

  def checkout(self, url, depth='infinity'):

    """Check out a working copy from the given URL.

    Args:

      url: The Subversion repository URL to check out.

      depth: The depth of the working copy root.

    """

    assert not self.exists()

    util.run(['svn', 'checkout', '--depth=' + depth, url, self.path()])

  def update(self, path='', depth=None):

    """Update a working copy path, optionally changing depth.

    Args:

      path: The working copy path to update.

      depth: If set, change the depth of the path before updating.

    """

    assert self.exists()

    if depth is None:

      util.run(['svn', 'update', self.path(path)])

    else:

      util.run(['svn', 'update', '--set-depth=' + depth, self.path(path)])

  def revert(self, path=''):

    """Recursively revert a working copy path.

    Note that this command is more zealous than the 'svn revert'

    command, as it will also delete any files which subversion

    does not know about.

    """

    util.run(['svn', 'revert', '-R', self.path(path)])

    unknown, missing = self._unknownAndMissing(path)

    unknown = [os.path.join(self.path(path), p) for p in unknown]

    if unknown:

      # rm -rf makes me uneasy. Verify that all paths to be deleted

      # are within the release working copy.

      for p in unknown:

        assert p.startswith(self.path())

      util.run(['rm', '-rf', '--'] + unknown)

  def ls(self, dir=''):

    """List the contents of a working copy directory.

    Note that this returns the contents of the directory as seen

    by the server, not constrained by the depth settings of the

    local path.

    """

    assert self.exists()

    return util.run(['svn', 'ls', self.path(dir)], capture=True)

  def copy(self, src, dest):

    """Copy a working copy path.

    The copy is only scheduled for commit, not committed.

    Args:

      src: The source working copy path.

      dst: The destination working copy path.

    """

    assert self.exists()

    util.run(['svn', 'cp', self.path(src), self.path(dest)])

  def propget(self, prop_name, path):

    """Get the value of a property on a working copy path.

    Args:

      prop_name: The property name, eg. 'svn:externals'.

      path: The working copy path on which the property is set.

    """

    assert self.exists()

    return util.run(['svn', 'propget', prop_name, self.path(path)],

            capture=True)

  def propset(self, prop_name, prop_value, path):

    """Set the value of a property on a working copy path.

    The property change is only scheduled for commit, not committed.

    Args:

      prop_name: The property name, eg. 'svn:externals'.

      prop_value: The value that should be set.

      path: The working copy path on which to set the property.

    """

    assert self.exists()

    util.run(['svn', 'propset', prop_name, prop_value, self.path(path)])

  def add(self, paths):

    """Schedule working copy paths for addition.

    The paths are only scheduled for addition, not committed.

    Args:

      paths: The list of working copy paths to add.

    """

    assert self.exists()

    paths = [self.path(p) for p in paths]

    util.run(['svn', 'add'] + paths)

  def remove(self, paths):

    """Schedule working copy paths for deletion.

    The paths are only scheduled for deletion, not committed.

    Args:

      paths: The list of working copy paths to delete.

    """

    assert self.exists()

    paths = [self.path(p) for p in paths]

    util.run(['svn', 'rm'] + paths)

  def status(self, path=''):

    """Return the status of a working copy path.

    The status returned is the verbatim output of 'svn status' on

    the path.

    Args:

      path: The path to examine.

    """

    assert self.exists()

    return util.run(['svn', 'status', self.path(path)], capture=True)

  def addRemove(self, path=''):

    """Perform an "addremove" operation a working copy path.

    An "addremove" runs 'svn status' and schedules all the unknown

    paths (listed as '?') for addition, and all the missing paths

    (listed as '!') for deletion. Its main use is to synchronize

    working copy state after applying a patch in unified diff

    format.

    Args:

      path: The path under which unknown/missing files should be

        added/removed.

    """

    assert self.exists()

    unknown, missing = self._unknownAndMissing(path)

    if unknown:

      self.add(unknown)

    if missing:

      self.remove(missing)

  def commit(self, message, path=''):

    """Commit scheduled changes to the source repository.

    Args:

      message: The commit message to use.

      path: The path to commit.

    """

    assert self.exists()

    util.run(['svn', 'commit', '-m', message, self.path(path)])