Re: [boost] [iostreams]ANNOUNCE:indent_filtering_ostream.zip in vault

Subject: Re: [boost] [iostreams]ANNOUNCE:indent_filtering_ostream.zip in vault
From: dherring_at_[hidden]
Date: 2010-01-13 12:17:50

On Tue, 12 Jan 2010, Larry Evans wrote:
> On 01/12/10 11:29, dherring_at_[hidden] wrote:
>> On Mon, 11 Jan 2010, vicente.botet wrote:
>>> From: "Larry Evans" <cppljevans_at_[hidden]>
>>>>
>>>> The .zip file in subject is here:
>>>>
>>>> http://www.boostpro.com/vault/index.php?&directory=Input%20-%20Output
>>>>
> [snip]
>> I wrote a similar utility, but made different tradeoffs.  The basic
>> usage looks like
>>
>> Indentation nl; // takes optional max depth and depth/level params
>> Indentation::Indent in(nl); // could have used a reference notation
>> Indentation::Outdent out(nl);
>> std::ostream os;
>> os << nl "class x
>>    << nl << '{' << in /* or nl.in */
>>    << nl << "int x;"
>>    << nl << "int y;" << out
>>    << nl << "};"
>>
>> Rationale:
>> - operator++ and operator-- don't mix "as expected" with operator<<
>
> The functions provided in the indent_filtering_ostream.hpp include:
>
>   indent_in
>   indent_out

Ok, I didn't see these; I just looked at the previous email's example.

>> - distinguishes between indenting and normal newlines
>
> I'm not sure what this means.  Does it mean that to indent
> a line, you have to use nl, as shown in this snippet of the code
> you posted:
>
> >    << nl << "int x;"
>
> If so, then I'm not sure that's an advantage.  Could you
> please elaborate on what you mean?

Yes.  In my work, this is a great advantage.  People don't like text with 
trailing whitespaces, but they want blank lines for visual separation.

I could see an argument for having \n indent and nl not; it may make it 
easier to compose indentation with output functions that do not understand 
it.  However, my experience has been that an indenting newlines 
semantically belong before the line text while a traditional \n appears 
after the text.  This creates a mismatch; a general indentation tool 
should probably have a (scoped) mechanism for switching behaviors.

Example: (pseudo C++)
// code oblivious to indentation
ostream & operator<<(ostream &os, vector<int> &v)
{
   for(x=v.begin(); x!=v.end(); x++)
     os << x << "\n";
   return os;
}
// pretty printing
void pretty(Struct s)
{
   out << nl << "Struct s" << indent
       << nl << "x=" << s.x
       << nl << "vector=" << indent // one item per line
       << nl << s.vector << outdent
       << nl << "y=" << s.y << outdent;
}

This will give
Struct s
   x=5
   vector=
     1
     2
     3

   y=6

Note the undesired newline.  But if nl appears in the traditional \n 
location, you have the issue of undesired indentation (the inner printer 
has to anticipate outdents in the outer) or extra buffering to clean such 
mistakes.

I have had the best results by putting nl first and defining "pretty 
printers" that use it for each type I want to print.

>> - possible to maintain several indentation systems
>
> Could you describe when this would be an advantage?

This is rarely useful, but there are times when indentation differentiates 
between classes of output line.  This is naturally represented by having 
one indentation object per class.

- Daniel