Module SubLua

Lua binding to SubCpp - a C++ Subversion library.

Usage:

    local SubLua = require( "SubLua" )
local svn = SubLua.new( { username = "user", password = "my_password" } )

Info:

  • Release: 1.00 <04/21/2012>
  • License: MIT/X11
  • Author: Ryan P.

Functions

new (options) Create a new SVN client to work with.
SubLua:Cat (path, options) Output the content of specified files or URLs.
SubLua:Upgrade (path) Upgrade the working copy format of the specified path.
SubLua:GetWorkingCopyFormatVersion (path) Get the format version of the working copy at the specified path.
SubLua:Checkout (url, path, options) Checks out a working copy from a url to a path.
SubLua:Update (path, options) Updates the file or directory.
SubLua:Export (srcPath, destPath, options) Create an unversioned copy of a tree.
SubLua:Get (path, destPath, options) Retrieves the contents for a specific revision of a path and saves it to the destination file dstPath.
SubLua:Add (path, options) Schedule a working copy path for addition to the repository.
SubLua:Import (path, url, message, options) Commit an unversioned file or tree into the repository.
SubLua:MkDir (path, message) Create a new directory under version control.
SubLua:Delete (path, message, options) Remove files and directories from version control.
SubLua:Revert (path, options) Revert files and directories from version control.
SubLua:Lock (path, message, options) Locks files and directories.
SubLua:Unlock (path, options) Unlocks files and directories.
SubLua:Commit (path, message, options) Commit files or directories into repository
SubLua:DiffRevisions (path, startRevision, endRevision, summarizeCallback, options) Display the differences between two revisions of a path.
SubLua:DiffPaths (path1, path2, summarizeCallback, options) Produce a diff summary which lists the changed items between path1@revision and path2@revision2 without creating text deltas.
SubLua:Copy (srcPath, srcRevision, destPath) Copies one path to another
SubLua:Info (path, infoReceiverCallback, options) Return information about pathOrUrl
SubLua:PropGet (propertyName, path, options) Gets the value of a property on files, dirs, or revisions.
SubLua:PropSet (propName, propValue, path, options) set property in @a path no matter whether local or repository
SubLua:Cleanup (path) Recursively cleans up a local directory, finishing any incomplete operations, removing lockfiles, etc.
ReleaseWorkingCopyLock () Release the lock on the working copy Does nothing and is unnecessary in svn versions 1.6 and below

Tables

Options The Options class.
SvnInfo The SvnInfo class.
Enums The Subverison enums.


Functions

new (options)
Create a new SVN client to work with.
    Available listener callbacks are:
  • Notify( path, svn.action, kind, mimeType, contentState, propState, revision )
  • GetLogin( realm, username, password, maySave )
  • GetLogMessage() and it should return the log message.
  • Incomplete may not function Cancel()

Parameters:

  • options {table} [OPT] The table can contain key of 'username' for the username, 'password' for the password, 'no_auth_cache' to control if the is saved, and 'listener' which is a table of the listeners you want to overwride.

Returns:

    {table} The SubLua object.
SubLua:Cat (path, options)
Output the content of specified files or URLs.

Parameters:

  • path {string} The path or URL to output.
  • options {table} [OPT] Options table. Possible Options: peg, revision

Returns:

    {string} String of the contents of @path.
SubLua:Upgrade (path)
Upgrade the working copy format of the specified path.

Parameters:

  • path {string} The path to a working copy to upgrade.
SubLua:GetWorkingCopyFormatVersion (path)
Get the format version of the working copy at the specified path.

Parameters:

  • path {string} The absolute path to a working copy to get the format for.

Returns:

    The format version of the working copy specified (eg 29 for Subversion 1.7.13 and 31 for Subversion 1.8.0)
SubLua:Checkout (url, path, options)
Checks out a working copy from a url to a path.

Parameters:

  • url {string} The URL to check out.
  • path {string} The local path to check out to.
  • options {table} [OPT] Options table. Possible Options: peg, revision, depth, ignore_externals, force

Returns:

    Revision of the checkout.

see also:

SubLua:Update (path, options)
Updates the file or directory.

Parameters:

  • path {string} The path or URL to output.
  • options {table} [OPT] Options table. Possible Options: revision, depth, set_depth, ignore_externals, force

