boost.org Source-Code, Concepts & Idioms.
Good morning Guys. Do you think it feasible to have a section in boost.org that shows (& permits download) the libraries' source-code at its bare-minimum, without all the configuration to clutter the code? The only problem with easily & clearly understanding the boost libraries is the abundance of conditional compilation directives, & a multitude of macros for some libraries. This makes it hard to read & understand. Seeing the bare source-code without the directives & macros (I know it is very necessary for portability, & avoiding boiler-plate code) would make the concepts easier to understand. In addition, I do agree with Scott Meyers in the section below, from the link: http://www.artima.com/cppsource/top_cpp_aha_moments.html#r10 "...Second, I think it's regrettable that this kind of innovation doesn't often get written up and disseminated for the wider C++ development community. Boost does an enviable job of fostering the creation of useful software, including user-level documentation that is at least serviceable. I wish it did a better job of getting the word out on the design and implementation techniques employed by the library authors, because there's some really interesting-and largely unknown-stuff going on under the hood in Boost libraries..." What is your opinion on both these issues? I do believe the entire C++ community would benefit from both. Awaiting your feedback. Thank you. Have a nice day. ______________________________________________________________________ Kizza George Mbidde | Interconnect Billing Systems Analyst | MTN Uganda | MTN Towers 22 Hannington Road | P.O. Box 24624 Kampala Uganda | East-Africa | email: mbiddeg@mtn.co.ug [cid:image001.png@01C92D0F.BE2B7C10]
AMDG mbiddeg@mtn.co.ug wrote:
Good morning Guys. Do you think it feasible to have a section in boost.org that shows (& permits download) the libraries' source-code at its bare-minimum, without all the configuration to clutter the code?
The only problem with easily & clearly understanding the boost libraries is the abundance of conditional compilation directives, & a multitude of macros for some libraries.
This makes it hard to read & understand. Seeing the bare source-code without the directives & macros (I know it is very necessary for portability, & avoiding boiler-plate code) would make the concepts easier to understand.
I don't think it is really feasible to maintain two versions of the code. In Christ, Steven Watanabe
AMDG Jonas Persson wrote:
Steven Watanabe skrev:
I don't think it is really feasible to maintain two versions of the code.
Do we really need to. Would it be possible to modify Wave to do a selective preprocessing of the source?
This could be quite a task if we want the output to be more readable that the input. For instance some macros should be expanded but others shouldn't be. (Do users really want to see the implementation of BOOST_TYPEOF?) In Christ, Steven Watanabe
Steven Watanabe skrev:
AMDG
Jonas Persson wrote:
Steven Watanabe skrev:
I don't think it is really feasible to maintain two versions of the code.
Do we really need to. Would it be possible to modify Wave to do a selective preprocessing of the source?
This could be quite a task if we want the output to be more readable that the input. For instance some macros should be expanded but others shouldn't be. (Do users really want to see the implementation of BOOST_TYPEOF?)
Suppose that it would be possible to declare which macros are to be considered defined, which are undefined and which are still undecided. Wave would use the information on defined or undefined macros and resolve preprocessor directives using them, but leave undecided macros untouched. There could also be a option to prevent macros matching %pattern% to be expanded. Would that not be enough to allow for fine tuned generation of readable workaround-free code (or preprocessing source for specific platforms)? / Jonas
I don't think it is really feasible to maintain two versions of the code.
Do we really need to. Would it be possible to modify Wave to do a selective preprocessing of the source?
This could be quite a task if we want the output to be more readable that the input. For instance some macros should be expanded but others shouldn't be. (Do users really want to see the implementation of BOOST_TYPEOF?)
Suppose that it would be possible to declare which macros are to be considered defined, which are undefined and which are still undecided. Wave would use the information on defined or undefined macros and resolve preprocessor directives using them, but leave undecided macros untouched. There could also be a option to prevent macros matching %pattern% to be expanded.
Would that not be enough to allow for fine tuned generation of readable workaround-free code (or preprocessing source for specific platforms)?
If you have a list of macros to leave untouched it is easily implemented. All you (somebody) will have to do is to modify the expanding_function_like_macro() and expanding_object_like_macro() preprocessing hooks to return true for all macros Wave shouldn't touch (see tools/wave/trace_macro_expansion.hpp). You probably don't want system headers to be expanded, though. As long as you don't care about the defined macros in those headers you can skip processing of certain include directives the same way as above: change the found_include_directive() preprocessing hook to return true for the #include's to skip. The readability of the output is another issue. Wave allows to control the amount of whitespace: eat all whitespace, leave comments only, leave all whitespace. The second option is probably the best, but I'm almost positive this will eat leading indentation as well (which would have to be fixed). Overall, worth a try, I think. Somebody up to this? HTH Regards Hartmut
AMDG Hartmut Kaiser wrote:
The readability of the output is another issue. Wave allows to control the amount of whitespace: eat all whitespace, leave comments only, leave all whitespace. The second option is probably the best, but I'm almost positive this will eat leading indentation as well (which would have to be fixed).
Can this be made to format macro expansions nicely? In Christ, Steven Watanabe
The readability of the output is another issue. Wave allows to control the amount of whitespace: eat all whitespace, leave comments only, leave all whitespace. The second option is probably the best, but I'm almost
Hartmut Kaiser wrote: positive
this will eat leading indentation as well (which would have to be fixed).
Can this be made to format macro expansions nicely?
What do you mean by that? Regards Hartmut
AMDG Hartmut Kaiser wrote:
Can this be made to format macro expansions nicely?
What do you mean by that?
Since the point is to make the code more readable, if we do any macro expansion for instance: #define SOME_MACRO(...) \ template<class T> \ class C { \ /*stuff*/ \ }; SOME_MACRO(x, y, z) We don't want this all to end up on one line. In Christ, Steven Watanabe
----- Original Message ----- From: "Steven Watanabe" <watanabesj@gmail.com> To: <boost@lists.boost.org> Sent: Tuesday, October 14, 2008 9:12 PM Subject: Re: [boost] boost.org Source-Code, Concepts & Idioms.
AMDG
Hartmut Kaiser wrote:
Can this be made to format macro expansions nicely?
What do you mean by that?
Since the point is to make the code more readable, if we do any macro expansion for instance:
#define SOME_MACRO(...) \ template<class T> \ class C { \ /*stuff*/ \ };
SOME_MACRO(x, y, z)
We don't want this all to end up on one line.
In Christ, Steven Watanabe
Hi, I'm not sure to understand what exactly you want, which are the two generated sources you are locking for. Any way here they are my 2 cts. If the problem is to have a single source able to generate the current files, and on the other hand a more readable pseudo C++, I think that we need a different preprocesor. I've made something like that some years ago (lost now) The preprocessor * allow to define one line macros @@define SOME_MACRO(...) XXXX * allow to define multi line macros preserving white spaces and line breaks @@define_begin SOME_MACRO(...) template<class T> class C { /*stuff*/ }; @@define_end * allow conditional preprocesing @@if @@else @@endif * file inclusion @@include "file" The preprocessing was done using some sed/awk and the CPP preprocessor, on three phases. 1st. Prepare the input to the CPP . Replace all the CPP preprocessing # directives by $$ . Add a end of line pattern $$ . Replace n white spaces by " $$n$$ " . Add the \ at the end of the multi line macros and remove the @@define_end . Replace the new preprocesing directives @@ by # . Replace C comments /* */ by $$* *$$ . Replace C++ comments // by $$$$ 2nd. apply the CPP preprocessor 3rd. restore the initial CPP directives . Replace all the CPP preprocessing $$ directives by # . Replace the pattern $$ by a end of line . Replace the pattern " $$n$$ " by n white spaces . Replace the patterns by $$* *$$ by /* */ . Replace the pattern $$$$ by // The problem is if library authors will use this preprocessing to get the two required outputs. I don't know if this can help. Vicente
On Tue, Oct 14, 2008 at 4:49 PM, vicente.botet <vicente.botet@wanadoo.fr>wrote:
----- Original Message ----- From: "Steven Watanabe" <watanabesj@gmail.com
Hartmut Kaiser wrote:
Can this be made to format macro expansions nicely?
What do you mean by that?
Since the point is to make the code more readable, if we do any macro expansion for instance:
#define SOME_MACRO(...) \ template<class T> \ class C { \ /*stuff*/ \ };
SOME_MACRO(x, y, z)
We don't want this all to end up on one line.
...
I'm not sure to understand what exactly you want, which are the two generated sources you are locking for.
I use the -E compiler option (gcc & msvc) fairly frequently to look at what the pre-processor is generating. This code should be readable (or at least as readable as possible). A lost of times, macros expand to a huge wad of code, containing many expressions all on the same line. This isn't easily readable, so we should make sure that the generated code contains new lines where appropriate. I'm pretty sure that this is what Steven is getting at. Jon
----- Original Message ----- From: "Jonathan Franklin" <franklin.jonathan@gmail.com> To: <boost@lists.boost.org> Sent: Wednesday, October 15, 2008 4:14 AM Subject: Re: [boost] boost.org Source-Code, Concepts & Idioms.
On Tue, Oct 14, 2008 at 4:49 PM, vicente.botet <vicente.botet@wanadoo.fr>wrote:
----- Original Message ----- From: "Steven Watanabe" <watanabesj@gmail.com
Hartmut Kaiser wrote:
Can this be made to format macro expansions nicely?
What do you mean by that?
Since the point is to make the code more readable, if we do any macro expansion for instance:
#define SOME_MACRO(...) \ template<class T> \ class C { \ /*stuff*/ \ };
SOME_MACRO(x, y, z)
We don't want this all to end up on one line.
...
I'm not sure to understand what exactly you want, which are the two generated sources you are locking for.
I use the -E compiler option (gcc & msvc) fairly frequently to look at what the pre-processor is generating. This code should be readable (or at least as readable as possible). A lost of times, macros expand to a huge wad of code, containing many expressions all on the same line. This isn't easily readable, so we should make sure that the generated code contains new lines where appropriate.
I'm pretty sure that this is what Steven is getting at.
Jon
Oh, I get it. Thanks, Vicente
on Wed Oct 15 2008, "vicente.botet" <vicente.botet-AT-wanadoo.fr> wrote: <snip long quote>
Oh, I get it.
Thanks, Vicente
Please limit the size of your quoted text per the posting guidelines. Thanks, -- Dave Abrahams BoostPro Computing http://www.boostpro.com
Can this be made to format macro expansions nicely?
What do you mean by that?
Since the point is to make the code more readable, if we do any macro expansion for instance:
#define SOME_MACRO(...) \ template<class T> \ class C { \ /*stuff*/ \ };
SOME_MACRO(x, y, z)
We don't want this all to end up on one line.
Ok, I see what you mean. Good point. This is really tricky as the backslash/newline's are removed at the lowest level possible - in the lexer. I'm not sure if we're able to re-create this particular formatting. Let me think about this for a while. Perhaps I can coerce the lexer to (optionally) retain this information inside macro expansion sequences. Regards Hartmut
Steven Watanabe wrote:
Since the point is to make the code more readable, if we do any macro expansion for instance:
#define SOME_MACRO(...) \ template<class T> \ class C { \ /*stuff*/ \ };
SOME_MACRO(x, y, z)
We don't want this all to end up on one line.
Perhaps run everything through a code beautifier after the pseudo-preprocessing step? Still, I'd have thought that macros like the above would usually be the sort that would better not be expanded. John Bytheway
Hartmut Kaiser skrev:
If you have a list of macros to leave untouched it is easily implemented. All you (somebody) will have to do is to modify the expanding_function_like_macro() and expanding_object_like_macro() preprocessing hooks to return true for all macros Wave shouldn't touch (see tools/wave/trace_macro_expansion.hpp).
Is there also a hook to decide if an #if #else expression should be evaluated or left as it is?
You probably don't want system headers to be expanded, though. As long as you don't care about the defined macros in those headers you can skip processing of certain include directives the same way as above: change the found_include_directive() preprocessing hook to return true for the #include's to skip.
Are you saying that we need to inline the headers or wave wont see the macro definitions? Would it be possible to split the parsing of includes from the inline expansion? I expect that we do need the defined macros from included files if we want everything correctly evaluated. But if it is to be readable no headers should be expanded. We want the source files to look like hand written code. / Jonas
If you have a list of macros to leave untouched it is easily implemented. All you (somebody) will have to do is to modify the expanding_function_like_macro() and expanding_object_like_macro() preprocessing hooks to return true for all macros Wave shouldn't touch (see tools/wave/trace_macro_expansion.hpp).
Is there also a hook to decide if an #if #else expression should be evaluated or left as it is?
Sure. Just have a look at the docs for the full set of preprocessing hooks or at the file boost/wave/preprocessing_hooks.hpp But on a second thought, you probably don't want to evaluate the #if/#endif etc. yourself, this might turn out to be serious business and is best left to Wave.
You probably don't want system headers to be expanded, though. As long as you don't care about the defined macros in those headers you can skip processing of certain include directives the same way as above: change the found_include_directive() preprocessing hook to return true for the #include's to skip.
Are you saying that we need to inline the headers or wave wont see the macro definitions?
Currently yes. At least that's the default behavior of the library.
Would it be possible to split the parsing of includes from the inline expansion?
I think it is possible. Again by adding some code to the found_include_directive() pp hook. All you have to do there is to use the context object passed to this function to preprocess the include file, eating up all generated output and returning true afterwards to make the library skip this include. Since you have been using the same context to preprocess the include file, all macros have been expanded and the wave::context object is the same as if the library itself was preprocessing the file.
I expect that we do need the defined macros from included files if we want everything correctly evaluated. But if it is to be readable no headers should be expanded. We want the source files to look like hand written code.
Agreed. Regards Hartmut
on Mon Oct 13 2008, <mbiddeg-AT-mtn.co.ug> wrote:
What is your opinion on both these issues?
I do believe the entire C++ community would benefit from both.
I agree that they would be nice, but who has the time? I'm sure we'd welcome a competent group of volunteers willing take these projects on. -- Dave Abrahams BoostPro Computing http://www.boostpro.com
Your mail makes it sound like you want to look at gcc -E output, but of course you'd find that much worse. An obvious issue is that while sometimes macros obfuscate code, sometimes they simplify (e.g. as part of the API of underlying code). What I imagine being of some potential (though perhaps small) value is the notion of a fully standards-compliant compiler (or perhaps an approximation such as Comeau), for which conditional includes are processed, macros only required to patch in hacks for non-Standard-compliant compilers have their Standard substitution performed, but other macros are left alone. I imagine differentiating macros on this basis would have to be done manually, after which the processing could be done easily enough with a bit of sed/awk/perl/Ruby/etc hackery. I don't see enough value in it to override other demands on my time, but best of luck. - Tony -----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of mbiddeg@mtn.co.ug Sent: Monday, 13 October 2008 3:21 PM To: boost@lists.boost.org Subject: [boost] boost.org Source-Code, Concepts & Idioms. Good morning Guys. Do you think it feasible to have a section in boost.org that shows (& permits download) the libraries' source-code at its bare-minimum, without all the configuration to clutter the code? The only problem with easily & clearly understanding the boost libraries is the abundance of conditional compilation directives, & a multitude of macros for some libraries. This makes it hard to read & understand. Seeing the bare source-code without the directives & macros (I know it is very necessary for portability, & avoiding boiler-plate code) would make the concepts easier to understand. In addition, I do agree with Scott Meyers in the section below, from the link: http://www.artima.com/cppsource/top_cpp_aha_moments.html#r10 "...Second, I think it's regrettable that this kind of innovation doesn't often get written up and disseminated for the wider C++ development community. Boost does an enviable job of fostering the creation of useful software, including user-level documentation that is at least serviceable. I wish it did a better job of getting the word out on the design and implementation techniques employed by the library authors, because there's some really interesting-and largely unknown-stuff going on under the hood in Boost libraries..." What is your opinion on both these issues? I do believe the entire C++ community would benefit from both. Awaiting your feedback. Thank you. Have a nice day. ______________________________________________________________________ Kizza George Mbidde | Interconnect Billing Systems Analyst | MTN Uganda | MTN Towers 22 Hannington Road | P.O. Box 24624 Kampala Uganda | East-Africa | email: mbiddeg@mtn.co.ug [cid:image001.png@01C92D0F.BE2B7C10]
participants (9)
-
David Abrahams -
Delroy, Tony (IED) -
Hartmut Kaiser -
John Bytheway -
Jonas Persson -
Jonathan Franklin -
mbiddeg＠mtn.co.ug -
Steven Watanabe -
vicente.botet