# 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)])