DGD Library
Version: 0.1.0.14 | Updated: Thu Aug 10 16:59:35 2006
Home Documentation FAQ Download Sourceforge SVN
Home
DGD News
FAQ
Code Documentation
DGD Installation Guide
Bugs-n-Features
DGD at Sourceforge.net
Download DGD
Subversion
Code Documentation
Documentation
Namespaces
Class Hierarchy
Class List
File List
Namespace Members
Functions
Globals
Tutorial
Main Page   Namespace List   Class Hierarchy   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

DGD Basics - Formatting

Channelbuf makes no physical output. Instead, it makes some formatting on what it gets and then pipes already formatted output to the associated physical stream. In this chapter we will learn how the formatting is done. Consider the following example: 
// format output with channelbuf

#include <dgChannel.h>
#include <dgStream.h>

main( int argc, char** argv ) {
   DGD::channel formatter( "formatter" );

   DGD::assoc( &std::cout, formatter );
   formatter.open();

   formatter << "Hello! This is actally very very very " 
             << "very very very very very very very very " 
             << "very very very very very very very long line!" 
             << "longer then " << formatter.max_width() << "!"
             << std::endl;

   formatter.max_width( 40 );

   formatter << "Hello! This is another very very very " 
             << "very very very very very very very very " 
             << "very very very very very very very long line!" 
             << "longer then " << formatter.max_width() << "!"
             << std::endl;

   formatter.word_wrap( false );

   formatter << "Hello! This is another very very very " 
             << "very very very very very very very very " 
             << "very very very very very very very long line!" 
             << "longer then " << formatter.max_width() << "!"
             << std::endl;

   formatter.word_wrap( true );

   formatter.space_chars(" \t;");
   formatter.max_width( 4 );
   formatter << "a;b;c;d;e;f;g;h" << std::endl;

   formatter.max_width( 60 );
   formatter.space_chars(" \t");
   
   for( int i = 0; i < 76; i++ ) {
      formatter << "word ";
      if( i > 0 && i % 15 == 0 ) {
         formatter << std::endl;
         if( i < 32 )
            formatter.incr_indent();
         else 
            formatter.decr_indent();
      }
   }

   return 0;
}
Note that in this example DGD::channel is used instead of directly using DGD::channelbuf . DGD::channel is a output stream which hides complexities of using channelbuf and encapsulates all of its functionality. Note also that DGD::channel always has name and must be explicitly opened and associated with physical stream: 
   DGD::assoc( &std::cout, formatter );
   formatter.open();

Wrapping

The very basic feature of the DGD formatting is a maximum line length and wrapping. By default word wrapping is turned on and maximum line length is 79, so the following line: 
   formatter << "Hello! This is actally very very very " 
             << "very very very very very very very very " 
             << "very very very very very very very long line!" 
             << "longer then " << formatter.max_width() << "!"
             << std::endl;
will produce the following output: 
 Hello! This is actally very very very very very very very very ver very very
 very very very very very very very long line!longer then 79!
The maximum line width can be easily changed. For example the line: 
   formatter.max_width( 40 );
and same output will produce the following: 
 Hello! This is another very very very
 very very very very very very very very
 very very very very very very very
 long line!longer then 40!
Note how DGD breaks the line. The line is split at spaces between words, not at the exact 40x positions. This is called word wrapping. The word wrapping can be turned off: 
   formatter.word_wrap( false );
The output will look like this: 
 Hello! This is another very very very ve
 ry very very very very very very very ve
 ry very very very very very very long li
 ne!longer then 40!
If you don't want the lines being wrapped you can turn the wrapping off by using DGD::channel::wrap(bool) method.

You can tell DGD what characters are considered white spaces to change word wrapping behavior: 

   formatter.space_chars(" \t;");
   formatter.max_width( 4 );
   formatter << "a;b;c;d;e;f;g;h" << std::endl;
The DGD::space_chars() method receives a string containing a set of characters which will be considered as white spaces. The output will look like this: 
 a;b
 ;c;
 d;e
 ;f;
 g;h
Note that here word wrapping is enabled and maximum width is defined to 4, but there are only 3 characters in a line. This is because the '\n' in the end of each line is considered as a separate character.

Indentation

DGD output can be indented. This means that you can define amount of blanks filled before any actual line of output. Consider the following code: 
   formatter.max_width( 60 );
   formatter.space_chars(" \t");
   
   for( int i = 0; i < 76; i++ ) {
      formatter << "word ";
      if( i > 0 && i % 15 == 0 ) {
         formatter << std::endl;
         if( i < 32 )
            formatter.incr_indent();
         else 
            formatter.decr_indent();
      }
   }
The following output will be produced: 
 word word word word word word word word word word word word
 word word word word
        word word word word word word word word word word
        word word word word word
                word word word word word word word word
                word word word word word word word
        word word word word word word word word word word
        word word word word word
 word word word word word word word word word word word word
  word word word
Note that the filled blanks are considered as part of the line so overall line width does not exceed the 60 characters limit.

This code demonstrates indentation level mechanism. DGD::channel::incr_indent() and DGD::channel::decr_indent() methods increment/decrement the current indentation level. The actual number of filled blanks is calculated at the beginning of each line (thus, the incr_indent() and decr_indent() take no effect until beginning of the next line). The indentation level value is multiplied by indentation step value and the calculated amount of blanks is filled to the output. The indentation step can be controlled by DGD::channel::indent_step(unsigned) method. The default indentation step value is 8.

You can set the exact amount of indentation spaces using DGD::channel::indent(unsigned) method.

Note that theoretically the indentation level could exceed the maximum line width. In this case DGD considers minimum line width property of the DGD::channel or DGD::channelbuf. Minimum line width tells DGD to skip indentation and keep the actual output line at least "min_width" characters wide. Minimum width is controlled by DGD::channel::min_width(unsigned) method. The default value for minimum width is 20.

Generated on Thu Aug 10 16:48:29 2006 for DGD Library by doxygen1.3

SourceForge.net Logo Powered by Mason Powered by Perl
Web design derived from Pasilda design found on www.oswd.org.
Copyright (c) 2002, 2003. Dimitry Kloper <kloper@users.sourceforge.net>