#include <TextOutput.h>

Classes
class	Settings

Public Member Functions
	TextOutput (const std::string &filename, const Settings &options=Settings())

	TextOutput (const Settings &options=Settings())

int	line () const

void	commit (bool flush=true)

void	commitString (std::string &string)

void	pushIndent ()

void	popIndent ()

std::string	commitString ()

void	writeString (const std::string &string)

void	writeBoolean (bool b)

void	writeNumber (double n)

void	writeNumber (int n)

void	writeNewline ()

void	writeNewlines (int numLines)

bool	deleteSpace ()

void	writeSymbol (const std::string &string)

void	writeSymbol (char s)

void	writeSymbols (const std::string &a, const std::string &b="", const std::string &c="", const std::string &d="", const std::string &e="", const std::string &f="")

void __cdecl	printf (const char *fmt,...) G3D_CHECK_PRINTF_METHOD_ARGS

void __cdecl	printf (const std::string fmt,...)

void __cdecl	vprintf (const char *fmt, va_list argPtr) G3D_CHECK_VPRINTF_METHOD_ARGS

Private Member Functions
void	setIndentLevel (int i)

void	setOptions (const Settings &_opt)

void	convertNewlines (const std::string &in, std::string &out)

void	wordWrapIndentAppend (const std::string &str)

void	indentAppend (char c)

Private Attributes
bool	startingNewLine

int	currentColumn

bool	inDQuote

std::string	filename

Array< char >	data

Settings	option

int	indentLevel

int	indentSpaces

std::string	newline

int	m_currentLine

Detailed Description

Convenient formatting of ASCII text written to a file.

The core writeString, writeNumber, and writeSymbol methods map to TextInput's methods. Number and Symbol each print an additional space that is used to separate adjacent tokens.

TextOutput::printf allows arbitrary text to be conveniently dumped en-masse. Use [de]serialize(bool, TextOutput) and other overloads to read/write primitive types in a standardized manner and

When a word-wrap line break occurs, all whitespace between words is replaced with a single newline (the newline may be two characters– see G3D::TextOutput::Options::NewlineStyle). Word wrapping occurs against the number of columns specified by Options::numColumns, minus the current indent level.

Indenting adds the specified number of spaces immediately after a newline. If a newline was followed by spaces in the original string, these are added to the indent spaces. Indenting will indent blank lines and will leave indents after the last newline of a file (if the indent level is non-zero at the end).

Serialization/Marshalling

Text serialization is accomplished using TextOutput by defining the pair of methods:

void serialize(TextOutput& to) const;
void deserialize(TextInput& ti);

Constructor & Destructor Documentation

G3D::TextOutput::TextOutput	(	const std::string &	filename,
		const Settings &	options = `Settings()`
	)

explicit

  :
  startingNewLine(true),
  currentColumn(0),
  inDQuote(false),
  filename(fil),
  indentLevel(0),
  m_currentLine(0)
 {
 
  setOptions(opt);
 }

Here is the call graph for this function:

G3D::TextOutput::TextOutput ( const Settings & options = Settings() )

explicit

Constructs a text output that can later be commited to a string instead of a file.

  :
  startingNewLine(true),
  currentColumn(0),
  inDQuote(false),
  filename(""),
  indentLevel(0),
  m_currentLine(0)
 {
  setOptions(opt);
 }

Here is the call graph for this function:

Member Function Documentation

void G3D::TextOutput::commit ( bool flush = true )

Commit to the filename specified on the constructor. Not called from the destructor; you must call it yourself.

Parameters

flush If true (default) the file is ready for reading when the method returns, otherwise the method returns immediately and writes the file in the background.

  {
  std::string p = filenamePath(filename);
  if (! FileSystem::exists(p, false)) {
  FileSystem::createDirectory(p);
  }
 
  FILE* f = FileSystem::fopen(filename.c_str(), "wb");
  debugAssertM(f, "Could not open \"" + filename + "\"");
  fwrite(data.getCArray(), 1, data.size(), f);
  if (flush) {
  fflush(f);
  }
  FileSystem::fclose(f);
 }

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::TextOutput::commitString ( std::string & string )

