text: naming & doc fixes

include/psyc/parse.h

@@ -330,7 +330,7 @@ void psyc_setParseBuffer (psycParseState *state, psycString buffer)
  * @see psycString
  */
 static inline
-void psyc_setParseBuffer2 (psycParseState *state, char *buffer, size_t length)
+void psyc_setParseBuffer2 (psycParseState *state, const char *buffer, size_t length)
 {
 	psycString buf = {length, buffer};
 	psyc_setParseBuffer(state, buf);
@@ -358,7 +358,7 @@ void psyc_setParseListBuffer (psycParseListState *state, psycString buffer)
 }
 
 static inline
-void psyc_setParseListBuffer2 (psycParseListState *state, char *buffer, size_t length)
+void psyc_setParseListBuffer2 (psycParseListState *state, const char *buffer, size_t length)
 {
 	psycString buf = {length, buffer};
 	psyc_setParseListBuffer(state, buf);

include/psyc/text.h

@@ -26,7 +26,7 @@ typedef enum
 	/// Text template parsing & rendering complete.
 	PSYC_TEXT_COMPLETE = 0,
 	/// Text template parsing & rendering is incomplete, because the buffer was too small.
-	/// Another call is required to this function with a new buffer.
+	/// Another call is required to this function after setting a new buffer.
 	PSYC_TEXT_INCOMPLETE = 1,
 } psycTextRC;
 
@@ -48,8 +48,8 @@ typedef struct
 {
 	size_t cursor; ///< current position in the template
 	size_t written; ///< number of bytes written to buffer
-	psycString template; ///< template to parse
+	psycString tmpl; ///< input buffer with text template to parse
-	psycString buffer; ///< buffer for writing to
+	psycString buffer; ///< output buffer for rendered text
 	psycString open;
 	psycString close;
 } psycTextState;
@@ -70,32 +70,32 @@ typedef psycTextValueRC (*psycTextCB)(const char *name, size_t len, psycString *
  * Initializes the PSYC text state struct.
  *
  * @param state Pointer to the PSYC text state struct that should be initialized.
- * @param template Text template to be parsed.
+ * @param tmpl Input buffer with text template to be parsed.
- * @param tlen Length of template.
+ * @param tmplen Length of input buffer.
- * @param buffer Buffer where the rendered text is going to be written.
+ * @param buffer Output buffer where the rendered text is going to be written.
- * @param blen Length of buffer.
+ * @param buflen Length of output buffer.
  */
 static inline
 void psyc_initTextState (psycTextState *state,
-                         char *template, size_t tlen,
+                         const char *tmpl, size_t tmplen,
-                         char *buffer, size_t blen)
+                         char *buffer, size_t buflen)
 {
-	state->cursor   = 0;
+	state->cursor  = 0;
-	state->written  = 0;
+	state->written = 0;
-	state->template = (psycString) {tlen, template};
+	state->tmpl    = (psycString) {tmplen, tmpl};
-	state->buffer   = (psycString) {blen, buffer};
+	state->buffer  = (psycString) {buflen, buffer};
-	state->open     = (psycString) {1, "["};
+	state->open    = (psycString) {1, "["};
-	state->close    = (psycString) {1, "]"};
+	state->close   = (psycString) {1, "]"};
 }
 
 /**
- * Initializes the PSYC text state struct with custom open & closing braces.
+ * Initializes the PSYC text state struct with custom opening & closing braces.
  *
  * @param state Pointer to the PSYC text state struct that should be initialized.
- * @param template Text template to be parsed.
+ * @param tmpl Input buffer with text template to be parsed.
- * @param tlen Length of template.
+ * @param tmplen Length of input buffer.
- * @param buffer Buffer where the rendered text is going to be written.
+ * @param buffer Output buffer where the rendered text is going to be written.
- * @param blen Length of buffer.
+ * @param buflen Length of output buffer.
  * @param open Opening brace.
  * @param openlen Length of opening brace.
  * @param close Closing brace.
@@ -103,19 +103,21 @@ void psyc_initTextState (psycTextState *state,
  */
 static inline
 void psyc_initTextState2 (psycTextState *state,
-                          char *template, size_t tlen,
+                          const char *tmpl, size_t tmplen,
-                          char *buffer, size_t blen,
+                          char *buffer, size_t buflen,
-                          char *open, size_t openlen,
+                          const char *open, size_t openlen,
-                          char *close, size_t closelen)
+                          const char *close, size_t closelen)
 {
-	state->template = (psycString) {tlen, template};
+	state->cursor  = 0;
-	state->buffer   = (psycString) {blen, buffer};
+	state->written = 0;
-	state->open     = (psycString) {openlen, open};
+	state->tmpl    = (psycString) {tmplen, tmpl};
-	state->close    = (psycString) {closelen, close};
+	state->buffer  = (psycString) {buflen, buffer};
+	state->open    = (psycString) {openlen, open};
+	state->close   = (psycString) {closelen, close};
 }
 
 /**
- * Sets a new buffer in the PSYC text state struct.
+ * Sets a new output buffer in the PSYC text state struct.
  */
 static inline
 void psyc_setTextBuffer (psycTextState *state, psycString buffer)
