buf: deprecate git_buf as a public typeethomson/userbuf

The `git_buf` type is now no longer a publicly available structure, and
the `git_buf` family of functions are no longer exported.

The deprecation layer adds a typedef for `git_buf` (as `git_userbuf`)
and macros that define `git_buf` functions as `git_userbuf` functions.
This provides API (but not ABI) compatibility with libgit2 1.0's buffer
functionality.

Within libgit2 itself, we take care to avoid including those deprecated
typedefs and macros, since we want to continue using the `git_buf` type
and functions unmodified.  Therefore, a `GIT_DEPRECATE_BUF` guard now
wraps the buffer deprecation layer.  libgit2 will define that.

7 files changed, 64 insertions, 22 deletions

diff --git a/src/buffer.c b/src/buffer.c
index f81f19999..ce97ccffa 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -6,7 +6,7 @@
  */
 #include "buffer.h"
 #include "posix.h"
-#include "git2/buffer.h"
+#include "git2/userbuf.h"
 #include "buf_text.h"
 #include <ctype.h>
 
@@ -181,16 +181,6 @@ int git_buf_set(git_buf *buf, const void *data, size_t len)
 	return 0;
 }
 
-int git_buf_is_binary(const git_buf *buf)
-{
-	return git_buf_text_is_binary(buf);
-}
-
-int git_buf_contains_nul(const git_buf *buf)
-{
-	return git_buf_text_contains_nul(buf);
-}
-
 int git_buf_sets(git_buf *buf, const char *string)
 {
 	return git_buf_set(buf, string, string ? strlen(string) : 0);
diff --git a/src/buffer.h b/src/buffer.h
index a2ac2c77b..e2023cc59 100644
--- a/src/buffer.h
+++ b/src/buffer.h
@@ -9,13 +9,12 @@
 
 #include "common.h"
 #include "git2/strarray.h"
-#include "git2/buffer.h"
+#include "git2/userbuf.h"
 
-/* typedef struct {
- *  	char   *ptr;
- *  	size_t asize, size;
- * } git_buf;
- */
+typedef struct {
+	char *ptr;
+	size_t asize, size;
+} git_buf;
 
 extern char git_buf__initbuf[];
 extern char git_buf__oom[];
@@ -23,6 +22,9 @@ extern char git_buf__oom[];
 /* Use to initialize buffer structure when git_buf is on stack */
 #define GIT_BUF_INIT { git_buf__initbuf, 0, 0 }
 
+/* Static initializer for git_buf from static buffer */
+#define GIT_BUF_INIT_CONST(STR,LEN) { (char *)(STR), 0, (size_t)(LEN) }
+
 GIT_INLINE(bool) git_buf_is_allocated(const git_buf *buf)
 {
 	return (buf->ptr != NULL && buf->asize > 0);
@@ -37,6 +39,36 @@ GIT_INLINE(bool) git_buf_is_allocated(const git_buf *buf)
 extern int git_buf_init(git_buf *buf, size_t initial_size);
 
 /**
+ * Dispose the git_buf.  If the memory is owned by libgit2 (in other
+ * words, if asize > 0) then the given ptr will be freed.
+ */
+extern void git_buf_dispose(git_buf *buf);
+
+/**
+ * Sets the buffer to a copy of some raw data.
+ */
+extern int git_buf_set(git_buf *buf, const void *ptr, size_t len);
+
+/**
+ * Resize the buffer allocation to make more space.
+ *
+ * This will attempt to grow the buffer to accommodate the target size.
+ *
+ * If the buffer refers to memory that was not allocated by libgit2 (i.e.
+ * the `asize` field is zero), then `ptr` will be replaced with a newly
+ * allocated block of data.  Be careful so that memory allocated by the
+ * caller is not lost.  As a special variant, if you pass `target_size` as
+ * 0 and the memory is not allocated by libgit2, this will allocate a new
+ * buffer of size `size` and copy the external data into it.
+ *
+ * Currently, this will never shrink a buffer, only expand it.
+ *
+ * If the allocation fails, this will return an error and the buffer will
+ * be marked as invalid for future operations, invaliding the contents.
+*/
+extern int git_buf_grow(git_buf *buf, size_t size);
+
+/**
  * Resize the buffer allocation to make more space.
  *
  * This will attempt to grow the buffer to accommodate the additional size.
diff --git a/src/common.h b/src/common.h
index 2b1a4a456..dc3062223 100644
--- a/src/common.h
+++ b/src/common.h
@@ -85,7 +85,13 @@
 /*
  * Include the declarations for deprecated functions; this ensures
  * that they're decorated with the proper extern/visibility attributes.
+ *
+ * Before doing that, declare that we don't want compatibility git_buf
+ * definitions.  We want to avoid intermingling the public compatibility
+ * layer with our actual git_buf types and functions.
  */
+
+#define GIT_DEPRECATE_BUF
 #include "git2/deprecated.h"
 
 #include "posix.h"
diff --git a/src/transports/auth_ntlm.c b/src/transports/auth_ntlm.c
index d134a3db6..12000e665 100644
--- a/src/transports/auth_ntlm.c
+++ b/src/transports/auth_ntlm.c
@@ -5,8 +5,8 @@
  * a Linking Exception. For full terms see the included COPYING file.
  */
 
-#include "git2.h"
 #include "common.h"
+#include "git2.h"
 #include "buffer.h"
 #include "auth.h"
 #include "auth_ntlm.h"
diff --git a/src/userbuf.c b/src/userbuf.c
index e5c8fa3b7..5bfb27ae0 100644
--- a/src/userbuf.c
+++ b/src/userbuf.c
@@ -4,9 +4,9 @@
  * This file is part of libgit2, distributed under the GNU GPL v2 with
  * a Linking Exception. For full terms see the included COPYING file.
  */
+
 #include "userbuf.h"
 #include "buffer.h"
-#include "git2/buffer.h"
 #include "buf_text.h"
 #include <ctype.h>
 
@@ -21,11 +21,26 @@ void git_userbuf_sanitize(git_userbuf *buf)
 	}
 }
 
-int git_userbuf_set(git_userbuf *buf, const char *ptr, size_t len)
+int git_userbuf_is_binary(const git_userbuf *buf)
+{
+	return git_buf_text_is_binary((git_buf *)buf);
+}
+
+int git_userbuf_contains_nul(const git_userbuf *buf)
+{
+	return git_buf_text_contains_nul((git_buf *)buf);
+}
+
+int git_userbuf_set(git_userbuf *buf, const void *ptr, size_t len)
 {
 	return git_buf_set((git_buf *)buf, ptr, len);
 }
 
+int git_userbuf_grow(git_userbuf *buf, size_t size)
+{
+	return git_buf_grow((git_buf *)buf, size);
+}
+
 void git_userbuf_dispose(git_userbuf *buf)
 {
 	git_buf_dispose((git_buf *)buf);
diff --git a/src/userbuf.h b/src/userbuf.h
index 3d7a837d5..faa91fe16 100644
--- a/src/userbuf.h
+++ b/src/userbuf.h
@@ -7,6 +7,7 @@
 #ifndef INCLUDE_userbuf_h__
 #define INCLUDE_userbuf_h__
 
+#include "common.h"
 #include "git2/userbuf.h"
 #include "buffer.h"
 
diff --git a/src/util.h b/src/util.h
index af38698fe..06a10f58e 100644
--- a/src/util.h
+++ b/src/util.h
@@ -13,8 +13,6 @@
 # include <ctype.h>
 #endif
 
-#include "git2/buffer.h"
-
 #include "buffer.h"
 #include "common.h"
 #include "strnlen.h"