From bbdc45656ce958e6cbb7870c5d0e8d53083800a0 Mon Sep 17 00:00:00 2001 From: Josh B <421772+HT154@users.noreply.github.com> Date: Tue, 13 Aug 2024 00:56:15 -0700 Subject: [PATCH] [docs] Document `hidden` equality/hashing behavior (#618) * [docs] Document `hidden` equality/hashing behavior * Update docs/modules/language-reference/pages/index.adoc --------- Co-authored-by: Daniel Chao --- docs/modules/language-reference/pages/index.adoc | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/modules/language-reference/pages/index.adoc b/docs/modules/language-reference/pages/index.adoc index e15d8a4d..403f27b3 100644 --- a/docs/modules/language-reference/pages/index.adoc +++ b/docs/modules/language-reference/pages/index.adoc @@ -915,6 +915,7 @@ pigeon = new Dynamic { // <1> ==== Hidden Properties A property with the modifier `hidden` is omitted from the rendered output and object conversions. +Hidden properties are also ignored when evaluating equality or hashing (e.g. for `Mapping` or `Map` keys). [source,{pkl}] ---- @@ -933,12 +934,19 @@ pigeon = new Bird { // <3> pigeonInIndex = pigeon.nameAndLifespanInIndex // <4> pigeonDynamic = pigeon.toDynamic() // <5> + +favoritePigeon = (pigeon) { + nameAndLifespanInIndex = "Bettie, \(lifespan)" +} + +samePigeon = pigeon == favoritePigeon // <6> ---- <1> Properties defined as `hidden` are accessible on any `Bird` instance, but not output by default. <2> Non-hidden properties can refer to hidden properties as usual. <3> `pigeon` is an object with _four_ properties, but is rendered with _three_ properties. <4> Accessing a `hidden` property from outside the class and object is like any other property. <5> Object conversions omit hidden properties, so the resulting `Dynamic` has three properties. +<6> Objects that differ only in `hidden` property values are considered equal Invoking Pkl on this file produces the following result. @@ -955,6 +963,12 @@ pigeonDynamic { lifespan = 8 nameSignWidth = 9 } +favoritePigeon { + name = "Pigeon" + lifespan = 8 + nameSignWidth = 9 +} +samePigeon = true ---- ==== Local properties