Returns:

    Revision of the checkout.

see also:

SubLua:Export (srcPath, destPath, options)
Create an unversioned copy of a tree.

Parameters:

  • srcPath {string} The source path or URL to export from.
  • destPath {string} The destination path to export to.
  • options {table} [OPT] Options table. Possible Options: peg, revision, force, ignore_externals, depth, native_eol

Returns:

    Revision of the Export.

see also:

SubLua:Get (path, destPath, options)
Retrieves the contents for a specific revision of a path and saves it to the destination file dstPath.

If destPath is empty (""), then this path will be constructed from the temporary directory on this system and the filename in path. destPath will still have the file extension from path and uniqueness of the temporary filename will be ensured.

Parameters:

  • path {string} path or url
  • destPath {string} destination path
  • options {table} [OPT] Options table. Possible Options: peg, revision

Returns:

    {string} the destPath or the temp file path if destPath was an empty string

see also:

SubLua:Add (path, options)
Schedule a working copy path for addition to the repository. Adds a file to the repository.

Parameters:

  • path {string} The path to add to the working copy. Path's parent must be under revision control already.
  • options {table} [OPT] Options table. Possible Options: depth, force, no_ignore, add_parents

see also:

SubLua:Import (path, url, message, options)
Commit an unversioned file or tree into the repository. Parent directories are created as necessary in the repository.

Parameters:

  • path {string} The path to add to the working copy. Path's parent must be under revision control already.
  • url {string} The URL to check out.
  • message {string} [OPT] The commit message.
  • options {table} [OPT] Options table. Possible Options: depth, no_ignore, auto_props

see also:

SubLua:MkDir (path, message)
Create a new directory under version control.

Parameters:

  • path {string}/{table} The path(s) or URL(s) to output. If it is a local path then the directory is created and scheduled for addition upon the next commit. If it is a URL then the commit is immediate.
  • message {string} [OPT] Log message as a string.
SubLua:Delete (path, message, options)
Remove files and directories from version control.

Parameters:

  • path {string}/{table} The path(s) or URL(s) to remove. If it is a local path(s) then the paths are scheduled for deletion upon the next commit. If it is a URL(s) then they are deleted immediatly.
  • message {string} [OPT] Log message.
  • options {table} [OPT] Options table. Possible Options: force, keep_local

see also:

SubLua:Revert (path, options)
Revert files and directories from version control.

Parameters:

  • path {string}/{table} The path(s) or URL(s) to revert.
  • options {table} [OPT] Options table. Possible Options: depth

see also:

SubLua:Lock (path, message, options)
Locks files and directories.

Parameters:

  • path {string}/{table} The path(s) or URL(s) to lock.
  • message {string} [OPT] The message for the lock.
  • options {table} [OPT] Options table. Possible Options: force

see also:

SubLua:Unlock (path, options)
Unlocks files and directories.

Parameters:

  • path {string}/{table} The path(s) or URL(s) to unlock.
  • options {table} [OPT] Options table. Possible Options: force

see also:

SubLua:Commit (path, message, options)
Commit files or directories into repository

Parameters:

  • path {string}/{table} The path(s) to commit.
  • message {string} The commit message.
  • options {table} [OPT] Options table. Possible Options: depth, keep_locks, keep_changelists

see also:

SubLua:DiffRevisions (path, startRevision, endRevision, summarizeCallback, options)
Display the differences between two revisions of a path. The function may report false positives if notice_ancestry is true, since a file might have been modified between two revisions, but still have the same contents. If summarizeCallback and options.summarize = true then the results passed to the summarizeCallback. If summarizeCallback is not provided, but options.summarize = true then an array of summaryInfo is returned.

Parameters:

  • path {string} The path to diff. Can be either a working-copy path or a URL.
  • startRevision {string}/{number} The start revisions to check.
  • endRevision {string}/{number} The end revision to check.
  • summarizeCallback

    {function} [OPT] Called for every difference found when . For each invocation it passes summaryInfo table that has keys path, summarize_kind, prop_changed, and node_kind. ??Return true from the summarizeCallback() to have the function continue, if you return false it will stop the operation and throw an error.?? summarize_kind available values are found in the Enum section under the summarize.kind. node_kind available values are found in the Enums section under node.kind The prototype for the callback is

    function SubLua:MyDiffSummarizeReceiver( summaryInfo )
    print( summaryInfo.path, summaryInfo.summarize_kind, summaryInfo.prop_changed, summaryInfo.node_kind )
    return true
