Re: [boost] Yap's formal review is starting now!

Subject: Re: [boost] Yap's formal review is starting now!
From: Barrett Adair (barrettellisadair_at_[hidden])
Date: 2018-02-14 04:54:50

On Mon, Feb 5, 2018 at 9:53 AM, Louis Dionne via Boost <
boost_at_[hidden]> wrote:
>
> Dear Boost community,
>
> The formal review of Zach Laine's Yap library starts Monday, February 5th
> and
> ends on Wednesday, February 14th.

<snip>

> We encourage your participation in this review. At a minimum, please
state:
>
> - Whether you believe the library should be accepted into Boost

I recommend Boost ACCEPT Yap as a new library.

> - Your name

Barrett Adair

> - Your knowledge of the problem domain

At best, average for this mailing list -- probably less. I am familiar and
comfortable with hand-rolled expression templates, but I have not
(successfully) used Proto.

> You are strongly encouraged to also provide additional information:
>
> - What is your evaluation of the library's:
>   * Design

I agree that Boost needs a modern replacement for Proto, and Yap appears to
do this with flying colors (as far as my untrained eye can tell).

>   * Implementation

Did not review.

My only comment on the implementation is a minor usability note - a
recurring point of frustration for me was that gcc 7.2 errors print
expr_kind template value parameters as integer values instead using enum
member names, e.g. `meow_expr<(boost::yap::expr_kind)18,
boost::hana::tuple<meow>>`. This adds a layer of mental indirection when
debugging an expression tree. A very small nice-to-have, if nothing else,
would be to assign explicit enum values in boost/yap/algorithm_fwd.hpp for
faster cross-referencing.

>   * Documentation

...can never be good enough, but I'm happy with this. It's pleasantly
concise, and it seems complete. I'm confident that I could become
proficient with Yap given what is available here.

I do think the docs would benefit from the following:
* less nesting of sections
* a link to Zach's C++Now talk (if the talk still reflects the code, that
is)
* more examples, as always
* Some sections could be merged, such as "operators" and "operator macros",
also the transform sections
* The "operator macros" section would benefit from having the expr_kind
names listed nearby

This documentation appears to cater to Proto alumni, which is fine, but an
"Intro to Expression Templates" section would be nice for newcomers. A
"Suggested reading" section would also be a cheap way to improve
accessibility. Smoothing out the cliff-shaped learning curve of this
library is a daunting task, but it might be worthwhile in the long run.

>   * Tests

Built, ran, passed, did not review. Ubuntu 16, gcc 7.2, Boost 1.66

>   * Usefulness

I have not written an EDSL complex enough to need Proto or Yap, but I can
see why this library would be useful.

> - Did you attempt to use the library? If so:
>   * Which compiler(s)?

gcc 7.2

>   * What was the experience? Any problems?

I played around with transforming variations of the following:

template <boost::yap::expr_kind Kind, typename Tuple>
struct letter_expr {
    static boost::yap::expr_kind const kind = Kind;
    Tuple elements;
    BOOST_YAP_USER_BINARY_OPERATOR_MEMBER(minus, ::letter_expr)
};

#define DEFINE_LETTER(c) auto c =
boost::yap::make_terminal<letter_expr>(std::string{#c})
DEFINE_LETTER(A);
DEFINE_LETTER(B);
DEFINE_LETTER(C);
DEFINE_LETTER(D); // ...

auto foo = H-E-L-L-O-W-O-R-L-D;

I'd hoped to get further than I did. I tried and failed to implement a
cloud-to-butt [0] transform in the time that I had. I was able to see the
library in action and implement some very simple transforms. The
documentation and examples were helping me through my issues.

> - How much effort did you put into your evaluation of the review?

1 hour reading examples and documentation, 2 hours hacking around, 1 hour
writing this review, 0 hours catching up on previous reviews of Yap.

Thanks,
Barrett

[0] https://github.com/panicsteve/cloud-to-butt