Skip to content

Commit d28e494

Browse files
catamorphismcatamorphism
committed
Remove 'part 2' document and move contents to the end of part 1
1 parent 791f645 commit d28e494

File tree

2 files changed

+315
-411
lines changed

2 files changed

+315
-411
lines changed

‎exploration/function-composition-part-1.md‎

Lines changed: 315 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -838,7 +838,10 @@ so that functions can be passed the values they need.
838838
It also needs to provide a mechanism for declaring
839839
when functions can compose with each other.
840840

841-
Other requirements:
841+
### Guarantee portability
842+
843+
A message that has a valid result in one implementation
844+
should not result in an error in a different implementation.
842845

843846
### Identify a set of use cases that must be supported
844847

@@ -975,26 +978,321 @@ Hence, revisiting the extensibility of the runtime model
975978
now that the data model is settled
976979
may result in a more workable solution.
977980

978-
## Proposed design and alternatives considered
981+
## Alternatives to be considered
982+
983+
The goal of this section is to present a _complete_ list of
984+
alternatives that may be considered by the working group.
985+
986+
Each alternative corresponds to a different concrete
987+
definition of "resolved value".
988+
989+
## Introducing type names
990+
991+
It's useful to be able to refer to two types:
992+
993+
* `MessageValue`: The "resolved value" type; see [PR 728](https://github.com/unicode-org/message-format-wg/pull/728).
994+
* `ValueType`: This type encompasses strings, numbers, date/time values,
995+
all other possible implementation-specific types that input variables can be
996+
assigned to,
997+
and all possible implementation-specific types that custom and built-in
998+
functions can construct.
999+
Conceptually it's the union of an "input type" and a "formatted value".
9791000

980-
These sections are omitted from this document and will be added in
981-
a future follow-up document,
982-
given the length so far and need to agree on a common vocabulary.
1001+
It's tagged with a string tag so functions can do type checks.
9831002

984-
We expect that any proposed design
985-
would fall into one of the following categories:
1003+
```
1004+
interface ValueType {
1005+
type(): string
1006+
value(): unknown
1007+
}
1008+
```
9861009

987-
1. Provide a general mechanism for custom function authors
1010+
## Alternatives to consider
1011+
1012+
In lieu of the usual "Proposed design" and "Alternatives considered" sections,
1013+
we offer some alternatives already considered in separate discussions.
1014+
1015+
Because of our constraints, implementations are **not required**
1016+
to use the `MessageValue` interface internally as described in
1017+
any of the sections.
1018+
The purpose of defining the interface is to guide implementors.
1019+
An implementation that uses different types internally
1020+
but allows the same observable behavior for composition
1021+
is compliant with the spec.
1022+
1023+
Five alternatives are presented:
1024+
1. Typed functions
1025+
2. Formatted value model
1026+
3. Preservation model
1027+
4. Allow both kinds of composition
1028+
5. Don't allow composition
1029+
1030+
Alternatives 2 and 3 were presented earlier in this document.
1031+
Alternative 4 is an idea from a prior mailing list discussion
1032+
of this problem. Alternative 1 is similar to Alternative 3
1033+
but introduces additional notation to make composition
1034+
easier to think about (which is why it's presented first).
1035+
Alternative 5 is included for completeness.
1036+
1037+
### Typed functions
1038+
1039+
The following option aims to provide a general mechanism
1040+
for custom function authors
9881041
to specify how functions compose with each other.
989-
1. Specify composition rules for built-in functions,
990-
but not in general, allowing custom functions
991-
to cooperate in an _ad hoc_ way.
992-
1. Recommend a rich representation of resolved values
993-
without specifying any constraints on how these values
994-
are used.
995-
(This is the approach in [PR 645](https://github.com/unicode-org/message-format-wg/pull/645).)
996-
1. Restrict function composition for built-in functions
997-
(in order to prevent unintuitive behavior).
1042+
1043+
This is an extension of the "preservation model"
1044+
from part 1 of this document.
1045+
1046+
Here, `ValueType` is the most general type
1047+
in a system of user-defined types.
1048+
Using the function registry,
1049+
each custom function could declare its own argument type
1050+
and result type.
1051+
1052+
This does not imply the existence of any static typechecking.
1053+
A function passed the wrong type could signal a runtime error.
1054+
This does require some mechanism for dynamically inspecting
1055+
the type of a value.
1056+
1057+
Consider Example B1 from part 1 of the document:
1058+
1059+
Example B1:
1060+
```
1061+
.local $age = {$person :getAge}
1062+
.local $y = {$age :duration skeleton=yM}
1063+
.local $z = {$y :uppercase}
1064+
```
1065+
1066+
Informally, we can write the type signatures for
1067+
the three custom functions in this example:
1068+
1069+
```
1070+
getAge : Person -> Number
1071+
duration : Number -> String
1072+
uppercase : String -> String
1073+
```
1074+
1075+
`Number` and `String` are assumed to be subtypes
1076+
of `MessageValue`. Thus,
1077+
1078+
The [function registry data model](https://github.com/unicode-org/message-format-wg/blob/main/spec/registry.md)
1079+
attempts to do some of this, but does not define
1080+
the structure of the values produced by functions.
1081+
1082+
An optional static typechecking pass (linting)
1083+
would then detect any cases where functions are composed in a way that
1084+
doesn't make sense. For example:
1085+
1086+
Semantically invalid example:
1087+
```
1088+
.local $z = {$person: uppercase}
1089+
```
1090+
1091+
A person can't be converted to uppercase; or, `:uppercase` expects
1092+
a `String`, not a `Person`. So an optional tool could flag this
1093+
as an error, assuming that enough type information
1094+
was included in the registry.
1095+
1096+
The resolved value type is similar to what was proposed in
1097+
[PR 728](https://github.com/unicode-org/message-format-wg/pull/728/).
1098+
1099+
```ts
1100+
interface MessageValue {
1101+
formatToString(): string
1102+
formatToX(): X // where X is an implementation-defined type
1103+
getValue(): ValueType
1104+
properties(): { [key: string]: MessageValue }
1105+
selectKeys(keys: string[]): string[]
1106+
}
1107+
```
1108+
1109+
The `resolvedOptions()` method is renamed to `properties`.
1110+
This is to suggest that individual function implementations
1111+
may not pass all of the options through into the resulting
1112+
`MessageValue`.
1113+
1114+
Instead of using `unknown` as the result type of `getValue()`,
1115+
we use `ValueType`, mentioned previously.
1116+
Instead of using `unknown` as the value type for the
1117+
`properties()` object, we use `MessageValue`,
1118+
since options can also be full `MessageValue`s with their own options.
1119+
1120+
Because `ValueType` has a type tag,
1121+
custom function implementations can easily
1122+
signal dynamic errors if passed an operand of the wrong type.
1123+
1124+
The advantage of this approach is documentation:
1125+
with type names that can be used in type signatures
1126+
specified in the registry,
1127+
it's easy for users to reason about functions and
1128+
understand which combinations of functions
1129+
compose with each other.
1130+
1131+
### Formatted value model (Composition operates on output)
1132+
1133+
This is an elaboration on the "formatted model" from part 1.
1134+
1135+
A less general solution is to have a single "resolved value"
1136+
type, and specify that if function `g` consumes the resolved value
1137+
produced by function `f`,
1138+
then `g` operates on the output of `f`.
1139+
1140+
```
1141+
.local $x = {$num :number maxFrac=2}
1142+
.local $y = {$x :number maxFrac=5 padStart=3}
1143+
```
1144+
1145+
In this example, `$x` would be bound to the formatted result
1146+
of calling `:number` on `$num`. So the `maxFrac` option would
1147+
be "lost" and when determining the value of `$y`, the second
1148+
set of options would be used.
1149+
1150+
For built-ins, it suffices to define `ValueType`as something like:
1151+
1152+
```
1153+
FormattedNumber | FormattedDateTime | String
1154+
```
1155+
1156+
because no information about the input needs to be
1157+
incorporated into the resolved value.
1158+
1159+
However, to make it possible for custom functions to return
1160+
a wider set of types, a wider `ValueType` definition would be needed.
1161+
1162+
The `MessageValue` definition would look as in #728, but without
1163+
the `resolvedOptions()` method:
1164+
1165+
```ts
1166+
interface MessageValue {
1167+
formatToString(): string
1168+
formatToX(): X // where X is an implementation-defined type
1169+
getValue(): ValueType
1170+
selectKeys(keys: string[]): string[]
1171+
}
1172+
```
1173+
1174+
`MessageValue` is effectively a `ValueType` with methods.
1175+
1176+
Using this definition would make some of the use cases from part 1
1177+
impractical.
1178+
1179+
### Preservation model (composition can operate on input and options)
1180+
1181+
This is an extension of
1182+
the "preservation model" from part 1,
1183+
if resolved options are included in the output.
1184+
This model can also be thought of as functions "pipelining"
1185+
the input through multiple calls.
1186+
1187+
A JSON representation of an example resolved value might be:
1188+
```
1189+
{
1190+
input: { type: "number", value: 1 },
1191+
output: { type: "FormattedNumber", value: FN }
1192+
properties: { "maximumFractionDigits": 2 }
1193+
}
1194+
```
1195+
1196+
(The number "2" is shown for brevity, but it would
1197+
actually be a `MessageValue` itself.)
1198+
1199+
where `FN` is an instance of an implementation-specific
1200+
`FormattedNumber` type, representing the number 1.
1201+
1202+
The resolved value interface would include both "input"
1203+
and "output" methods:
1204+
1205+
```ts
1206+
interface MessageValue {
1207+
formatToString(): string
1208+
formatToX(): X // where X is an implementation-defined type
1209+
getInput(): ValueType
1210+
getOutput(): ValueType
1211+
properties(): { [key: string]: MessageValue }
1212+
selectKeys(keys: string[]): string[]
1213+
}
1214+
```
1215+
1216+
Without a mechanism for type signatures,
1217+
it may be hard for users to tell which combinations
1218+
of functions compose without errors,
1219+
and for implementors to document that information
1220+
for users.
1221+
1222+
### Allow both kinds of composition (with different syntax)
1223+
1224+
By introducing new syntax, the same function could have
1225+
either "preservation" or "formatted value" behavior.
1226+
1227+
Consider (this suggestion is from Elango Cheran):
1228+
1229+
```
1230+
.local $x = {$num :number maxFrac=2}
1231+
.pipeline $y = {$x :number maxFrac=5 padStart=3}
1232+
{{$x} {$y}}
1233+
```
1234+
1235+
If `$num` is `0.33333`,
1236+
then the result of formatting would be
1237+
1238+
```
1239+
0.33 000.33333
1240+
```
1241+
1242+
An extra argument to function implementations,
1243+
`pipeline`, would be added.
1244+
1245+
`.pipeline` would be a new keyword that acts like `.local`,
1246+
except that if its expression has a function annotation,
1247+
the formatter would pass in `true` for the `pipeline`
1248+
argument to the function implementation.
1249+
1250+
The `resolvedOptions()` method should be ignored if `pipeline`
1251+
is `false`.
1252+
1253+
```ts
1254+
interface MessageValue {
1255+
formatToString(): string
1256+
formatToX(): X // where X is an implementation-defined type
1257+
getInput(): MessageValue
1258+
getOutput(): unknown
1259+
properties(): { [key: string]: MessageValue }
1260+
selectKeys(keys: string[]): string[]
1261+
}
1262+
```
1263+
1264+
### Don't allow composition for built-in functions
1265+
1266+
Another option is to define the built-in functions this way,
1267+
notionally:
1268+
1269+
```
1270+
number : Number -> FormattedNumber
1271+
date : Date -> FormattedDate
1272+
```
1273+
1274+
Then it would be a runtime error to pass a `FormattedNumber` into `number`
1275+
or to pass a `FormattedDate` into `date`.
1276+
1277+
The resolved value type would look like:
1278+
1279+
```ts
1280+
interface MessageValue {
1281+
formatToString(): string
1282+
formatToX(): X // where X is an implementation-defined type
1283+
getValue(): ValueType
1284+
selectKeys(keys: string[]): string[]
1285+
}
1286+
```
1287+
1288+
As with the formatted value model, this restricts the
1289+
behavior of custom functions.
1290+
1291+
### Non-alternative: Allow composition in some implementations
1292+
1293+
Allow composition only if the implementation requires functions to return a resolved value as defined in [PR 728](https://github.com/unicode-org/message-format-wg/pull/728).
1294+
1295+
This violates the portability requirement.
9981296

9991297
## Acknowledgments
10001298

0 commit comments

Comments
 (0)