[swift-evolution] 100% bikeshed topic: DictionaryLiteral

[Dmitri Gribenko]

On Mon, Jan 8, 2018 at 4:29 PM, Ben Cohen via swift-evolution
<swift-evolution at swift.org> wrote:
> There exists in the standard library a type `DictionaryLiteral` that deserves naming re-consideration before we declare ABI Stability, because it’s confusingly misnamed, being neither a Dictionary (it doesn’t provide key-based lookup of values) nor a Literal.
>
> Instead, it’s just an immutable collection of key-value pairs you can create _from_ a literal.

I was around when we were naming this type, and I don't think it is
misnamed.  However, I just read the documentation and I don't believe
it explains the intended use of the type, hence we have this
confusion.

The intended use case for DictionaryLiteral is to build DSLs.  Swift
provides types in the standard library that are efficient and lossless
representations for all literals, but are also useful as your
workhorse data types: string literal -- String, array literal --
Array, integer literal -- [U]Int64, kinda (there is some
dissatisfaction with integer literals since there is no type to
capture a >64 bit literal, which is useful for defining a bigint
type).  But there was no type that could capture a dictionary literal
in a lossless form, maintaining the order of items, not imposing
dictionary limitations like uniqueness or hashability of keys.

Therefore, we added DictionaryLiteral.  Yes, it did land together with
Mirrors in commit 50c6e936d4b94b9736a8d060ddf052ef1ba9c74d, but the
intent was that it is a generally useful library component unrelated
to Mirrors, and therefore we did not add any Mirror-related words to
the name (we couldn't nest it in Mirror because nested generics didn't
work at the time).  In fact you can see the comment in Mirrors.swift
that has been preserved to this date:

// This component could stand alone, but is used in Mirror's public interface.

Mirrors just *use* DictionaryLiteral to build a small DSL in the
initializer of Mirror, so that callers could call that initializer
representing Mirror's children with a nice intuitive syntax using a
dictionary literal.

Therefore, based on this intended use, I think that trying to hint
that this type is a general *collection* of any kind is a disservice
for users -- DictionaryLiteral wasn't intended to be a collection, and
it does not have performance characteristics anyone would reasonably
expect from it.  We could add more words to the name to paint it more
an "advanced tool shade", for example, CapturedDictionaryLiteral,
DictionaryLiteralSyntax or something along those lines, but I feel
like the impact of that to fix the confusion would be minimal.

Instead, I think the right way to fix the confusion is to adjust the
documentation to not claim that it is first and foremost a collection,
because currently documentation is only technically correct, but does
not explain the intended use of the type at all.

Dmitri