1 files changed, 278 insertions, 0 deletions
diff --git a/libparc/parc/algol/parc_File.h b/libparc/parc/algol/parc_File.h
new file mode 100755
index 00000000..42ef232e
--- /dev/null
+++ b/libparc/parc/algol/parc_File.h
@@ -0,0 +1,278 @@
+/*
+ * Copyright (c) 2017 Cisco and/or its affiliates.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at:
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @file parc_File.h
+ * @ingroup inputoutput
+ * @brief File manipulation
+ *
+ *
+ */
+#ifndef libparc_parc_File_h
+#define libparc_parc_File_h
+
+#include <stdbool.h>
+
+#include <parc/algol/parc_BufferComposer.h>
+
+#ifdef PARCLibrary_DISABLE_VALIDATION
+#  define parcFile_OptionalAssertValid(_instance_)
+#else
+#  define parcFile_OptionalAssertValid(_instance_) parcFile_AssertValid(_instance_)
+#endif
+
+struct parc_file;
+typedef struct parc_file PARCFile;
+
+/**
+ * Creates a `PARCFile` object named by pathname.
+ *
+ * This operation does not imply any I/O operations.
+ * The PARCFile instance only represents the pathname,
+ * and does not necessarily reference a real file.
+ *
+ * @param [in] pathname is a pointer to a char array (string)
+ * @return A pointer to an instance of `PARCFile`
+ *
+ * Example:
+ * @code
+ * <#example#>
+ * @endcode
+ */
+PARCFile *parcFile_Create(const char *pathname);
+
+/**
+ * Acquire a new reference to an instance of `PARCFile`.
+ *
+ * The reference count to the instance is incremented.
+ *
+ * @param [in] file The instance of `PARCFile` to which to refer.
+ *
+ * @return The same value as the input parameter @p file
+ *
+ * Example:
+ * @code
+ * {
+ *     <#example#>
+ * }
+ * @endcode
+ */
+PARCFile *parcFile_Acquire(const PARCFile *file);
+
+/**
+ * Assert that an instance of `PARCFile` is valid.
+ *
+ * Valid means the internal state of the type is consistent with its required current or future behaviour.
+ * This may include the validation of internal instances of types.
+ *
+ * @param [in] instance A pointer to a `PARCFile` instance.
+ *
+ * Example:
+ * @code
+ * {
+ *     PARCFile *file = parcFile_Create("/tmp/foo");
+ *
+ *     parcFile_AssertValid(file);
+ * }
+ * @endcode
+ */
+void parcFile_AssertValid(const PARCFile *instance);
+
+/**
+ * Release a `PARCFile` reference.
+ *
+ * Only the last invocation where the reference count is decremented to zero,
+ * will actually destroy the `PARCFile`.
+ *
+ * @param [in,out] filePtr is a pointer to the `PARCFile` reference.
+ *
+ * Example:
+ * @code
+ * <#example#>
+ * @endcode
+ */
+void parcFile_Release(PARCFile **filePtr);
+
+/**
+ * Create a new file on storage.
+ *
+ * @param [in] file A pointer to an instance of `PARCFile`
+ *
+ * @return true if succesful, false if not
+ *
+ * Example:
+ * @code
+ * {
+ *     <#example#>
+ * }
+ * @endcode
+ */
+bool parcFile_CreateNewFile(const PARCFile *file);
+
+/**
+ * Return true if the PARCFile exists on storage.
+ *
+ * If the pathname can be stat(2)'d, then it exists.
+ *
+ * @param [in] file A pointer to a `PARCFile` instance.
+ * @return true if the file exists, false otherwise
+ *
+ * Example:
+ * @code
+ * <#example#>
+ * @endcode
+ */
+bool parcFile_Exists(const PARCFile *file);
+
+/**
+ * Create a new directory.
+ *
+ * @param [in] file A pointer to a `PARCFile` instance.
+ * @return true if the pathname exists, false otherwise
+ *
+ * Example:
+ * @code
+ * {
+ *     <#example#>
+ * }
+ * @endcode
+ */
+bool parcFile_Mkdir(const PARCFile *file);
+
+/**
+ * True if the specified `PARCFile` is an existing directory on storage.
+ *
+ * @param [in] file A pointer to a `PARCFile` instance.
+ *
+ * @return true if specified `PARCFile` is an existing directory on storage, false if not
+ *
+ * Example:
+ * @code
+ * {
+ *     <#example#>
+ * }
+ * @endcode
+ */
+bool parcFile_IsDirectory(const PARCFile *file);
+
+/**
+ * Deletes the file or directory on storage.
+ *
+ * For a directory, it does a recursive delete.
+ *
+ * @param [in] file The instance of `PARCFile` to be deleted.
+ * @return `true` if everything deleted, false otherwise
+ *
+ * Example:
+ * @code
+ * <#example#>
+ * @endcode
+ */
+bool parcFile_Delete(const PARCFile *file);
+
+/**
+ * Append a representation of the specified `PARCFile` instance to the given {@link PARCBufferComposer}.
+ *
+ * @param [in] file A pointer to the `PARCFile` instance whose contents should be appended to to string.
+ * @param [in,out] string A pointer to the `PARCBufferComposer` instance to which the contents of file will be appended.
+ *
+ * @return NULL Cannot allocate memory.
+ * @return non-NULL The instance of `PARCBufferComposer` with the appended contents.
+ *
+ * Example:
+ * @code
+ * {
+ *     PARCBufferComposer *result = parcBufferComposer_Create();
+ *     PARCFile *instance = parcFile_Create("/tmp/foo");
+ *
+ *     parcFile_BuildString(instance, result);
+ *
+ *     PARCBuffer *string = parcBufferComposer_FinalizeBuffer(result);
+ *     printf("File: %s\n", parcBuffer_ToString(string));
+ *     parcBuffer_Release(&string);
+ *
+ *     parcBufferComposer_Release(&result);
+ * }
+ * @endcode
+ */
+PARCBufferComposer *parcFile_BuildString(const PARCFile *file, PARCBufferComposer *string);
+
+/**
+ * <#One Line Description#>
+ *
+ * <#Paragraphs Of Explanation#>
+ *
+ * @param [<#in#> | <#out#> | <#in,out#>] <#name#> <#description#>
+ *
+ * @return <#value#> <#explanation#>
+ *
+ * Example:
+ * @code
+ * {
+ *     <#example#>
+ * }
+ * @endcode
+ */
+size_t parcFile_GetFileSize(const PARCFile *file);
+
+/**
+ * Create a PARCFile representation of the home directory of the current user.
+ *
+ * The return value must be released via `parcFile_Release`.
+ *
+ * @return non-NULL A pointer to a valid PARCFile instance.
+ * @return NULL An error occurred.
+ *
+ * Example:
+ * @code
+ * {
+ *     PARCFile *directory = parcFile_CreateHome();
+ * }
+ * @endcode
+ */
+PARCFile *parcFile_CreateHome(void);
+
+/**
+ * Produce a null-terminated string representation of the specified `PARCFile` instance.
+ *
+ * The non-null result must be freed by the caller via {@link parcMemory_Deallocate}.
+ *
+ * @param [in] file A pointer to the `PARCFile` instance.
+ *
+ * @return NULL Cannot allocate memory.
+ * @return non-NULL A pointer to an allocated, null-terminated C string that must be deallocated via {@link parcMemory_Deallocate}.
+ *
+ * Example:
+ * @code
+ * {
+ *     PARCFile *instance = parcFile_Create("/tmp/foo");
+ *
+ *     char *string = parcFile_ToString(instance);
+ *
+ *     if (string != NULL) {
+ *         printf("Hello: %s\n", string);
+ *         parcMemory_Deallocate((void **)&string);
+ *     } else {
+ *         printf("Cannot allocate memory\n");
+ *     }
+ *
+ *     parcFile_Release(&instance);
+ * }
+ * @endcode
+ *
+ * @see {@link parcFile_BuildString}
+ */
+char *parcFile_ToString(const PARCFile *file);
+#endif // libparc_parc_File_h