@@ -149,10 +151,10 @@ size_t psyc_getTextBytesWritten (psycTextState *state)
  * string between these braces. Should the callback return
  * PSYC_TEXT_VALUE_NOT_FOUND, the original template text is copied as is.
  *
- * Before calling this function psyc_initTextState or psyc_initTextState should
+ * Before calling this function psyc_initTextState should be called to initialize
- * be called to initialze the state struct. By default PSYC's "[" and "]" are
+ * the state struct. By default PSYC's "[" and "]" are used but you can provide
- * used but you can provide any other brace strings such as "${" and "}" or
+ * any other brace strings such as "${" and "}" or "<!--" and "-->" if you use
- * "<!--" and "-->".
+ * the psyc_initTextState2 variant.
  *
  * @see http://about.psyc.eu/psyctext
  **/

src/text.c

@@ -3,29 +3,29 @@
 
 psycTextRC psyc_text (psycTextState *state, psycTextCB getValue)
 {
-	const char *start = state->template.ptr, *end; // start & end of variable name
+	const char *start = state->tmpl.ptr, *end; // start & end of variable name
-	const char *prev = state->template.ptr + state->cursor;
+	const char *prev = state->tmpl.ptr + state->cursor;
 	psycString value;
 	int ret;
 	size_t len;
 	uint8_t no_subst = (state->cursor == 0); // whether we can return NO_SUBST
 
-	while (state->cursor < state->template.length)
+	while (state->cursor < state->tmpl.length)
 	{
-		start = memmem(state->template.ptr + state->cursor,
+		start = memmem(state->tmpl.ptr + state->cursor,
-		               state->template.length - state->cursor,
+		               state->tmpl.length - state->cursor,
 		               state->open.ptr, state->open.length);
 		if (!start)
 			break;
 
-		state->cursor = (start - state->template.ptr) + state->open.length;
+		state->cursor = (start - state->tmpl.ptr) + state->open.length;
-		if (state->cursor >= state->template.length)
+		if (state->cursor >= state->tmpl.length)
 			break; // [ at the end
 
-		end = memmem(state->template.ptr + state->cursor,
+		end = memmem(state->tmpl.ptr + state->cursor,
-		             state->template.length - state->cursor,
+		             state->tmpl.length - state->cursor,
 		             state->close.ptr, state->close.length);
-		state->cursor = (end - state->template.ptr) + state->close.length;
+		state->cursor = (end - state->tmpl.ptr) + state->close.length;
 
 		if (!end)
 			break; // ] not found
@@ -40,12 +40,12 @@ psycTextRC psyc_text (psycTextState *state, psycTextCB getValue)
 		if (ret < 0)
 			continue; // value not found, no substitution
 
-		// first copy the part in the template from the previous subst. to the current one
+		// first copy the part in the input from the previous subst. to the current one
 		// if there's enough buffer space for that
 		len = start - prev;
 		if (state->written + len > state->buffer.length)
 		{
-			state->cursor = prev - state->template.ptr;
+			state->cursor = prev - state->tmpl.ptr;
 			return PSYC_TEXT_INCOMPLETE;
 		}
 
@@ -55,7 +55,7 @@ psycTextRC psyc_text (psycTextState *state, psycTextCB getValue)
 		// now substitute the value if there's enough buffer space
 		if (state->written + value.length > state->buffer.length)
 		{
-			state->cursor = start - state->template.ptr;
+			state->cursor = start - state->tmpl.ptr;
 			return PSYC_TEXT_INCOMPLETE;
 		}
 
@@ -63,7 +63,7 @@ psycTextRC psyc_text (psycTextState *state, psycTextCB getValue)
 		state->written += value.length;
 
 		// mark the start of the next chunk of text in the template
-		prev = state->template.ptr + state->cursor;
+		prev = state->tmpl.ptr + state->cursor;
 		no_subst = 0;
 	}
 
@@ -71,7 +71,7 @@ psycTextRC psyc_text (psycTextState *state, psycTextCB getValue)
 		return PSYC_TEXT_NO_SUBST;
 
 	// copy the rest of the template after the last var
-	len = state->template.length - (prev - state->template.ptr);
+	len = state->tmpl.length - (prev - state->tmpl.ptr);
 	if (state->written + len > state->buffer.length)
 		return PSYC_TEXT_INCOMPLETE;