end
  • options {table} [OPT] Options table. Possible Options: depth, summarize, peg, notice_ancestry, no_diff_deleted, ignore_content_type

Returns:

    Normally the differences are returned as a {string} of file differences.

see also:

SubLua:DiffPaths (path1, path2, summarizeCallback, options)
Produce a diff summary which lists the changed items between path1@revision and path2@revision2 without creating text deltas. The function may report false positives if notice_ancestry is true, since a file might have been modified between two revisions, but still have the same contents. If summarizeCallback and options.summarize = true then the results passed to the summarizeCallback. If summarizeCallback is not provided, but options.summarize = true then an array of summaryInfo is returned.

Parameters:

  • path1 {string} The first path to diff. Can be either a working-copy path or a URL.
  • path2 {string} The second path to diff. Can be either a working-copy path or a URL.
  • summarizeCallback

    {function} Called for every difference found. For each invocation it passes summaryInfo table that has keys path, summarize_kind, prop_changed, and node_kind. ??Return true from the summarizeCallback() to have the function continue, if you return false it will stop the operation and throw an error.?? summarize_kind available values are found in the Enum section under the summarize.kind. node_kind available values are found in the Enums section under node.kind The prototype for the callback is

    function SubLua:MyDiffSummarizeReceiver( summaryInfo )
    print( summaryInfo.path, summaryInfo.summarize_kind, summaryInfo.prop_changed, summaryInfo.node_kind )
    return true
end
  • options {table} [OPT] Options table. Possible Options: depth, revision, revision2, summarize, peg, notice_ancestry.

Returns:

    Normally the differences are returned as a {string} of file differences.

see also:

SubLua:Copy (srcPath, srcRevision, destPath)
Copies one path to another

Parameters:

  • srcPath {string} The source path to copy from.
  • srcRevision {string} The source revision to copy from.
  • destPath {string} The destination path to copy to.
SubLua:Info (path, infoReceiverCallback, options)
Return information about pathOrUrl

Parameters:

  • path {string}/{table} The path or URL to get the specified information from.
  • infoReceiverCallback

    {function} [OPT] Called everytime a file is found during receiving information. For each invocation it passes path with the information present in info. Return true from the InfoReceiver() to have the function contiue, if you return false it will stop the operation and throw an error. The prototype for the callback is

    function SubLua:MyInfoReceiver( path, info )
    print( path, info )
    return true
end
  • options {table} [OPT] Options table. Possible Options: peg, revision, depth

see also:

SubLua:PropGet (propertyName, path, options)
Gets the value of a property on files, dirs, or revisions. property table. In the property table there are keys of property names to their value, both as strings.

Parameters:

  • propertyName {string} The property to get from path.
  • path {string}/{table} The path or URL to get the specified property from.
  • options {table} [OPT] Options table. Possible Options: revision, depth

Returns:

    {table} Table of properties. The list will contain tables where the keys are the path, and the values are a

see also:

SubLua:PropSet (propName, propValue, path, options)
set property in @a path no matter whether local or repository

Parameters:

  • propName {string} The property name to set.
  • propValue {string} The value of the property to set
  • path {string} Path where property to be set
  • options {table} Options table. Possible Options: depth

see also:

SubLua:Cleanup (path)
Recursively cleans up a local directory, finishing any incomplete operations, removing lockfiles, etc.

Parameters:

  • path {string} Path to a local directory.
ReleaseWorkingCopyLock ()
Release the lock on the working copy Does nothing and is unnecessary in svn versions 1.6 and below

Tables

Options
The Options class.

