On Saturday, 19 December 2020 at 23:16:00 UTC, Rekel wrote:
Most confusing was the way the documentation (website &
in-editor) used;
1. Yes.keepTerminator
2. KeepTerminator.yes
3. Flag!"keepTerminator".yes
Your confusion arises from the fact that KeepTerminator is
combining multiple distinct D features to achieve its goal.
As Paul said, std.typecons.Flag is a templated enum of type bool.
It's declared to take a string as its template parameter, and it
has two fields: yes, and no. Minus the documentation:
template Flag(string name) {
///
enum Flag : bool
{
no = false,
yes = true
}
}
The template parameter serves to make Flag!"foo" a distinct type
from Flag!"bar".
Now, the goal of Flag is to make the purpose of a boolean
function parameter more clear. Sometimes, we can misremember what
a boolean parameter indicates. Does true mean do this extra thing
or does it mean don't do this extra thing? Flag removes the doubt.
However, having to write Flag!"keepTerminator".yes all the time
is more annoying that simply writing true, so functions that use
Flag usually have a corresponding alias defined in the module
scope to give it a less annoying syntax:
alias KeepTerminator = Flag!"keepTerminator";
Because of this, you can write KeepTerminator.yes and
KeepTerminator.no.
std.typecons also has two structs: Yes and No. Both are
implemented with a bit of template magic. D supports a feature
called "Forwarding" in structs and classes and implements it via
a special template called opDispatch:
https://dlang.org/spec/operatoroverloading.html#dispatch
The idea is that if you call a member function on a struct or
class, and the class does not have a member function of that
name, then the compiler will look for an opDispatch template
implementation in that class or struct. If it finds one, it will
call the template with the name of the missing function.
There are a number of use cases for this, if you look at the
examples in the documentation of opDispatch, you'll find that
there are two examples of implementing it as a function template
and one that looks like this:
struct D
{
template opDispatch(string s)
{
enum int opDispatch = 8;
}
}
This impelemtation is an enum template that's essentially
creating an enum with a single member, also called a "manifest
constant" (a compile-time constant):
https://dlang.org/spec/enum.html#manifest_constants
This is an eponymous template, which means it can be accessed
directly as opDispatch without using dot notation on the template
name (opDispatch.opDispatch). So given `d` of type `D`, when the
compiler sees `d.foo`, it looks for `foo` in the `D` struct. It
doesn't find it, but it does find `opDisptach`, so it
instantiated `d.opDispatch!"foo"` which, in this case, produces
the number `8` as a compile-time constant.
Both the Yes and No structs use this technique:
struct Yes
{
template opDispatch(string name)
{
enum opDispatch = Flag!name.yes;
}
}
So when you call Yes.keepTerminator, you're getting
Flag!"keepTerminator".yes as a result.
The point behind the structs is so that people who make use of
Flag in their function parameter lists don't need to actually
define an alias:
"The structs Yes and No are provided as shorthand for
Flag!"Name".yes and Flag!"Name".no and are preferred for brevity
and readability. These convenience structs mean it is usually
unnecessary and counterproductive to create an alias of a Flag as
a way of avoiding typing out the full type while specifying the
affirmative or negative options."
So when implementing your function with a Flag!"foo", you can
skip the alias and users can call the function with Yes.foo and
No.foo.
However, I believe that the aliases for KeepTerminator in
std.string (for splitLines and lineSplitter) and std.stdio (for
byLine and byLineCopy) predate the implementation of the Yes and
No structs in std.typecons, but were kept around so as not to
break any code.
So, to summarize:
1. Yes.keepTerminator
This is because of Yes is a struct with an opDispatch template
that "forwards" to Flag!"keepTerminator".yes. This is the
preferred syntax and will work with any Flag parameter.
2. KeepTerminator.yes
This is because KeepTerminator is an alias to
Flag!"keepTerminator". This syntax will only work on any given
Flag parameter if the function implementer defines the alias.
3. Flag!"keepTerminator".yes
This is because Flag is a templated enum that takes a string
parameter and has two members: yes and no. This always works,
because it's the root feature for which the above two syntaxes
were implemented as conveniences.
& Don't get me started on the autocomplete trying to get me to
use KeepTerminator.Flag.yes (VSCode & code-d)
code-d uses DScanner to implement autocompletion. It can get
confused in certain instances when compile-time features are
involved. If there isn't an issue on this yet, you should report
it:
https://github.com/dlang-community/D-Scanner/issues
