CHANGED: Continue to refactor core API routines for clarity and flexibility

diff --git a/Sources/libMultiMarkdown/include/libMultiMarkdown.h b/Sources/libMultiMarkdown/include/libMultiMarkdown.h
index 41fb6c80124ade4b927b18db323b4069d472488a..c5fe3596cdd767e89e516ea2b60b36a9b59edb14 100644 (file)
--- a/Sources/libMultiMarkdown/include/libMultiMarkdown.h
+++ b/Sources/libMultiMarkdown/include/libMultiMarkdown.h
@@ -78,11 +78,23 @@
 #include "token.h"
 
 
+/// There are 3 main versions of the primary functions:
+///
+///    * `mmd_string...` -- start from source text in c string
+/// * `mmd_d_string...` -- start from a DString (Useful if you already use DString's for your text)
+/// * `mmd_engine...` -- useful when you are processing the same source multiple times
+
+
 /// Convert MMD text to specified format, with specified extensions, and language
 /// Returned char * must be freed
 char * mmd_string_convert(const char * source, unsigned long extensions, short format, short language);
 
 
+/// Convert MMD text and write results to specified file -- used for "complex" output formats requiring
+/// multiple documents (e.g. EPUB)
+void mmd_string_convert_to_file(const char * source, unsigned long extensions, short format, short language, const char * directory, const char * filepath);
+
+
 /// Does the text have metadata?
 bool mmd_string_has_metadata(char * source, size_t * end);
 
@@ -97,6 +109,8 @@ char * mmd_string_metadata_keys(char * source);
 char * mmd_string_metavalue_for_key(char * source, const char * key);
 
 
+
+
 /// Convert MMD text to specified format, with specified extensions, and language
 /// Returned char * must be freed
 char * mmd_d_string_convert(DString * source, unsigned long extensions, short format, short language);
