feat(mailmap): add bindings and api

lib/src/bindings/mailmap.dart

@@ -0,0 +1,158 @@
+import 'dart:ffi';
+import 'package:ffi/ffi.dart';
+import 'libgit2_bindings.dart';
+import '../error.dart';
+import '../util.dart';
+
+/// Allocate a new mailmap object.
+///
+/// This object is empty, so you'll have to add a mailmap file before you can
+/// do anything with it. The mailmap must be freed with `free()`.
+///
+/// Throws a [LibGit2Error] if error occured.
+Pointer<git_mailmap> init() {
+  final out = calloc<Pointer<git_mailmap>>();
+  final error = libgit2.git_mailmap_new(out);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  } else {
+    return out.value;
+  }
+}
+
+/// Create a new mailmap instance containing a single mailmap file.
+///
+/// Throws a [LibGit2Error] if error occured.
+Pointer<git_mailmap> fromBuffer(String buffer) {
+  final out = calloc<Pointer<git_mailmap>>();
+  final bufferC = buffer.toNativeUtf8().cast<Int8>();
+
+  final error = libgit2.git_mailmap_from_buffer(out, bufferC, buffer.length);
+
+  calloc.free(bufferC);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  } else {
+    return out.value;
+  }
+}
+
+/// Create a new mailmap instance from a repository, loading mailmap files based
+/// on the repository's configuration.
+///
+/// Mailmaps are loaded in the following order:
+///
+/// 1. `.mailmap` in the root of the repository's working directory, if present.
+/// 2. The blob object identified by the `mailmap.blob` config entry, if set.
+///   NOTE: `mailmap.blob` defaults to `HEAD:.mailmap` in bare repositories
+/// 3. The path in the `mailmap.file` config entry, if set.
+///
+/// Throws a [LibGit2Error] if error occured.
+Pointer<git_mailmap> fromRepository(Pointer<git_repository> repo) {
+  final out = calloc<Pointer<git_mailmap>>();
+  final error = libgit2.git_mailmap_from_repository(out, repo);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  } else {
+    return out.value;
+  }
+}
+
+/// Resolve a name and email to the corresponding real name and email.
+///
+/// Throws a [LibGit2Error] if error occured.
+List<String> resolve({
+  required Pointer<git_mailmap> mailmapPointer,
+  required String name,
+  required String email,
+}) {
+  final outRealName = calloc<Pointer<Int8>>();
+  final outRealEmail = calloc<Pointer<Int8>>();
+  final nameC = name.toNativeUtf8().cast<Int8>();
+  final emailC = email.toNativeUtf8().cast<Int8>();
+  final error = libgit2.git_mailmap_resolve(
+    outRealName,
+    outRealEmail,
+    mailmapPointer,
+    nameC,
+    emailC,
+  );
+
+  if (error < 0) {
+    calloc.free(outRealName);
+    calloc.free(outRealEmail);
+    calloc.free(nameC);
+    calloc.free(emailC);
+    throw LibGit2Error(libgit2.git_error_last());
+  } else {
+    final realName = outRealName.value.cast<Utf8>().toDartString();
+    final realEmail = outRealEmail.value.cast<Utf8>().toDartString();
+    calloc.free(outRealName);
+    calloc.free(outRealEmail);
+    calloc.free(nameC);
+    calloc.free(emailC);
+
+    return [realName, realEmail];
+  }
+}
+
+/// Resolve a signature to use real names and emails with a mailmap.
+///
+/// Throws a [LibGit2Error] if error occured.
+Pointer<git_signature> resolveSignature({
+  required Pointer<git_mailmap> mailmapPointer,
+  required Pointer<git_signature> signaturePointer,
+}) {
+  final out = calloc<Pointer<git_signature>>();
+  final error = libgit2.git_mailmap_resolve_signature(
+    out,
+    mailmapPointer,
+    signaturePointer,
+  );
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  } else {
+    return out.value;
+  }
+}
+
+/// Add a single entry to the given mailmap object. If the entry already exists,
+/// it will be replaced with the new entry.
+///
+/// Throws a [LibGit2Error] if error occured.
+void addEntry({
+  required Pointer<git_mailmap> mailmapPointer,
+  String? realName,
+  String? realEmail,
+  String? replaceName,
+  required String replaceEmail,
+}) {
+  final realNameC = realName?.toNativeUtf8().cast<Int8>() ?? nullptr;
+  final realEmailC = realEmail?.toNativeUtf8().cast<Int8>() ?? nullptr;
+  final replaceNameC = replaceName?.toNativeUtf8().cast<Int8>() ?? nullptr;
+  final replaceEmailC = replaceEmail.toNativeUtf8().cast<Int8>();
+
+  final error = libgit2.git_mailmap_add_entry(
+    mailmapPointer,
+    realNameC,
+    realEmailC,
+    replaceNameC,
+    replaceEmailC,
+  );
+
+  calloc.free(realNameC);
+  calloc.free(realEmailC);
+  calloc.free(replaceNameC);
+  calloc.free(replaceEmailC);
+
+  if (error < 0) {
+    throw LibGit2Error(libgit2.git_error_last());
+  }
+}
+
+/// Free the mailmap and its associated memory.
+void free(Pointer<git_mailmap> mm) => libgit2.git_mailmap_free(mm);

