"Andrei Alexandrescu" <SeeWebsiteForEmail@erdani.org> wrote in message news:inv4rv$1dfl$1@digitalmars.com...
>A fair amount of code in std uses this idiom:
>
> enum SomeOption { no, yes }
>
> void someFunction(...parms..., SomeOption, ...more_parms...) { ... }
>
> SomeOption is really a Boolean but replaces the unhelpful call syntax someFunction(...args..., false, ...more_args...) with the self-documenting ...args..., SomeOption,no, ...more_args...).
>
> The liabilities of using Booleans for describing flags have been documented in several places, including McConnell's Code Complete. I think the idiom above is a good replacement.
>

Named args are much better for this. No boilerplate needed. Of course, without named args, yea, this idiom needs to be used.

> One issue I have with it is that it requires separate definition and documentation. Usually the documentation awkwardly states "This type is really an option for someFunction, which you haven't seen yet. Skip this for now, then get back, and you'll understand." Moving the enum to after the function is possible but equally confusing.
>

/// Documentation here
enum SomeOption { no, yes }
///ditto
 void someFunction(...parms..., SomeOption, ...more_parms...) { ... }

That groups the two together, right? So solved.

> So I was thinking of planting a simple template in std.typecons:
>
> template YesOrNo(string name)
> {
>     mixin("enum "~name~" : bool { no, yes }");
> }
>
> That way, the definition of the function needs no separately-defined is self-documenting:
>
> void someFunction(...parms..., YesOrNo!"SomeOption", ...) { ... }
>
> The question is to what extent this would mark progress and fostering structured use of this idiom, versus just confusing beginners and adding deadweight to Phobos.
>

Not sure what I think, really. Although, I do think the fact there seems to be a need for someting that complex just for a mere two-option setting is more indication that named args are just a better approach. But since we're stuck without that, I really don't know how I feel about this template. Umm, if you need to add a third setting, then you're right back to using a straight enum and making sure it's documentated sensibly. You could generalize YesOrNo further, but I don't think's possible without making it really ugly to use. So maybe it's better to just make sure there's a good way to handle the documentation. If that turns out to require some new DDoc feature, then so be it.

"KennyTM~" <kennytm@gmail.com> wrote in message news:invke1$2gv6$1@digitalmars.com...
> On Apr 12, 11 03:05, Andrej Mitrovic wrote:
>> Because without some form of syntax highlighting the function headers
>> are almost unreadable from the website:
>> http://i.imgur.com/B5M6u.png
>>
>> It's a wall of text.
>
> Well that's a separate issue. Firstly the struct Until shouldn't appear (e.g. use 'auto' return). Then the signature appeared would become
>
>     until(alias pred="a==b", Range, Sentinel)(Range range, Sentinel
> sentinel, OpenRight openRight = OpenRight.yes);
>     until(alias pred, Range)(Range range, OpenRight openRight =
> OpenRight.yes);
>
> This would break half of the wall.

...And suddenly people won't know what the hell to expect it to return.

On 04/11/2011 09:35 PM, Nick Sabalausky wrote:
> "Andrei Alexandrescu"<SeeWebsiteForEmail@erdani.org>  wrote in message
> news:inv4rv$1dfl$1@digitalmars.com...
>> A fair amount of code in std uses this idiom:
>>
>> enum SomeOption { no, yes }
>>
>> void someFunction(...parms..., SomeOption, ...more_parms...) { ... }
>>
>> SomeOption is really a Boolean but replaces the unhelpful call syntax
>> someFunction(...args..., false, ...more_args...) with the self-documenting
>> ...args..., SomeOption,no, ...more_args...).
>>
>> The liabilities of using Booleans for describing flags have been
>> documented in several places, including McConnell's Code Complete. I think
>> the idiom above is a good replacement.
>>
>
> Named args are much better for this. No boilerplate needed. Of course,
> without named args, yea, this idiom needs to be used.
>
>> One issue I have with it is that it requires separate definition and
>> documentation. Usually the documentation awkwardly states "This type is
>> really an option for someFunction, which you haven't seen yet. Skip this
>> for now, then get back, and you'll understand." Moving the enum to after
>> the function is possible but equally confusing.
>>
>
> /// Documentation here
> enum SomeOption { no, yes }
> ///ditto
>   void someFunction(...parms..., SomeOption, ...more_parms...) { ... }
>
> That groups the two together, right? So solved.

Yop! The "ditto" feature is great for such cases.

