key/key-io.c: Add low-level `key_mergeline' and `key_extractline' functions.

[catacomb] / key / key.h

diff --git a/key/key.h b/key/key.h
index bed3632..96a2b5a 100644 (file)
--- a/key/key.h
+++ b/key/key.h
@@ -177,36 +177,64 @@ typedef void key_reporter(const char */*file*/, int /*line*/,
 
 /*----- Reading and writing keys and files --------------------------------*/
 
-/* --- @key_merge@ --- *
+/* --- @key_merge@, @key_mergeline@ --- *
  *
  * Arguments:  @key_file *f@ = pointer to file structure
  *             @const char *file@ = name of file (for error messages)
- *             @FILE *fp@ = file handle to read from
+ *             @int lno@ = line number (for error messages, @key_mergeline@)
+ *             @FILE *fp@ = file handle to read from (@key_merge@)
+ *             @const char *line@ = line from the input (@key_mergeline@)
  *             @key_reporter *rep@ = error reporting function
  *             @void *arg@ = argument for function
  *
  * Returns:    Error code (one of the @KERR@ constants).
  *
- * Use:                Reads keys from a file, and inserts them into the file.
+ * Use:                The @key_merge@ function reads keys from a file, and inserts
+ *             them into the keyring.
+ *
+ *             The @key_mergeline@ function reads a key from a single input
+ *             line (which may, but need not, have a final newline), and
+ *             adds it to the keyring.
+ *
+ *             The @key_mergeline@ function is intended to help with
+ *             interfacing Catacomb to runtimes which don't use C's @stdio@
+ *             streams, rather than as a general-purpose service, though if
+ *             it turns out to be useful in other ways then so much the
+ *             better.
  */
 
 extern int key_merge(key_file */*f*/, const char */*file*/, FILE */*fp*/,
                     key_reporter */*rep*/, void */*arg*/);
+extern int key_mergeline(key_file */*f*/, const char */*file*/, int /*lno*/,
+                        const char */*line*/,
+                        key_reporter */*rep*/, void */*arg*/);
 
-/* --- @key_extract@ --- *
+/* --- @key_extract@, @key_extractline@ --- *
  *
  * Arguments:  @key_file *f@ = pointer to file structure
  *             @key *k@ = key to extract
- *             @FILE *fp@ = file to write on
+ *             @FILE *fp@ = file to write on (@key_extract@)
+ *             @dstr *d@ = string to write on (@key_extractline@)
  *             @const key_filter *kf@ = pointer to key selection block
  *
- * Returns:    Zero if OK, EOF on error.
+ * Returns:    @key_extract@ returns zero if OK, EOF on error.
+ *             @key_extractline@ does not return a value.
+ *
+ * Use:                Extracts a key to an ouptut file or buffer.
+ *
+ *             The @key_extractline@ includes a final newline in its output.
  *
- * Use:                Extracts a key to an ouptut file.
+ *             The @key_extractline@ function is intended to help with
+ *             interfacing Catacomb to runtimes which don't use C's @stdio@
+ *             streams, rather than as a general-purpose service, though if
+ *             it turns out to be useful in other ways then so much the
+ *             better.
  */
 
 extern int key_extract(key_file */*f*/, key */*k*/, FILE */*fp*/,
                       const key_filter */*kf*/);
+extern void key_extractline(key_file */*f*/, key */*k*/,
+                           dstr */*d*/, const key_filter */*kf*/);
 
 /* --- @key_open@ --- *
  *