Add zix_expand_environment_strings()

2 files changed, 48 insertions, 1 deletions

diff --git a/include/zix/environment.h b/include/zix/environment.h
new file mode 100644
index 0000000..fbbcd0d
--- /dev/null
+++ b/include/zix/environment.h
@@ -0,0 +1,39 @@
+// Copyright 2024 David Robillard <d@drobilla.net>
+// SPDX-License-Identifier: ISC
+
+#ifndef ZIX_ENVIRONMENT_H
+#define ZIX_ENVIRONMENT_H
+
+#include <zix/allocator.h>
+#include <zix/attributes.h>
+
+ZIX_BEGIN_DECLS
+
+/**
+   @defgroup zix_expand Variable Expansion
+   @ingroup zix_environment
+   @{
+*/
+
+/**
+   Expand shell-style variables in a string.
+
+   On Windows, this expands environment variable references like
+   "%USERPROFILE%".  On POSIX systems, it expands environment variable
+   references like "$HOME", and the special path component "~".
+
+   @param allocator Allocator used for returned string.
+   @param string Input string to expand.
+   @return A newly allocated copy of `string` with variables expanded, or null.
+*/
+ZIX_API char* ZIX_ALLOCATED
+zix_expand_environment_strings(ZixAllocator* ZIX_NULLABLE allocator,
+                               const char* ZIX_NONNULL    string);
+
+/**
+   @}
+*/
+
+ZIX_END_DECLS
+
+#endif /* ZIX_ENVIRONMENT_H */
diff --git a/include/zix/zix.h b/include/zix/zix.h
index 4fcf238..ceaadc0 100644
--- a/include/zix/zix.h
+++ b/include/zix/zix.h
@@ -1,4 +1,4 @@
-// Copyright 2016-2022 David Robillard <d@drobilla.net>
+// Copyright 2016-2024 David Robillard <d@drobilla.net>
 // SPDX-License-Identifier: ISC
 
 #ifndef ZIX_ZIX_H
@@ -68,6 +68,14 @@
 
 /**
    @}
+   @defgroup zix_environment Environment
+   @{
+*/
+
+#include <zix/environment.h>
+
+/**
+   @}
    @}
 */