38dd9122b6a2e1fefb229f37d95686a7fa80c4a3
tdreszer
  Fri Apr 15 17:49:09 2011 -0700
Initial checkin of continuation char support in RA files
diff --git src/inc/ra.h src/inc/ra.h
index 4e8d085..a2a925b 100644
--- src/inc/ra.h
+++ src/inc/ra.h
@@ -1,45 +1,63 @@
 /* Stuff to parse .ra files. Ra files are simple text databases.
  * The database is broken into records by blank lines.
  * Each field takes a line.  The name of the field is the first
  * word in the line.  The value of the field is the rest of the line.
  *
  * This file is copyright 2002 Jim Kent, but license is hereby
  * granted for all use - public, private or commercial. */
 
 #ifndef RA_H
 
-struct hash *raNextRecord(struct lineFile *lf);
-/* Return a hash containing next record.
- * Returns NULL at end of file.  freeHash this
- * when done.  Note this will free the hash
- * keys and values as well, so you'll have to
- * cloneMem them if you want them for later. */
+struct hash *raNextStanza(struct lineFile *lf,boolean unjoined);
+// Return a hash containing next record, or NULL at end of file.
+// Will ignore '#' comments and if requsted, joins lines ending in continuation char.
+// freeHash this when done.  Note this will free the hash keys and values as well,
+// so you'll have to cloneMem them if you want them for later.
+#define raNextRecord(lf)         raNextStanza((lf),TRUE)
+#define raNextRecordUnjoined(lf) raNextStanza((lf),FALSE)
 
-struct slPair *raNextRecordAsSlPairList(struct lineFile *lf);
-/* Return ra record as a slPair list instead of a hash.  Handy if you want to preserve the order.
- * Do a slPairFreeValsAndList on result when done. */
+struct slPair *raNextStanzAsPairs(struct lineFile *lf,boolean unjoined);
+// Return ra stanza as an slPair list instead of a hash.  Handy to preserve the order.
+// Will ignore '#' comments and if requsted, join lines ending in continuation char '\'.
+#define raNextRecordAsSlPairList(lf)         raNextStanzAsPairs((lf),TRUE)
+#define raNextRecordUnjoinedAsSlPairList(lf) raNextStanzAsPairs((lf),FALSE)
+
+struct slPair *raNextStanzaLinesAndUntouched(struct lineFile *lf);
+// Return list of lines starting from current position, up through last line of next stanza.
+// May return a few blank/comment lines at end with no real stanza.
+// Will join continuation lines, allocating memory as needed.
+// returns pairs with name=joined line and if joined,
+// val will contain raw lines '\'s and linefeeds, else val will be NULL.
 
 boolean raSkipLeadingEmptyLines(struct lineFile *lf, struct dyString *dy);
 /* Skip leading empty lines and comments.  Returns FALSE at end of file.
  * Together with raNextTagVal you can construct your own raNextRecord....
  * If dy parameter is non-null, then the text parsed gets placed into dy. */
 
 boolean raNextTagVal(struct lineFile *lf, char **retTag, char **retVal, struct dyString  *dy);
-/* Read next line.  Return FALSE at end of file or blank line.  Otherwise
- * fill in *retTag and *retVal and return TRUE.
- * If dy parameter is non-null, then the text parsed gets appended to dy. */
+// Read next line.  Return FALSE at end of file or blank line.  Otherwise fill in
+// *retTag and *retVal and return TRUE.  If dy parameter is non-null, then the text parsed
+// gets appended to dy. Continuation lines in RA file will be joined to produce tag and val,
+// but dy will be filled with the unedited multiple lines containing the continuation chars.
+
+boolean raNextTagValUnjoined(struct lineFile *lf, char **retTag, char **retVal, struct dyString *dyRecord);
+// NOTE: this is the former raNextTagVal routine is ignorant of continuation lines.
+//       It is provided in case older RAs need it.
+// Read next line.  Return FALSE at end of file or blank line.  Otherwise
+// fill in *retTag and *retVal and return TRUE.
+// If dy parameter is non-null, then the text parsed gets appended to dy.
 
 struct hash *raFromString(char *string);
 /* Return hash of key/value pairs from string.
  * As above freeHash this when done. */
 
 boolean raFoldInOne(struct lineFile *lf, struct hash *hashOfHash);
 /* Fold in one record from ra file into hashOfHash.
  * This will add ra's and ra fields to whatever already
  * exists in the hashOfHash,  overriding fields of the
  * same name if they exist already. */
 
 void raFoldIn(char *fileName, struct hash *hashOfHash);
 /* Read ra's in file name and fold them into hashOfHash.
  * This will add ra's and ra fields to whatever already
  * exists in the hashOfHash,  overriding fields of the