>> So I was thinking of planting a simple template in std.typecons:
>>
>> template YesOrNo(string name)
>> {
>>      mixin("enum "~name~" : bool { no, yes }");
>> }
>>
>> That way, the definition of the function needs no separately-defined is
>> self-documenting:
>>
>> void someFunction(...parms..., YesOrNo!"SomeOption", ...) { ... }
>>
>> The question is to what extent this would mark progress and fostering
>> structured use of this idiom, versus just confusing beginners and adding
>> deadweight to Phobos.
>>
>
> Not sure what I think, really. Although, I do think the fact there seems to
> be a need for someting that complex just for a mere two-option setting is
> more indication that named args are just a better approach. But since we're
> stuck without that, I really don't know how I feel about this template. Umm,
> if you need to add a third setting, then you're right back to using a
> straight enum and making sure it's documentated sensibly. You could
> generalize YesOrNo further, but I don't think's possible without making it
> really ugly to use. So maybe it's better to just make sure there's a good
> way to handle the documentation. If that turns out to require some new DDoc
> feature, then so be it.

I now think the same way.

Denis
-- 
_________________
vita es estrany
spir.wikidot.com

On 4/11/11 1:29 PM, Andrej Mitrovic wrote:
> On 4/11/11, KennyTM~<kennytm@gmail.com>  wrote:
>> The idea, IIUC, is to avoid documenting that extra enum type. So, for
>> example,
>>
>>       TRange topNCopy(alias less = "a<  b", SRange, TRange)
>>                      (SRange source, TRange target,
>>                       YesOrNo!"SortOutput" sorted = false);
>>
>> and then we can call it as
>>
>>       topNCopy([1,3,5,2,4], result, SortOutput.yes);
>
> But how do you make `SortOutput` known at the calling site?

I was hasty. I can't see a way for a mixin to introduce at the same time SortOutput and itself in scope.

Andrei

On 4/11/11 2:35 PM, Nick Sabalausky wrote:
> /// Documentation here
> enum SomeOption { no, yes }
> ///ditto
>   void someFunction(...parms..., SomeOption, ...more_parms...) { ... }
>
> That groups the two together, right? So solved.

Never thought of it. Facepalm etc. Thanks!

Andrei

On 4/11/11 2:41 PM, Nick Sabalausky wrote:
> "KennyTM~"<kennytm@gmail.com>  wrote in message
> news:invke1$2gv6$1@digitalmars.com...
>> On Apr 12, 11 03:05, Andrej Mitrovic wrote:
>>> Because without some form of syntax highlighting the function headers
>>> are almost unreadable from the website:
>>> http://i.imgur.com/B5M6u.png
>>>
>>> It's a wall of text.
>>
>> Well that's a separate issue. Firstly the struct Until shouldn't appear
>> (e.g. use 'auto' return). Then the signature appeared would become
>>
>>      until(alias pred="a==b", Range, Sentinel)(Range range, Sentinel
>> sentinel, OpenRight openRight = OpenRight.yes);
>>      until(alias pred, Range)(Range range, OpenRight openRight =
>> OpenRight.yes);
>>
>> This would break half of the wall.
>
> ...And suddenly people won't know what the hell to expect it to return.

I think it's not all that bad to state until returns a range with such and such characteristics. After all this is the norm in dynamically typed languages.

Andrei

On Apr 12, 11 03:41, Nick Sabalausky wrote:
> "KennyTM~"<kennytm@gmail.com>  wrote in message
> news:invke1$2gv6$1@digitalmars.com...
>> On Apr 12, 11 03:05, Andrej Mitrovic wrote:
>>> Because without some form of syntax highlighting the function headers
>>> are almost unreadable from the website:
>>> http://i.imgur.com/B5M6u.png
>>>
>>> It's a wall of text.
>>
>> Well that's a separate issue. Firstly the struct Until shouldn't appear
>> (e.g. use 'auto' return). Then the signature appeared would become
>>
>>      until(alias pred="a==b", Range, Sentinel)(Range range, Sentinel
>> sentinel, OpenRight openRight = OpenRight.yes);
>>      until(alias pred, Range)(Range range, OpenRight openRight =
>> OpenRight.yes);
>>
>> This would break half of the wall.
>
> ...And suddenly people won't know what the hell to expect it to return.
>
>

That's why you assign the result using 'auto'.

(This was discussed before, but I can't find the post.)

On 11/04/2011 18:13, Andrej Mitrovic wrote:
> On 4/11/11, Andrei Alexandrescu<SeeWebsiteForEmail@erdani.org>  wrote:
>> template YesOrNo(string name)
>> {
>>       mixin("enum "~name~" : bool { no, yes }");
>> }
>>
>> void someFunction(YesOrNo!"SomeOption") { }
>
> How exactly would this work? I can't compile it.

I make out the idea to be that, at the module or class level, you write

    mixin YesOrNo!("SomeOption");

and then declare functions as, e.g.

    void doSomething(SomeOption someOption);

and so calls to this function become self-documenting with

    doSomething(SomeOption.yes);

The disadvantage is that a user of the library needs to look up SomeOption in order to find out what the possible values are, whereas everybody knows what the possible values of a bool are.

It's really a workaround for two things:
- named arguments
- strong typedefs

Stewart.

Named arguments. Seriously. Named arguments.

*stares into Andrei's soul*