@@ -107,6 +121,22 @@ char * mmd_d_string_convert(DString * source, unsigned long extensions, short fo
 void mmd_d_string_convert_to_file(DString * source, unsigned long extensions, short format, short language, const char * directory, const char * filepath);
 
 
+/// Does the text have metadata?
+bool mmd_d_string_has_metadata(DString * source, size_t * end);
+
+
+/// Return metadata keys, one per line
+/// Returned char * must be freed
+char * mmd_d_string_metadata_keys(DString * source);
+
+
+/// Extract desired metadata as string value
+/// Returned char * must be freed
+char * mmd_d_string_metavalue_for_key(DString * source, const char * key);
+
+
+
+
 /// MMD Engine is used for storing configuration information for MMD parser
 typedef struct mmd_engine mmd_engine;
 
@@ -126,7 +156,7 @@ mmd_engine * mmd_engine_create_with_string(
 );
 
 
-/// Reset engine when finished parsing. (Not necessary to use this.)
+/// Reset engine when finished parsing. (Usually not necessary to use this.)
 void mmd_engine_reset(mmd_engine * e);
 
 
@@ -137,6 +167,10 @@ void mmd_engine_free(
 );
 
 
+/// Set language and smart quotes language
+void mmd_engine_set_language(mmd_engine * e, short language);
+
+
 /// Parse part of the string into a token tree
 token * mmd_engine_parse_substring(mmd_engine * e, size_t byte_start, size_t byte_len);
 
@@ -145,6 +179,20 @@ token * mmd_engine_parse_substring(mmd_engine * e, size_t byte_start, size_t byt
 void mmd_engine_parse_string(mmd_engine * e);
 
 
+/// Export parsed token tree to output format
+void mmd_engine_export_token_tree(DString * out, mmd_engine * e, short format);
+
+
+/// Convert MMD text to specified format, with specified extensions, and language
+/// Returned char * must be freed
+char * mmd_engine_convert(mmd_engine * e, short format);
+
+
+/// Convert MMD text and write results to specified file -- used for "complex" output formats requiring
+/// multiple documents (e.g. EPUB)
+void mmd_engine_convert_to_file(mmd_engine * e, short format, const char * directory, const char * filepath);
+
+
 /// Does the text have metadata?
 bool mmd_engine_has_metadata(mmd_engine * e, size_t * end);
 
@@ -158,13 +206,6 @@ char * mmd_engine_metadata_keys(mmd_engine * e);
 char * mmd_engine_metavalue_for_key(mmd_engine * e, const char * key);
 
 
-void mmd_engine_export_token_tree(DString * out, mmd_engine * e, short format);
-
-
-/// Set language and smart quotes language
-void mmd_engine_set_language(mmd_engine * e, short language);
-
-
 /// Return the version string for this build of libMultiMarkdown
 /// The returned `char *` will need to be freed after it is no longer needed.
 char * mmd_version(void);

diff --git a/Sources/libMultiMarkdown/mmd.c b/Sources/libMultiMarkdown/mmd.c
index afd497bea2333bf767e371de1b0277fd4bb3b45a..537a2479014c592af07fba41d669e00dd09d6d37 100644 (file)
--- a/Sources/libMultiMarkdown/mmd.c
+++ b/Sources/libMultiMarkdown/mmd.c
@@ -1924,6 +1924,20 @@ bool mmd_string_has_metadata(char * source, size_t * end) {
 }
 
 
+/// Does the text have metadata?
+bool mmd_d_string_has_metadata(DString * source, size_t * end) {
+       bool result;
+
+       mmd_engine * e = mmd_engine_create_with_dstring(source, 0);
+       result = mmd_engine_has_metadata(e, end);
+
+       mmd_engine_free(e, false);
+
+       return result;
+}
+
+
+/// Does the text have metadata?
 bool mmd_engine_has_metadata(mmd_engine * e, size_t * end) {
        bool result = false;
 
@@ -1974,6 +1988,20 @@ char * mmd_string_metadata_keys(char * source) {
 }
 
 
+/// Return metadata keys, one per line
+/// Returned char * must be freed
+char * mmd_d_string_metadata_keys(DString * source) {
+       char * result;
+
+       mmd_engine * e = mmd_engine_create_with_dstring(source, 0);
+       result = mmd_engine_metadata_keys(e);
+
+       mmd_engine_free(e, false);
+
+       return result;
+}
+
+
 /// Return metadata keys, one per line
 /// Returned char * must be freed
 char * mmd_engine_metadata_keys(mmd_engine * e) {
@@ -2016,6 +2044,20 @@ char * mmd_string_metavalue_for_key(char * source, const char * key) {
 }
 
 
+/// Extract desired metadata as string value
+/// Returned char * must be freed
+char * mmd_d_string_metavalue_for_key(DString * source, const char * key) {
+       char * result;
+
+       mmd_engine * e = mmd_engine_create_with_dstring(source, 0);
+       result = strdup(mmd_engine_metavalue_for_key(e, key));
+
+       mmd_engine_free(e, false);
+
+       return result;
+}
+
+
 /// Grab metadata without processing entire document
 /// Returned char * does not need to be freed
 char * mmd_engine_metavalue_for_key(mmd_engine * e, const char * key) {
@@ -2055,16 +2097,9 @@ char * mmd_string_convert(const char * source, unsigned long extensions, short f
 
        mmd_engine_set_language(e, language);
 
-       mmd_engine_parse_string(e);
-
-       DString * output = d_string_new("");
-
-       mmd_engine_export_token_tree(output, e, format);
-
-       result = output->str;
+       result = mmd_engine_convert(e, format);
 
        mmd_engine_free(e, true);                       // The engine has a private copy of source that must be freed
-       d_string_free(output, false);
 
        return result;
 }
@@ -2079,6 +2114,19 @@ char * mmd_d_string_convert(DString * source, unsigned long extensions, short fo
 
        mmd_engine_set_language(e, language);
 
+       result = mmd_engine_convert(e, format);
+
+       mmd_engine_free(e, false);                      // The engine doesn't own the DString, so don't free it.
+
+       return result;
+}
+
+
+/// Convert MMD text to specified format, with specified extensions, and language
+/// Returned char * must be freed
+char * mmd_engine_convert(mmd_engine * e, short format) {
+       char * result;
+
        mmd_engine_parse_string(e);
 
        DString * output = d_string_new("");
@@ -2087,21 +2135,44 @@ char * mmd_d_string_convert(DString * source, unsigned long extensions, short fo
 
        result = output->str;
 
-       mmd_engine_free(e, false);                      // The engine doesn't own the DString, so don't free it.
        d_string_free(output, false);
 
        return result;
 }
 
 
+/// Convert MMD text and write results to specified file -- used for "complex" output formats requiring
+/// multiple documents (e.g. EPUB)
+void mmd_string_convert_to_file(const char * source, unsigned long extensions, short format, short language, const char * directory, const char * filepath) {
+
+       mmd_engine * e = mmd_engine_create_with_string(source, extensions);
+
+       mmd_engine_set_language(e, language);
+
+       mmd_engine_parse_string(e);
+
+       mmd_engine_free(e, true);                       // The engine has a private copy of source, so free it.
+}
+
+
+/// Convert MMD text and write results to specified file -- used for "complex" output formats requiring
+/// multiple documents (e.g. EPUB)
 void mmd_d_string_convert_to_file(DString * source, unsigned long extensions, short format, short language, const char * directory, const char * filepath) {
-       FILE * output_stream;
 
        mmd_engine * e = mmd_engine_create_with_dstring(source, extensions);
 
        mmd_engine_set_language(e, language);
 
-       mmd_engine_parse_string(e);
+       mmd_engine_convert_to_file(e, format, directory, filepath);
+
+       mmd_engine_free(e, false);                      // The engine doesn't own the DString, so don't free it.
+}
+
+
+/// Convert MMD text and write results to specified file -- used for "complex" output formats requiring
+/// multiple documents (e.g. EPUB)
+void mmd_engine_convert_to_file(mmd_engine * e, short format, const char * directory, const char * filepath) {
+       FILE * output_stream;
 
        DString * output = d_string_new("");
 
@@ -2126,10 +2197,10 @@ void mmd_d_string_convert_to_file(DString * source, unsigned long extensions, sh
                        break;
        }
 
-       mmd_engine_free(e, false);                      // The engine doesn't own the DString, so don't free it.
        d_string_free(output, true);
 }
 
+
 /// Return string containing engine version.
 char * mmd_version(void) {
        char * result;