lib/src/mailmap.dart

@@ -0,0 +1,103 @@
+import 'dart:ffi';
+import 'package:libgit2dart/libgit2dart.dart';
+import 'bindings/libgit2_bindings.dart';
+import 'bindings/mailmap.dart' as bindings;
+import 'util.dart';
+
+class Mailmap {
+  /// Initializes a new instance of [Mailmap] class from provided
+  /// pointer to mailmap object in memory.
+  Mailmap(this._mailmapPointer);
+
+  /// Initializes a new instance of [Mailmap] class.
+  ///
+  /// This object is empty, so you'll have to add a mailmap file before you can
+  /// do anything with it. Must be freed with `free()`.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  Mailmap.empty() {
+    libgit2.git_libgit2_init();
+
+    _mailmapPointer = bindings.init();
+  }
+
+  /// Initializes a new instance of [Mailmap] class from provided buffer.
+  ///
+  /// Must be freed with `free()`.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  Mailmap.fromBuffer(String buffer) {
+    libgit2.git_libgit2_init();
+
+    _mailmapPointer = bindings.fromBuffer(buffer);
+  }
+
+  /// Initializes a new instance of [Mailmap] class from a repository, loading
+  /// mailmap files based on the repository's configuration.
+  ///
+  /// Mailmaps are loaded in the following order:
+  ///
+  /// 1. `.mailmap` in the root of the repository's working directory, if present.
+  /// 2. The blob object identified by the `mailmap.blob` config entry, if set.
+  ///   NOTE: `mailmap.blob` defaults to `HEAD:.mailmap` in bare repositories
+  /// 3. The path in the `mailmap.file` config entry, if set.
+  ///
+  /// Must be freed with `free()`.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  Mailmap.fromRepository(Repository repo) {
+    _mailmapPointer = bindings.fromRepository(repo.pointer);
+  }
+
+  late final Pointer<git_mailmap> _mailmapPointer;
+
+  /// Pointer to memory address for allocated mailmap object.
+  Pointer<git_mailmap> get pointer => _mailmapPointer;
+
+  /// Returns list containing resolved [name] and [email] to the corresponding real name
+  /// and real email respectively.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  List<String> resolve({
+    required String name,
+    required String email,
+  }) {
+    return bindings.resolve(
+      mailmapPointer: _mailmapPointer,
+      name: name,
+      email: email,
+    );
+  }
+
+  /// Resolves a signature to use real names and emails with a mailmap.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  Signature resolveSignature(Signature signature) {
+    return Signature(bindings.resolveSignature(
+      mailmapPointer: _mailmapPointer,
+      signaturePointer: signature.pointer,
+    ));
+  }
+
+  /// Adds a single entry to the given mailmap object. If the entry already exists,
+  /// it will be replaced with the new entry.
+  ///
+  /// Throws a [LibGit2Error] if error occured.
+  void addEntry({
+    String? realName,
+    String? realEmail,
+    String? replaceName,
+    required String replaceEmail,
+  }) {
+    bindings.addEntry(
+      mailmapPointer: _mailmapPointer,
+      realName: realName,
+      realEmail: realEmail,
+      replaceName: replaceName,
+      replaceEmail: replaceEmail,
+    );
+  }
+
+  /// Releases memory allocated for mailmap object.
+  void free() => bindings.free(_mailmapPointer);
+}