Fields:

  • revision the revision you want to update to; defaults to "HEAD".
  • revision2 the revision for path2 when finding the differences in paths; defaults to "HEAD".
  • peg the peg revision you want to update using; defaults to "HEAD".
  • depth limit operation by depth ARG ('empty', 'files', 'immediates', or 'infinity'); defaults to unknown.
  • force force operation to run; defaults to false.
  • ignore_externals set to ignore the externals; defaults to false.
  • ignore_keywords set to ignore the keyword substitution; defaults to false.
  • no_ignore set to disregard default and svn:ignore property ignores; defaults to false.
  • native_eol use a different EOL marker than the standard system marker for files with the svn:eol-style property set to 'native'. ARG may be one of 'LF', 'CR', 'CRLF'; defaults to NULL (no change).
  • set_depth set new working copy depth to depth. If depth is not specified then this does nothing; defaults to false.
  • parents If true, create any non-existent parent directories also; defaults to false.
  • add_parents If true, recurse up path's directory and look for a versioned directory. If found, add all intermediate paths between it and path; defaults to false.
  • keep_changelists After the commit completes successfully, remove changelist associations from the targets, unless keep_changelists is true; defaults to false.
  • keep_locks Unlock paths in the repository, unless keep_locks is true; defaults to false.
  • auto_props Enable automatic properties; defaults to true.
  • ignore_unknown_node_types Ignore files of which the node type is unknown, such as device files and pipes.; defaults to false.
  • keep_local if true then the paths will not be removed from the working copy, only scheduled for removal from the repository. Once the scheduled deletion is committed, they will appear as unversioned paths in the working copy; defaults to false.
  • no_diff_deleting Do not print differences for deleted files; defaults to false.
  • notice_ancestry Notice ancestry when calculating differences; defaults to false.
  • ignore_content_type if true, Diff output will be generated for binary files, in which case diffs will be shown regardless of the content types; defaults to false.
  • summarize if true, during a diff operation only produce a summary which lists the changed items without creating text deltas; defaults to false.
SvnInfo
The SvnInfo class.

Fields:

  • isValid Is it valid?
  • url The url
  • revision The revision
  • kind The kind
  • rootUrl The root URL
  • uuid The uuid
  • lastChangedRevision Last changed revision
  • lastChangedDate Last changed date
  • lastChangedAuthor Last changed author
  • lock Lock
  • hasWCInfo Has working copy info?
  • schedule The schedule
  • copyFromUrl Copy from URL
  • copyFromRev Copy from revision
  • textTime Time in text
  • propTime Properties time
  • checksum The checksum
  • conflictOld Conflict old
  • conflictNew Conflict new
  • conflictWrk Conflict working
  • propRejectFile Prop reject file
  • changelist The changelist
  • depth Depth
  • workingSize Working size
  • size Size
  • size64 Size64
  • workingSize64 Working Size64
  • treeConflict the TreeConflict
Enums
The Subverison enums. These are part of the SubLua object returned after calling new().