Commits to this string

  {
  // Null terminate
  data.push('\0');
  out = data.getCArray();
  data.pop();
 }

Here is the call graph for this function:

Here is the caller graph for this function:

std::string G3D::TextOutput::commitString ( )

Produces a new string that contains the output

  {
  std::string str;
  commitString(str);
  return str;
 }

void G3D::TextOutput::convertNewlines	(	const std::string &	in,
		std::string &	out
	)

private

Converts to the desired newlines. Called from vprintf

  {
  // TODO: can be significantly optimized in cases where
  // single characters are copied in order by walking through
  // the array and copying substrings as needed.
 
  if (option.convertNewlines) {
  out = "";
  for (uint32 i = 0; i < in.size(); ++i) {
  if (in[i] == '\n') {
  // Unix newline
  out += newline;
  } else if ((in[i] == '\r') && (i + 1 < in.size()) && (in[i + 1] == '\n')) {
  // Windows newline
  out += newline;
  ++i;
  } else {
  out += in[i];
  }
  }
  } else {
  out = in;
  }
 }

Here is the caller graph for this function:

bool G3D::TextOutput::deleteSpace ( )

If the most recently written character was a space, remove it and return true. Can be called repeatedly to back up over multiple spaces.

  {
  if ((currentColumn > 0) && (data.last() == ' ')) {
  data.popDiscard();
  --currentColumn;
  return true;
  } else {
  return false;
  }
 }

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::TextOutput::indentAppend ( char c )

private

Appends the character to data, indenting whenever a newline is encountered. Called from wordWrapIndentAppend

  {
 
  if (startingNewLine) {
  for (int j = 0; j < indentSpaces; ++j) {
  data.push(' ');
  }
  startingNewLine = false;
  currentColumn = indentSpaces;
  }
 
  data.push(c);
 
  // Don't increment the column count on return character
  // newline is taken care of below.
  if (c != '\r') {
  ++currentColumn;
  }
  
  if (c == '\"') {
  inDQuote = ! inDQuote;
  }
 
  startingNewLine = (c == '\n');
  if (startingNewLine) {
  currentColumn = 0;
  ++m_currentLine;
  }
 }

Here is the call graph for this function:

Here is the caller graph for this function:

int G3D::TextOutput::line ( ) const

inline

Returns one plus the number of newlines written since the output was created.

  {
  return m_currentLine;
  }

Here is the caller graph for this function:

void G3D::TextOutput::popIndent ( )

  {
  setIndentLevel(indentLevel - 1);
 }

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::TextOutput::printf	(	const char *	fmt,
			...
	)

Normal printf conventions. Note that the output will be reformatted for word-wrapping and newlines

  {
  va_list argList;
  va_start(argList, formatString);
  this->vprintf(formatString, argList);
  va_end(argList);
 }

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::TextOutput::printf	(	const std::string	fmt,
			...
	)

  {
  va_list argList;
  va_start(argList, formatString);
  this->vprintf(formatString.c_str(), argList);
  va_end(argList);
 }

Here is the call graph for this function:

void G3D::TextOutput::pushIndent ( )

Increase indent level by 1

  {
  setIndentLevel(indentLevel + 1);
 }

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::TextOutput::setIndentLevel ( int i )

private

  {
  indentLevel = i;
 
  // If there were more pops than pushes, don't let that take us below 0 indent.
  // Don't ever indent more than the number of columns.
  indentSpaces = 
  iClamp(option.spacesPerIndent * indentLevel, 
  0, 
  option.numColumns - 1);
 }

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::TextOutput::setOptions ( const Settings & _opt )

private

  {
  option = _opt;
 
  debugAssert(option.numColumns > 1);
 
  setIndentLevel(indentLevel);
 
  newline = (option.newlineStyle == Settings::NEWLINE_WINDOWS) ? "\r\n" : "\n";
 }

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::TextOutput::vprintf	(	const char *	fmt,
		va_list	argPtr
	)

  {
  const std::string& str = vformat(formatString, argPtr);
 
  std::string clean;
  convertNewlines(str, clean);
  wordWrapIndentAppend(clean);
 }

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::TextOutput::wordWrapIndentAppend ( const std::string & str )

