Merge pull request #82 from swift-developer-tools/feature/refs-advanced

Add Refs (Advanced) bindings

Author: swift-developer-tools-archive

Sources/SwiftLibgit2/ODB/ODB-Functions.swift

@@ -545,7 +545,6 @@ public func gitODBWrite(
 
 
 
-// TODO: Replace `GIT_STREAM_WRONLY` in documentation.
 /// Opens a stream to write an object into the given object database.
 /// - Parameters:
 ///   - out: The pointer in which to store the stream.
@@ -557,9 +556,9 @@ public func gitODBWrite(
 ///
 /// ## Discussion
 ///
-/// The type of the resulting stream will be `GIT_STREAM_WRONLY`, and it
-/// will not be effective until ``gitODBStreamFinalizeWrite(out:stream:)``
-/// is successfully called.
+/// The type of the resulting stream will be ``GitODBStreamT/gitStreamWROnly``,
+/// and it will not be effective until
+/// ``gitODBStreamFinalizeWrite(out:stream:)`` is successfully called.
 ///
 /// ## C Equivalent
 ///
@@ -719,7 +718,6 @@ public func gitODBStreamFree(
 
 
 
-// TODO: Replace `GIT_STREAM_WRONLY` in documentation.
 /// Opens a stream to read the specified object from the given object database.
 /// - Parameters:
 ///   - out: The pointer in which to store the stream.
@@ -732,8 +730,8 @@ public func gitODBStreamFree(
 ///
 /// ## Discussion
 ///
-/// The type of the resulting stream will be `GIT_STREAM_RONLY`, and will
-/// have `read()` and `free()` methods.
+/// The type of the resulting stream will be ``GitODBStreamT/gitStreamWROnly``,
+/// and will have `read()` and `free()` methods.
 ///
 /// - Note: Most backends do not support streaming reads, since the objects are
 /// stored as compressed/delta blobs. Use ``gitODBRead(obj:db:id:)`` instead.

Sources/SwiftLibgit2/RefDB/RefDB-Functions.swift

@@ -11,7 +11,6 @@ import CLibgit2
 
 
 
-// TODO: Replace `git_refdb_set_backend()` in documentation.
 /// Creates a new reference database with no backends.
 /// - Parameters:
 ///   - out: The pointer in which to store the reference database. The
@@ -23,7 +22,8 @@ import CLibgit2
 /// ## Discussion
 ///
 /// Before the ODB can be used for reading or writing, a custom database
-/// backend must be manually added by calling `git_refdb_set_backend()`.
+/// backend must be manually added by calling
+/// ``gitRefDBSetBackend(refDB:backend:)``.
 ///
 /// ## C Equivalent
 ///

Sources/SwiftLibgit2/Refs-Advanced/Refs-Advanced-Functions.swift

@@ -0,0 +1,67 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the swift-libgit2 open source project.
+//
+// Copyright (c) Margins Technologies LLC.
+// Licensed under the Apache License, Version 2.0.
+//
+//===----------------------------------------------------------------------===//
+
+import CLibgit2
+
+
+
+/// Creates a new direct reference using the given name and ID.
+/// - Parameters:
+///   - name: The reference name to use.
+///   - oid: The reference ID to use.
+///   - peel: The ID of the first non-tag object to use.
+/// - Returns: The new direct reference using the given name and ID.
+///
+/// ## C Equivalent
+///
+/// [`git_reference__alloc()`](https://libgit2.org/docs/reference/main/sys/refs/git_reference__alloc.html)
+public func gitReferenceAlloc(
+    name    : String,
+    oid     : GitOID,
+    peel    : GitOID?
+) -> OpaquePointer?
+{
+    return try? oid.withCValue
+    {
+        cOID in
+        
+        return try peel.withOptionalCValue
+        {
+            cPeel in
+            
+            return git_reference__alloc(
+                name,
+                cOID,
+                cPeel
+            )
+        }
+    }
+}
+
+
+
+/// Creates a new symbolic reference using the given name and target.
+/// - Parameters:
+///   - name: The reference name to use.
+///   - target: The reference target to use.
+/// - Returns: The new direct reference using the given name and target.
+///
+/// ## C Equivalent
+///
+/// [`git_reference__alloc_symbolic()`](https://libgit2.org/docs/reference/main/sys/refs/git_reference__alloc_symbolic.html)
+public func gitReferenceAllocSymbolic(
+    name    : String,
+    target  : String
+) -> OpaquePointer?
+{
+    return git_reference__alloc_symbolic(
+        name,
+        target
+    )
+}

Sources/SwiftLibgit2/SwiftLibgit2.docc/Refs-Advanced.md

@@ -0,0 +1,10 @@
+# Refs (Advanced)
+
+Low-level reference creation.
+
+## Topics
+
+### Functions
+
+- ``gitReferenceAlloc(name:oid:peel:)``
+- ``gitReferenceAllocSymbolic(name:target:)``

Tests/swift-libgit2Tests/Refs-Advanced-Tests.swift

@@ -0,0 +1,127 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the swift-libgit2 open source project.
+//
+// Copyright (c) Margins Technologies LLC.
+// Licensed under the Apache License, Version 2.0.
+//
+//===----------------------------------------------------------------------===//
+
+import CLibgit2
+import XCTest
+@testable import SwiftLibgit2
+
+
+
+final class RefsAdvancedTests: XCTestCaseStopOnFail
+{
+    func testGitReferenceAlloc() throws
+    {
+        try Repository.withRepository
+        {
+            repository in
+            
+            var directRefPointer: OpaquePointer? = nil
+            
+            defer
+            {
+                gitReferenceFree(ref: directRefPointer)
+            }
+            
+            
+            
+            let refName : String    = "HEAD"
+            let refOID  : GitOID    = repository.headOID
+            
+            directRefPointer = gitReferenceAlloc(
+                name:   refName,
+                oid:    refOID,
+                peel:   refOID
+            )
+            
+            guard let directRefPointer: OpaquePointer = directRefPointer
+            else
+            {
+                XCTFail("The direct reference pointer was nil.")
+                return
+            }
+            
+            
+            
+            let directRefName: String?
+                = gitReferenceName(ref: directRefPointer)
+            
+            XCTAssertNotNil(directRefName)
+            XCTAssertEqual(directRefName, refName)
+            
+            
+            
+            let directRefType: GitReferenceT?
+                = gitReferenceType(ref: directRefPointer)
+            
+            XCTAssertNotNil(directRefType)
+            XCTAssertEqual(directRefType, .gitReferenceDirect)
+            
+            
+            
+            let directTargetOID: GitOID?
+                = gitReferenceTarget(ref: directRefPointer)
+            
+            XCTAssertNotNil(directTargetOID)
+            XCTAssertEqual(directTargetOID, refOID)
+        }
+    }
+    
+    
+    
+    func testGitReferenceAllocSymbolic() throws
+    {
+        var symbolicRefPointer: OpaquePointer? = nil
+        
+        defer
+        {
+            gitReferenceFree(ref: symbolicRefPointer)
+        }
+        
+        
+        
+        let refName         : String    = "refs/heads/symbolic-test"
+        let refTargetName   : String    = "HEAD"
+        
+        symbolicRefPointer = gitReferenceAllocSymbolic(
+            name:       refName,
+            target:     refTargetName
+        )
+        
+        guard let symbolicRefPointer: OpaquePointer = symbolicRefPointer
+        else
+        {
+            XCTFail("The symbolic reference pointer was nil.")
+            return
+        }
+        
+        
+        
+        let symbolicRefName: String?
+            = gitReferenceName(ref: symbolicRefPointer)
+        
+        XCTAssertNotNil(symbolicRefName)
+        XCTAssertEqual(symbolicRefName, refName)
+        
+        
+        
+        let symbolicRefType: GitReferenceT?
+            = gitReferenceType(ref: symbolicRefPointer)
+        
+        XCTAssertNotNil(symbolicRefType)
+        XCTAssertEqual(symbolicRefType, .gitReferenceSymbolic)
+        
+        
+        
+        let symbolicTarget: String?
+            = gitReferenceSymbolicTarget(ref: symbolicRefPointer)
+        
+        XCTAssertNotNil(symbolicTarget)
+        XCTAssertEqual(symbolicTarget, refTargetName)
+    }
+}