Fields:

  • wc.notify.action.add Adding a path to revision control.
  • wc.notify.action.copy Copying a versioned path.
  • wc.notify.action.delete Deleting a versioned path.
  • wc.notify.action.restore Restoring a missing path from the pristine text-base.
  • wc.notify.action.revert Reverting a modified path.
  • wc.notify.action.failed_revert A revert operation has failed.
  • wc.notify.action.resolved Resolving a conflict.
  • wc.notify.action.skip Skipping a path.
  • wc.notify.action.update_delete Got a delete in an update.
  • wc.notify.action.update_add Got an add in an update.
  • wc.notify.action.update_update Got any other action in an update.
  • wc.notify.action.update_completed The last notification in an update (including updates of externals).
  • wc.notify.action.update_external Updating an external module.
  • wc.notify.action.status_completed The last notification in a status (including status on externals).
  • wc.notify.action.status_external Running status on an external module.
  • wc.notify.action.commit_modified Committing a modification.
  • wc.notify.action.commit_added Committing an addition.
  • wc.notify.action.commit_deleted Committing a deletion.
  • wc.notify.action.commit_replaced Committing a replacement.
  • wc.notify.action.commit_postfix_txdelta Transmitting post-fix text-delta data for a file.
  • wc.notify.action.blame_revision Processed a single revision's blame.
  • wc.notify.action.locked Locking a path. New in 1.2.
  • wc.notify.action.unlocked Unlocking a path. New in 1.2.
  • wc.notify.action.failed_lock Failed to lock a path. New in 1.2.
  • wc.notify.action.failed_unlock Failed to unlock a path. New in 1.2.
  • wc.notify.action.exists Tried adding a path that already exists. New in 1.5.
  • wc.notify.action.changelist_set Changelist name set. New in 1.5.
  • wc.notify.action.changelist_clear Changelist name cleared. New in 1.5.
  • wc.notify.action.changelist_moved Warn user that a path has moved from one changelist to another. New in 1.5. Deprecated: As of 1.7, separate clear and set notifications are sent.
  • wc.notify.action.merge_begin A merge operation (to path) has begun.
  • wc.notify.action.foreign_merge_begin A merge operation (to path) from a foreign repository has begun.
  • wc.notify.action.update_replace Replace notification. New in 1.5.
  • wc.notify.action.property_added Property added. New in 1.6.
  • wc.notify.action.property_modified Property updated. New in 1.6.
  • wc.notify.action.property_deleted Property deleted. New in 1.6.
  • wc.notify.action.property_deleted_nonexistentNonexistent property deleted. New in 1.6.
  • wc.notify.action.revprop_set Revprop set. New in 1.6.
  • wc.notify.action.revprop_deleted Revprop deleted. New in 1.6.
  • wc.notify.action.merge_completed The last notification in a merge. New in 1.6.
  • wc.notify.action.tree_conflict The path is a tree-conflict victim of the intended action (not a persistent tree-conflict from an earlier operation, but this operation caused the tree-conflict). New in 1.6.
  • wc.notify.action.failed_external The path is a subdirectory referenced in an externals definition which is unable to be operated on. New in 1.6.
  • wc.notify.action.update_started Starting an update operation. New in 1.7.
  • wc.notify.action.update_skip_obstruction An update tried to add a file or directory at a path where a separate working copy was found. New in 1.7.
  • wc.notify.action.update_skip_working_only An explicit update tried to update a file or directory that doesn't live in the repository and can't be brought in. New in 1.7.
  • wc.notify.action.update_skip_access_denied An update tried to update a file or directory to which access could not be obtained. New in 1.7.
  • wc.notify.action.update_external_removed An update operation removed an external working copy. New in 1.7.
  • wc.notify.action.update_shadowed_add A node below an existing node was added during update. New in 1.7.
  • wc.notify.action.update_shadowed_update A node below an exising node was updated during update. New in 1.7.
  • wc.notify.action.update_shadowed_delete A node below an existing node was deleted during update. New in 1.7.
  • wc.notify.action.merge_record_info The mergeinfo on path was updated. New in 1.7.
  • wc.notify.action.upgraded_path An working copy directory was upgraded to the latest format. New in 1.7.
  • wc.notify.action.merge_record_info_begin Mergeinfo describing a merge was recorded. New in 1.7.
  • wc.notify.action.merge_elide_info Mergeinfo was removed due to elision. New in 1.7.
  • wc.notify.action.patch A file in the working copy was patched. New in 1.7.
  • wc.notify.action.patch_applied_hunk A hunk from a patch was applied. New in 1.7.
  • wc.notify.action.patch_rejected_hunk A hunk from a patch was rejected. New in 1.7.
  • wc.notify.action.patch_hunk_already_applied A hunk from a patch was found to already be applied. New in 1.7.
  • wc.notify.action.commit_copied Committing a non-overwriting copy (path is the target of the copy, not the source). New in 1.7.
  • wc.notify.action.commit_copied_replaced Committing an overwriting (replace) copy (path is the target of the copy, not the source). New in 1.7.
  • wc.notify.action.url_redirect The server has instructed the client to follow a URL redirection. New in 1.7.
  • wc.notify.action.path_nonexistent The operation was attempted on a path which doesn't exist. New in 1.7.
  • wc.notify.action.exclude Removing a path by excluding it. New in 1.7.
  • wc.notify.action.failed_conflict Operation failed because the node remains in conflict. New in 1.7.
  • wc.notify.action.failed_missing Operation failed because an added node is missing. New in 1.7.
  • wc.notify.action.failed_out_of_date Operation failed because a node is out of date. New in 1.7.
  • wc.notify.action.failed_no_parent Operation failed because an added parent is not selected. New in 1.7.
  • wc.notify.action.failed_locked Operation failed because a node is locked by another user and/or working copy. New in 1.7.
  • wc.notify.action.failed_forbidden_by_server Operation failed because the operation was forbidden by the server. New in 1.7.
  • wc.notify.action.skip_conflicted The operation skipped the path because it was conflicted. New in 1.7.
  • wc.notify.state.unknown Notifier doesn't know or isn't saying.
  • wc.notify.state.unchanged The state did not change.
  • wc.notify.state.missing The item wasn't present.
  • wc.notify.state.obstructed An unversioned item obstructed work.
  • wc.notify.state.changed Pristine state was modified.
  • wc.notify.state.merged Modified state had mods merged in.
  • wc.notify.state.conflicted Modified state got conflicting mods.
  • wc.notify.state.source_missing The source to copy the file from is missing. New in 1.7
  • wc.schedule.normal Nothing special here.
  • wc.schedule.add Slated for addition.
  • wc.schedule.delete Slated for deletion.
  • wc.schedule.replace Slated for replacement (delete + add)
  • wc.conflict.action.edit attempting to change text or props.
  • wc.conflict.action.add attempting to add object.
  • wc.conflict.action.delete attempting to delete object.
  • wc.conflict.action.replace attempting to replace object. New in 1.7
  • wc.conflict.reason.edited Local edits are already present.
  • wc.conflict.reason.obstructed Another object is in the way.
  • wc.conflict.reason.deleted Object is already schedule-delete.
  • wc.conflict.reason.missing Object is unknown or missing.
  • wc.conflict.reason.unversioned Object is unversioned.
  • wc.conflict.reason.added Object is already added or schedule-add.
  • wc.conflict.reason.replaced Object is already replaced. New in 1.7
  • wc.conflict.kind.text textual conflict (on a file)
  • wc.conflict.kind.property property conflict (on a file or dir)
  • wc.conflict.kind.tree tree conflict (on a dir)
  • wc.operation.none No user operation exposed a conflict.
  • wc.operation.update User operation 'update' exposed a conflict.
  • wc.operation.switch User operation 'switch' exposed a conflict.
  • wc.operation.merge User operation 'merge' exposed a conflict.
  • node.kind.none Absent node in the Subversion filesystem.
  • node.kind.file Regular file node in the Subversion filesystem.
  • node.kind.dir Directory node in the Subversion filesystem.
  • node.kind.unknown "something's here, but we don't know what" node in the Subversion filesystem.
  • node.action.change Changed "action" attached to nodes in the dumpfile.
  • node.action.add Added "action" attached to nodes in the dumpfile.
  • node.action.delete Deleted "action" attached to nodes in the dumpfile.
  • node.action.replace Replaced "action" attached to nodes in the dumpfile.
  • depth.unknown Depth undetermined or ignored. In some contexts, this means the client should choose an appropriate default depth. The server will generally treat it as depth.infinity.
  • depth.exclude Exclude (i.e., don't descend into) directory D.
  • depth.empty Just the named directory D, no entries. Updates will not pull in any files or subdirectories not already present.
  • depth.files D + its file children, but not subdirs. Updates will pull in any files not already present, but not subdirectories.
  • depth.immediates D + immediate children (D and its entries). Updates will pull in any files or subdirectories not already present; those subdirectories' this_dir entries will have depth-empty.
  • depth.infinity D + all descendants (full recursion from D). Updates will pull in any files or subdirectories not already present; those subdirectories' this_dir entries will have depth-infinity. Equivalent to the pre-1.5 default update behavior.
  • recurse.kind.nonrecursive Indicates recursion is NOT needed.
  • recurse.kind.recursive Indicates recursion is needed.
  • summarize.kind.normal An item with no text modifications. @see SubLua:DiffRevisions @see SubLua:DiffPaths
  • summarize.kind.added An added item. @see SubLua:DiffRevisions @see SubLua:DiffPaths
  • summarize.kind.modified An item with text modifications. @see SubLua:DiffRevisions @see SubLua:DiffPaths
  • summarize.kind.deleted A deleted item. @see SubLua:DiffRevisions @see SubLua:DiffPaths
generated by LDoc 1.3