private

Called from vprintf

  {
  // TODO: keep track of the last space character we saw so we don't
  // have to always search.
 
  if ((option.wordWrap == Settings::WRAP_NONE) ||
  (currentColumn + (int)str.size() <= option.numColumns)) {
  // No word-wrapping is needed
 
  // Add one character at a time.
  // TODO: optimize for strings without newlines to add multiple
  // characters.
  for (uint32 i = 0; i < str.size(); ++i) {
  indentAppend(str[i]);
  }
  return;
  }
 
  // Number of columns to wrap against
  int cols = option.numColumns - indentSpaces;
  
  // Copy forward until we exceed the column size, 
  // and then back up and try to insert newlines as needed.
  for (uint32 i = 0; i < str.size(); ++i) {
 
  indentAppend(str[i]);
  if ((str[i] == '\r') && (i + 1 < str.size()) && (str[i + 1] == '\n')) {
  // \r\n, we need to hit the \n to enter word wrapping.
  ++i;
  indentAppend(str[i]);
  }
 
  if (currentColumn >= cols) {
  debugAssertM(str[i] != '\n' && str[i] != '\r',
  "Should never enter word-wrapping on a newline character"); 
 
  // True when we're allowed to treat a space as a space.
  bool unquotedSpace = option.allowWordWrapInsideDoubleQuotes || ! inDQuote;
 
  // Cases:
  //
  // 1. Currently in a series of spaces that ends with a newline
  // strip all spaces and let the newline
  // flow through.
  //
  // 2. Currently in a series of spaces that does not end with a newline
  // strip all spaces and replace them with single newline
  //
  // 3. Not in a series of spaces
  // search backwards for a space, then execute case 2.
 
  // Index of most recent space
  size_t lastSpace = data.size() - 1;
 
  // How far back we had to look for a space
  size_t k = 0;
  size_t maxLookBackward = currentColumn - indentSpaces;
 
  // Search backwards (from current character), looking for a space.
  while ((k < maxLookBackward) &&
  (lastSpace > 0) &&
  (! ((data[(int)lastSpace] == ' ') && unquotedSpace))) {
  --lastSpace;
  ++k;
 
  if ((data[(int)lastSpace] == '\"') && !option.allowWordWrapInsideDoubleQuotes) {
  unquotedSpace = ! unquotedSpace;
  }
  }
 
  if (k == maxLookBackward) {
  // We couldn't find a series of spaces
 
  if (option.wordWrap == Settings::WRAP_ALWAYS) {
  // Strip the last character we wrote, force a newline,
  // and replace the last character;
  data.pop();
  writeNewline();
  indentAppend(str[i]);
  } else {
  // Must be Settings::WRAP_WITHOUT_BREAKING
  //
  // Don't write the newline; we'll come back to
  // the word wrap code after writing another character
  }
  } else {
  // We found a series of spaces. If they continue 
  // to the new string, strip spaces off both. Otherwise
  // strip spaces from data only and insert a newline. 
 
  // Find the start of the spaces. firstSpace is the index of the
  // first non-space, looking backwards from lastSpace.
  size_t firstSpace = lastSpace;
  while ((k < maxLookBackward) &&
  (firstSpace > 0) &&
  (data[(int)firstSpace] == ' ')) {
  --firstSpace;
  ++k;
  }
 
  if (k == maxLookBackward) {
  ++firstSpace;
  }
 
  if (lastSpace == (uint32)data.size() - 1) {
  // Spaces continued up to the new string
  data.resize(firstSpace + 1);
  writeNewline();
 
  // Delete the spaces from the new string
  while ((i < str.size() - 1) && (str[i + 1] == ' ')) {
  ++i;
  }
  } else {
  // Spaces were somewhere in the middle of the old string.
  // replace them with a newline.
 
  // Copy over the characters that should be saved
  Array<char> temp;
  for (size_t j = lastSpace + 1; j < (uint32)data.size(); ++j) {
  char c = data[(int)j];
 
  if (c == '\"') {
  // Undo changes to quoting (they will be re-done
  // when we paste these characters back on).
  inDQuote = !inDQuote;
  }
  temp.append(c);
  }
 
  // Remove those characters and replace with a newline.
  data.resize(firstSpace + 1);
  writeNewline();
 
  // Write them back
  for (size_t j = 0; j < (uint32)temp.size(); ++j) {
  indentAppend(temp[(int)j]);
  }
 
  // We are now free to continue adding from the
  // new string, which may or may not begin with spaces.
 
  } // if spaces included new string
  } // if hit indent
  } // if line exceeded
  } // iterate over str
 }

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::TextOutput::writeBoolean ( bool b )

  {
  this->printf("%s ", b ? option.trueSymbol.c_str() : option.falseSymbol.c_str());
 }

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::TextOutput::writeNewline ( )

  {
  for (uint32 i = 0; i < newline.size(); ++i) {
  indentAppend(newline[i]);
  }
 }

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::TextOutput::writeNewlines ( int numLines )

  {
  for (int i = 0; i < numLines; ++i) {
  writeNewline();
  }
 }

