Re: [boost] IO Collection Framework (Output Formatters REDESIGN)
[I cc the mailing list]
Use () if you want to get the value of a decoration:
sep() == "|"; // instrinsinc value
Why would I want to do this?
In case you need to get the value directly and not lookup based on the stream.
Does the user ever need to do it? Or it's internal mechanism?
sep( std::cout ) == "|"; // stream default if sep() == std::string()
So, this means: 'value in sep if any, otherwise value in stream'?
Yes. There is currently a bug in the implementation if you use "" as a decorator value (i.e. no decoration) where it will choose the default value. I am planning to use "\1 def" - a value that is not likely to be used.
Why not fixing the bug? Using "\1 def" for empty decorator is not nice.
If you want to see if a decorator is on an input stream, you can use match:
io::match( std::cin, sep );
What are the use cases for this?
It is primarily used to implement the read function of a format object. e.g.:
template< class TraitsT, typename F, typename S > std::basic_istream< CharT, TraitsT > & in( std::basic_istream< CharT, TraitsT > & is, F & f, S & s ) const { if( !( match( is, open ) && first.read( is, f ) &&
Ouch! So 'match' in fact reads 'sep' from the input stream. Your original comment made me thing that it somehow checks that 'sep' is equal to the decorator associated with the stream -- and that made me wonder why it's needed.
wrap.decorate( "[[ ", " ]]" ); wrap2.decorate( wrap );
Why do I need the 'decorate' method as opposed to
wrap = wrapper_decorators<char>("<", ">")
or
wrap.assign("[[", "]]")
The idea that I can decorate a decorator does not seems good for me. Why do I need to change decorators in this way?
At the moment, the default values on the stream applies to all types. That is, the default value is associated with the decorator id argument.
I can see why decorate would not be a good name, but assign is not good either. Consider:
io::object( vec ).decorate( " / " ); // decorate io::object io::object( vec ).assign( " / " ); // assign what?
What I am trying to aim for is:
io::object( vec ).separator( " | " ) .openclose( "< ", " >" );
but I need to work on implementability (i.e. maintaining the current functionality). Maybe 'set' would be better for setting the decoration based on all 3 values or another sequence_decoration object.
Probably. I agree that 'assign' in above example is not good.
To change them, I need to access decorators stored on the stream. How do I do that?
Use io::decorate< CharT > or the c/wdecorate typedefs like this:
std::cout << io::cdecorate( "[[ ", " ]]" ) << io::object( vec ) << '\n';
RATIONALE: RetType -- a class may derive from this class and you may want to chain function calls. For example:
derived_class dc; dc.decorate( "/ ", " /" ).derived_fn();
RetType is needed to allow this type of behaviour.
Do you have the need for it at the moment? If not, I suggest you drop this template argument. I had something similar in program_options and was messy, did not work everywhere and added no value.
It is needed: the format objects can be passed as arguments to other format objects. Without the above, this code will not work:
io::object( vec, fmt::container().decorate( " : " )); -------------------------------------^ [error]: cannot find function 'write' in 'sequence_decorators'.
You mean that container_formatter derives from sequence_decorators and without RetType the value of fmt::container().decorate() will be sequence_decorators. Looks reasonable, but why not: fmt::container(open_close_delimiters("[", "]"))
io::sequence_decorators< char > seq5( wrap );
Do I ever need to use this constructor?
Do you mean seq5( wrap )? I don't know. It would depend on what you are using the library for. I have tried to keep the same arguments for the constructors and decorator() function.
I suspect that user will always specify formatting manually and has no need to convert formatting like this.
[6] n-ary objects
An n-ary object (currently, 2-ary, 4-ary and 8-ary objects are supported) is a statically-sized sequence of n elements. There is support here for describing how one of these types is constructed and for manipulating its elements.
In order to get the nth element of an n-ary object ob, you can use getval:
std::cout << io::getval< n >( ob ) << '\n';
Isn't 'getval' an implementation detail of the library?
In that it is used to implement the fmt::pair_t and fmt::nary_t classes.
I'd suggest you clearly document that it's implementation detail to reduce the amount of information which must be read.
BOOST_IO_NARY_PARAM2 is used to register a 2-ary type as containing two different types for elements 1 and 2, e.g. std::pair. BOOST_IO_NARY_PARAM1 is used in all other cases.
BOOST_IO_NARY_PARAM2( std::pair, seperable_pair ) BOOST_IO_NARY_PARAM1( std::complex, inseperable_pair< T > )
And what about 4-ary objects? Still BOOST_IO_NARY_PARAM1? What if there are 4 different template parameters?
BOOST_IO_NARY_PARAM1( boost::math::quaternion, nary4_type< T > ) BOOST_IO_NARY_PARAM1( boost::math::octonion, nary8_type< T > )
The current implementation of n-ary types only supports different template parameters on 2-ary types. What would be better is something like:
naryN_type< T1, ..., Tn = Tn-1 >
The fmt::nary_t format object would need to be extended to support FormatObject1..N format objects to render the individual elements.
Right. I wonder what are you going to do with general tuple<>
io::assignval( ob2ary, a, b ); io::assignval( ob4ary, a, b, c, d ); io::assignval( ob8ary, a, b, c, d, e, f, g, h );
I think you're again discussing implementation, not interface. I don't think this function should be initially present in the library public interface.
I see why you would classify it as implementation. It really belongs in an "extenders guide" rather than a "users guide".
Exactly!
For example, if you want to add support for NSPoint (a 2D position structure from the MacOS Cocoa API), you need to know this information, e.g.:
template< int n > float io::getval( const NSPoint & pt ) { return detail::selector< n, float >( pt.x, pt.y ); }
Likewise, if you are writing a format object that allows a different seperator for each division in the output, e.g.:
open e1 s1 e2 s2 e3 s3 e4 close where eX are the elements in the n-ary type and sX are the seperators
you need to know how to use getval, refval and assignval in order to implement the format object in a generic way.
Understood.
[7] automatic type deduction
The fmt::deduce function:
template< typename CharT, typename T > [undefined] fmt::deduce( const T & ob );
will return an instance to the nested format object construct that maps to the class T.
Ok, we've got to interesting part. I don't understand what's "nested format object", what's "construct", and what does it mean for "construct" to map to some class. And you haven't defined "format object" yet.
What I was trying to say with the above sentence is something like:
The type associated with ob may be a simple type or a more complex type
"Type associated with ob"? Is it different from "type of ob"?
like a container or pair type. If the type is a container or other sequence-like type, the elements in this type may be sequence-like types.
A format object is a class that is responsible for reading from and writing to a stream. There are format objects for different types (like containers, arrays and pairs). These take template arguments that specify the format object used to render the elements in the sequence associated with the format object.
The type of the object ob passed to fmt::deduce is mapped to the format object that can render ob. For example, if T = std::pair< std::list< char >, std::complex< float > > then fmt::deduce will return a format object of the type fmt::pair( fmt::container(), fmt::pair())
Now, that is perfectly clear. One question though, if I use deduce(obj), what I can do with the resulting object, except for using it for output? Can I access the nested formatter? If yes, how? If not, then you don't need to deduce nested formatters, the above could return: fmt::pair(fmt::generic_formatter(), fmt::generic_formatter()) where generic_formatter() just calls deduce on the type it's passed and use the returned formatter. In other words: you would not need to have two template parameters for pair_t.
In order to save writing code when several types are implemented by a format object, you can map these types into a formatter class type:
SEQ_TYPE_TO_FORMATTER( nary2value_type, pair_type ); SEQ_TYPE_TO_FORMATTER( nary2base_type, pair_type ); SEQ_TYPE_TO_FORMATTER( nary2int_type, pair_type );
Hmm... what's nary2int_type, nary2base_type and nary2value_type? I though there's only one type category for n-ary objects, now I see two more.
The nary2xxx_type categories belong to the type deduction system. They are used to distinguish between the different typedefs for the element types. Ideally, this would be better as a type trait:
element_type< T >::type where element_type< std::complex >::type == std::complex::value_type element_type< boost::interval >::type == interval::base_type element_type< boost::rational >::type == rational::int_type etc.
Understood.
This would make the deduction system simpler in that you would only need nary2_type. The problem is how this works with things like std::pair. One solution would be to return an mpl type list in this instance.
How does it work now?
As a user, you don't need this, but if you are adding a format object into the type deduction framework, you will need this to extract the nested format object.
Could you rephrase the above?
Yes. I shall update the evolution.html file with the revised wording.
Thanks.
A format object is deduced by defining fmt::detail::deduce_type for the formatter class type
What's "formatter class type"? Is that "type category"?
More like a collapsed type category. For example, the fmt::container_t format object supports seq_container_type (sequential containers), assoc_container_type (associative containers) and set_container_type (set containers). Thus, the format class type for fmt::container_t is seq_container_type. SEQ_TYPE_TO_FORMATTER is used to perform this collapse.
Maybe using jsut "formatter class" would be clearer. And a overview describing the interaction between components is a must. Say, a diagram like: output: object ---- (deduce) ---> formatter --- (operator<<) ---> stream deduce: type - (is_XXX) -> type_category -- (???) ---- > formatter class where arrows join main concepts and paranthethis show the mechanism which converts between those concepts.
template<> struct fmt::detail::deduce_type< type > { template< typename CharT, typename T >
What's 'T' here? The type being output?
Yes
I'm lost again. You have: fmt::detail::get_deducer< CharT, T >::type and template<> struct fmt::detail::deduce_type< type > what is the relationship between the two?
In addition, the format object may provide additional forms to allow format object nesting.
I did not understood what's generator and when it should be used.
A generator is a function that will return a format object. This is similar to make_pair or make_tuple. For example, instead of doing:
fmt::pair_t< char, fmt::container_t< char > >()
you can use the generator functions like this:
fmt::pair( fmt::container())
You know what I'm going to say: a comment is in order.
[9] format objects <2> pair format object
fmt::pair_t< CharT, First, Second > will render 2-ary object types using First to render the first element and Second to render the second. The generator function is fmt::pair() and has the additional form:
[unspecified] fmt::pair( const First & f, const Second & s = basic());
"unspecified"? Shouldn't that be fmt::pair_t<charT, First, Second>?
It is actually
fmt::pair_t< typename First::char_type, First, Second >
I use "unspecified" because the types can be long and complex, for example, io::object returns:
io::object_t < CharT, T, typename fmt::detail::get_deducer < CharT, T
>::type::format_object
and I don't want the return type to distract from the functions specification.
OK.
And BTW, I'm strongly against the "_t" suffix. Does it add any information or you just _t because 'pair' is already used? What about calling the type "pair_formatter"?
I will change the name in the update I am performing.
Good.
And, why do I ever need to create the formatter explicitly? Can I call any methods of it?
You can save a format style, for example:
fmt::pair_t< char > parens; parens.decorate( "( ", " )" );
std::cout << io::object( p1, parens ) // ( a, b ) << io::object( p1 ) // [ a, b ] << io::object( p2, parens ); // ( a, b )
You can also access properties and functions associated with the format object. For example:
fmt::pair_t< char, fmt::pair_t< char > > po; po.first.decorate( " : " ); po.decorate( "<: ", " :>" );
std::cout << io::object( p, po ); // <: [ a : b ], c :>
Ok. I'm not sure how usefull it is, but we get this for free.
I think the name "state format" is a bit unclear. I'd suggest some more explicit pre_format_hook/post_format_hook, or something like that. BTW, some thinks (and I'd agree) that using 'bool' as parameter to function/template is not good. If I look at
state<Foobar, true>()
I have no idea what 'true' means.
I shall find a better name. I am considering using an enumeration to define pre, post and pre_post values. For example:
pre_post_hook< char, pre >() // [hook] elem pre_post_hook< char, post >() // elem [hook] pre_post_hook< char, pre_post >() // [hook] elem [hook]
It may be better to drop this functionality from the initial release of the library.
I think I'd like to be able to output vectors with prepended indices, but I don't know if such generic mechanism is needed. You can have "numbering_formatter", for example, which will output a number of then use nested formatter to output the object itself. If creating formatting is simple, this is better that pre_post_hook, since it's more general.
Finally: you mentioned you have revised version of the code. Looks like it's not in sandbox. Is it possible to take a look?
I want to work on it further before committing it to the sandbox.
You can work in sandbox on a branch, if you don't want to break existing version. There's nothing wrong with adding unfinished version in sandbox -- nobody excepts it to be stable.
I am going to upload the files to my website shortly.
Would be good! - Volodya
participants (1)
-
Vladimir Prus