使用Subversion库API开发应用
使用API
使用Subversion库API开发应用看起来相当的直接，所有的公共头文件放在源文件的subversion/include目录，从源代码编译和安装Subversion本身，需要这些头文件拷贝到系统位置。这些头文件包括了所有用户可以访问的功能和类型。
你首先应该注意Subversion的数据类型和方法是命名空间保护的，每一个公共Subversion对象名以svn_开头，然后紧跟一个这个对象定义（如wc、client和fs其他）所在的库的简短编码，然后是一个下划线（_）和后面的对象名称。半公开的方法（库使用，但是但库之外代码不可以使用并且只可以在库自己的目录看到）与这个命名模式不同，并不是库代码之后紧跟一个下划线，他们是用两个下划线（__）。给定源文件的私有方法没有特殊前缀，使用static声明。当然，一个编译器不会关心命名习惯，只是用来区分给定方法或数据类型。
Apache可移植运行库
伴随Subversion自己的数据类型，你会看到许多apr开头的数据类型引用—来自Apache可移植运行库（APR）的对象。APR是Apache可移植运行库，源自为了服务器代码的多平台性，尝试将不同的操作系统特定字节与操作系统无关代码隔离。结果就提供了一个基础API的库，只有一些适度区别—或者是广泛的—来自各个操作系统。Apache HTTP服务器很明显是APR库的第一个用户，Subversion开发者立刻发现了使用APR库的价值。意味着Subversion没有操作系统特定的代码，也意味着Subversion客户端可以在Server存在的平台编译和运行。当前这个列表包括，各种类型的Unix、Win32、OS/2和Mac OS X。
除了提供了跨平台一致的系统调用， [44] APR给Subversion对多种数据类型有快速的访问，如动态数组和哈希表。Subversion在代码中广泛使用这些类型，但是或许大多数普遍深入的APR数据类型可以在所有的Subversion的API原型中发现，是apr_pool_t—APR内存池，Subversion使用内部缓冲池用来进行内存分配（除非外部库在API传递参数时需要一个不同的内存管理模式）， [45] 而且一个人如果针对Subversion的API编码不需要做同样的事情，他们可以在需要时给API提供缓冲池，这意味着Subversion的API使用者也必须链接到APR，必须调用apr_initialize()来初始化APR字系统，然后必须得到一个缓冲池用来进行Subversion的API调用。详情见“使用内存池编程”一节。
URL和路径需求
因为分布式版本控制操作是Subversion存在的重点，有意义来关注一下国际化（i18n）支持。毕竟，当“分布式”或许意味着“横跨办公室”，它也意味着“横跨全球”。为了更容易一点，Subversion的所有公共接口只接受路径参数,这些参数是传统的，使用UTF-8编码。这意味着，举个例子，任何新的使用libsvn_client接口客户端库，在把这些参数传递给Subversion库前，需要首先将路径从本地代码转化为UTF-8代码，然后将Subversion传递回来的路径转换为本地代码，很幸运，Subversion提供了一组任何程序可以使用的转化方法（见subversion/include/svn_utf.h）。
同样，Subversion的API需要所有的URL参数是正确的URI编码，所以，我们不会传递file:///home/username/My File.txt作为My File.txt的URL，而会传递file:///home/username/My%20File.txt。再次，Subversion提供了一些你可以使用的助手方法—svn_path_uri_encode()和svn_path_uri_decode()，分别用来URI的编码和解码。
使用C和C++以外的语言
除C语言以外，如果你对使用其他语言结合Subversion库感兴趣—如Python脚本或是Java应用—Subversion通过简单包裹生成器（SWIG）提供了最初的支持。Subversion的SWIG绑定位于subversion/bindings/swig，并且慢慢的走向成熟进入可用状态。这个绑定允许你直接调用Subversion的API方法，使用包裹器会把脚本数据类型转化为Subversion需要的C语言库类型。
通过语言绑定访问Subversion的API有一个明显的好处—简单性。通常来讲，Python和Perl之类的语言比C和C++更加的灵活和简单，这些语言的高级数据类型和上下文驱动类型更加易于处理用户提供的信息，就像你知道的，人们精于把程序搞坏，脚本语言可以更优雅的处理这些错误信息，当然，灵活性经常带来性能的损失，这就是为什么使用紧密优化的，C基础的接口和库组件，然后与一种高效的、灵活的绑定语言，是这样的吸引人。
让我们看看Subversion的Python SWIG绑定的实例，这个例子迭代遍历最新的修订版本，并且打印遍历到的路径。
例 8.2. 使用Python处理版本库层
#!/usr/bin/python
"""Crawl a repository, printing versioned object path names."""
import sys
import os.path
import svn.fs, svn.core, svn.repos
def crawl_filesystem_dir(root, directory, pool):
"""Recursively crawl DIRECTORY under ROOT in the filesystem, and return
a list of all the paths at or below DIRECTORY. Use POOL for all
allocations."""
# Print the name of this path.
print directory + "/"
# Get the directory entries for DIRECTORY.
entries = svn.fs.svn_fs_dir_entries(root, directory, pool)
# Use an iteration subpool.
subpool = svn.core.svn_pool_create(pool)
# Loop over the entries.
names = entries.keys()
for name in names:
# Clear the iteration subpool.
svn.core.svn_pool_clear(subpool)
# Calculate the entry's full path.
full_path = directory + '/' + name
# If the entry is a directory, recurse. The recursion will return
# a list with the entry and all its children, which we will add to
# our running list of paths.
if svn.fs.svn_fs_is_dir(root, full_path, subpool):
crawl_filesystem_dir(root, full_path, subpool)
else:
# Else it's a file, so print its path here.
print full_path
# Destroy the iteration subpool.
svn.core.svn_pool_destroy(subpool)
def crawl_youngest(pool, repos_path):
"""Open the repository at REPOS_PATH, and recursively crawl its
youngest revision."""
# Open the repository at REPOS_PATH, and get a reference to its
# versioning filesystem.
repos_obj = svn.repos.svn_repos_open(repos_path, pool)
fs_obj = svn.repos.svn_repos_fs(repos_obj)
# Query the current youngest revision.
youngest_rev = svn.fs.svn_fs_youngest_rev(fs_obj, pool)
# Open a root object representing the youngest (HEAD) revision.
root_obj = svn.fs.svn_fs_revision_root(fs_obj, youngest_rev, pool)
# Do the recursive crawl.
crawl_filesystem_dir(root_obj, "", pool)
if __name__ == "__main__":
# Check for sane usage.
if len(sys.argv) != 2:
sys.stderr.write("Usage: %s REPOS_PATH\n"
% (os.path.basename(sys.argv[0])))
sys.exit(1)
# Canonicalize (enough for Subversion, at least) the repository path.
repos_path = os.path.normpath(sys.argv[1])
if repos_path == '.':
repos_path = ''
# Call the app-wrapper, which takes care of APR initialization/shutdown
# and the creation and cleanup of our top-level memory pool.
svn.core.run_app(crawl_youngest, repos_path)
同样的C程序为表示路径和条目的hash需要处理自定义的数据类型（例如APR提供的库），但是Python有hash（叫做“dictionaries”），并且是内置数据类型，而且还提供了一系列操作这些类型的函数，所以SWIG（通过Subversion的语言绑定层的自定义帮助）要小心的将这些自定义数据类型映射到目标语言的数据类型，这为目标语言的用户提供了一个更加直观的接口。
Subversion的Python绑定也可以用来进行工作拷贝的操作，在本章前面的小节中，我们提到过libsvn_client接口，它存在的目的就是简化编写Subversion客户端的难度，下面是一个例子，讲的是如何使用SWIG绑定创建一个扩展的svn status命令。
例 8.3. A Python Status Crawler
#!/usr/bin/env python
"""Crawl a working copy directory, printing status information."""
import sys
import os.path
import getopt
import svn.core, svn.client, svn.wc
def generate_status_code(status):
"""Translate a status value into a single-character status code,
using the same logic as the Subversion command-line client."""
if status == svn.wc.svn_wc_status_none:
return ' '
if status == svn.wc.svn_wc_status_normal:
return ' '
if status == svn.wc.svn_wc_status_added:
return 'A'
if status == svn.wc.svn_wc_status_missing:
return '!'
if status == svn.wc.svn_wc_status_incomplete:
return '!'
if status == svn.wc.svn_wc_status_deleted:
return 'D'
if status == svn.wc.svn_wc_status_replaced:
return 'R'
if status == svn.wc.svn_wc_status_modified:
return 'M'
if status == svn.wc.svn_wc_status_merged:
return 'G'
if status == svn.wc.svn_wc_status_conflicted:
return 'C'
if status == svn.wc.svn_wc_status_obstructed:
return '~'
if status == svn.wc.svn_wc_status_ignored:
return 'I'
if status == svn.wc.svn_wc_status_external:
return 'X'
if status == svn.wc.svn_wc_status_unversioned:
return '?'
return '?'
def do_status(pool, wc_path, verbose):
# Calculate the length of the input working copy path.
wc_path_len = len(wc_path)
# Build a client context baton.
ctx = svn.client.svn_client_ctx_t()
def _status_callback(path, status, root_path_len=wc_path_len):
"""A callback function for svn_client_status."""
# Print the path, minus the bit that overlaps with the root of
# the status crawl
text_status = generate_status_code(status.text_status)
prop_status = generate_status_code(status.prop_status)
print '%s%s %s' % (text_status, prop_status, path[wc_path_len + 1:])
# Do the status crawl, using _status_callback() as our callback function.
svn.client.svn_client_status(wc_path, None, _status_callback,
1, verbose, 0, 0, ctx, pool)
def usage_and_exit(errorcode):
"""Print usage message, and exit with ERRORCODE."""
stream = errorcode and sys.stderr or sys.stdout
stream.write("""Usage: %s OPTIONS WC-PATH
Options:
--help, -h : Show this usage message
--verbose, -v : Show all statuses, even uninteresting ones
""" % (os.path.basename(sys.argv[0])))
sys.exit(errorcode)
if __name__ == '__main__':
# Parse command-line options.
try:
opts, args = getopt.getopt(sys.argv[1:], "hv", ["help", "verbose"])
except getopt.GetoptError:
usage_and_exit(1)
verbose = 0
for opt, arg in opts:
if opt in ("-h", "--help"):
usage_and_exit(0)
if opt in ("-v", "--verbose"):
verbose = 1
if len(args) != 1:
usage_and_exit(2)
# Canonicalize (enough for Subversion, at least) the working copy path.
wc_path = os.path.normpath(args[0])
if wc_path == '.':
wc_path = ''
# Call the app-wrapper, which takes care of APR initialization/shutdown
# and the creation and cleanup of our top-level memory pool.
svn.core.run_app(do_status, wc_path, verbose)
非常不幸，Subversion的语言绑定缺乏对核心Subversion模块的关注，但是，花了很多力气处理创建针对Python、Perl和Ruby的绑定，在一定程度上，在这些接口上的工作量可以在其他语言的SWIG（包括C#、Guile、Java、MzScheme、OCaml、PHP、Tcl等等）接口上得到重用。然而，一些接口仍然需要额外的编程工作，关于SWIG本身的更多信息可以看项目的网站http://www.swig.org/。
--------------------------------------------------------------------------------
[44] Subversion使用尽可能多ANSI系统调用和数据类型。
[45] Neon和Berkeley DB就是这种库的例子。