Here is the call graph for this function:

void G3D::TextOutput::writeNumber ( double n )

  {
  this->printf("%g ", n);
 }

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::TextOutput::writeNumber ( int n )

  {
  this->printf("%d ", n);
 }

Here is the call graph for this function:

void G3D::TextOutput::writeString ( const std::string & string )

Writes a quoted string. Special characters in the string (e.g., \, \t, \n) are escaped so that TextInput will produce the identical string on reading.

  {
  // Never break a line in a string
  const Settings::WordWrapMode old = option.wordWrap;
 
  if (! option.allowWordWrapInsideDoubleQuotes) {
  option.wordWrap = Settings::WRAP_NONE;
  }
  // Convert special characters to escape sequences
  this->printf("\"%s\"", escape(string).c_str());
  option.wordWrap = old;
 }

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::TextOutput::writeSymbol ( const std::string & string )

The symbol is written without quotes. Symbols are required to begin with a letter or underscore and contain only letters, underscores, and numbers or be a C++ symbol (e.g. "{", "(", "++", etc.) so that they may be properly parsed by TextInput::readSymbol. Symbols are printed with a trailing space.

  {
  if (string.size() > 0) {
  this->printf("%s ", string.c_str());
  }
 }

Here is the call graph for this function:

Here is the caller graph for this function:

void G3D::TextOutput::writeSymbol ( char s )

  {
  this->printf("%c ", c);
 }

Here is the call graph for this function:

void G3D::TextOutput::writeSymbols	(	const std::string &	a,
		const std::string &	b = `""`,
		const std::string &	c = `""`,
		const std::string &	d = `""`,
		const std::string &	e = `""`,
		const std::string &	f = `""`
	)

Convenient idiom for writing multiple symbols in a row, e.g. writeSymbols("name", "="); The empty symbols are not written.

  {
 
  writeSymbol(a);
  writeSymbol(b);
  writeSymbol(c);
  writeSymbol(d);
  writeSymbol(e);
  writeSymbol(f);
 }

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

int G3D::TextOutput::currentColumn

private

Number of characters at the end of the buffer since the last newline

Array<char> G3D::TextOutput::data

private

std::string G3D::TextOutput::filename

private

Empty if there is none

int G3D::TextOutput::indentLevel

private

Number of indents to prepend before each line. Always set using setIndentLevel.

int G3D::TextOutput::indentSpaces

private

Actual number of spaces to indent.

bool G3D::TextOutput::inDQuote

private

True if we have seen an open " and no close ".

int G3D::TextOutput::m_currentLine

private

Starts at 1

std::string G3D::TextOutput::newline

private

the newline character(s)

Settings G3D::TextOutput::option

private

bool G3D::TextOutput::startingNewLine

private

Used by indentAndAppend to tell when we are writing the first character of a new line.

So that push/popIndent work correctly, we cannot indent immediately after writing a newline. Instead we must indent on writing the first character after that newline.

The documentation for this class was generated from the following files:

dep/g3dlite/include/G3D/TextOutput.h
dep/g3dlite/source/TextOutput.cpp

Classes

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation