@gram-lang/i18n 1.4.2 → 1.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +8 -3
- package/dist/index.d.ts +421 -4
- package/dist/index.js +940 -9
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @gram-lang/i18n
|
|
2
2
|
|
|
3
|
-
[](https://www.npmjs.com/package/@gram-lang/i18n)
|
|
4
4
|
[](https://www.gnu.org/licenses/gpl-3.0)
|
|
5
5
|
|
|
6
6
|
*Part of the [Gram monorepo](https://git.gram-lang.org/gram-lang/gram).*
|
|
@@ -11,7 +11,7 @@ The translation and normalization module of the Gram recipe language: it normali
|
|
|
11
11
|
|
|
12
12
|
## 📚 General Documentation
|
|
13
13
|
|
|
14
|
-
For full syntax specifications, grammar details, cheatsheets, and best practices, please refer to the **[Gram Documentation](https://
|
|
14
|
+
For full syntax specifications, grammar details, cheatsheets, and best practices, please refer to the **[Gram Documentation](https://gram-lang.org/docs/)**.
|
|
15
15
|
|
|
16
16
|
---
|
|
17
17
|
|
|
@@ -47,11 +47,13 @@ console.log(resolveTimeUnit('minutes')); // 'm'
|
|
|
47
47
|
`getDictionary(lang)` returns the dictionary of a language (`en` or `fr`): the labels of the renderer's views (`renderer.*`, including the names of the outputs and of the formats), the units of durations (`renderer.durationUnits`, `1h 30min` or `1j 1h`) and the strings of the playground. `fillTemplate(template, values)` fills the `{name}` placeholders of a dictionary string (`"Serve at {time}"` becomes `"Serve at 20:00"`) and leaves a name with no value as written, so a missing value shows up instead of vanishing.
|
|
48
48
|
|
|
49
49
|
```javascript
|
|
50
|
-
import { getDictionary, fillTemplate } from '@gram-lang/i18n';
|
|
50
|
+
import { getDictionary, fillTemplate, formatNumber, parseDuration } from '@gram-lang/i18n';
|
|
51
51
|
|
|
52
52
|
const t = getDictionary('fr');
|
|
53
53
|
console.log(t.renderer.durationUnits); // { day: 'j', hour: 'h', minute: 'min', second: 's' }
|
|
54
54
|
console.log(fillTemplate('Serve at {time}', { time: '20:00' })); // 'Serve at 20:00'
|
|
55
|
+
console.log(formatNumber(1.5, 'fr')); // '1,5'
|
|
56
|
+
console.log(parseDuration('1h 30min')); // { ok: true, kind: 'single', ... }
|
|
55
57
|
```
|
|
56
58
|
|
|
57
59
|
A key is added in both languages together: a surface never carries a word of its own.
|
|
@@ -70,6 +72,9 @@ If a language-specific code (e.g., `'fr'`) is provided, the function checks the
|
|
|
70
72
|
* `src/dictionary.ts`: Dictionary compiler helper that transforms structured translations into flat `O(1)` maps.
|
|
71
73
|
* `src/units.ts`: Mass and volume unit dictionary (French & English) and normalizer.
|
|
72
74
|
* `src/time.ts`: Time unit dictionary (French & English) and normalizer.
|
|
75
|
+
* `src/duration.ts`: Compound, clock, prime, and range duration parser (`parseDuration()`).
|
|
76
|
+
* `src/numbers.ts`: Locale-aware number formatting (`formatNumber()`, `localizeDecimals()`, `toKitchenFraction()`).
|
|
77
|
+
* `src/quantity.ts`: Quantity term arithmetic and formatting (`termsTotal()`, `mergeTerms()`, `scaleTerms()`, `formatTerms()`).
|
|
73
78
|
* `src/locales/`: The `en` and `fr` dictionaries (renderer views, nutrients, playground) and `getDictionary()`.
|
|
74
79
|
* `src/template.ts`: `fillTemplate()`.
|
|
75
80
|
* `src/categories.ts`: Shopping list category keys and their labels per language.
|
package/dist/index.d.ts
CHANGED
|
@@ -36,6 +36,45 @@ declare const UNIT_CONVERSIONS: {
|
|
|
36
36
|
mass: UnitMap;
|
|
37
37
|
volume: UnitMap;
|
|
38
38
|
};
|
|
39
|
+
/**
|
|
40
|
+
* A run of units of one measuring system whose sizes are exact whole-number
|
|
41
|
+
* multiples of each other: what a cook can add up without rounding
|
|
42
|
+
* (`1 cup + 1 tbsp` = `17 tbsp`). Each step is the unit's size counted in the
|
|
43
|
+
* ladder's smallest unit (1 cup = 48 tsp).
|
|
44
|
+
*
|
|
45
|
+
* `UNIT_CONVERSIONS` says how much a unit weighs or holds in grams or
|
|
46
|
+
* milliliters, with its factors rounded (`cup: 236.588`); a ladder only says
|
|
47
|
+
* how units of one system relate, exactly. The two agree to 0.01%
|
|
48
|
+
* (`units-ladders.test.ts`).
|
|
49
|
+
*/
|
|
50
|
+
interface UnitLadder {
|
|
51
|
+
id: "usVolume" | "imperialMass" | "metricMass" | "metricVolume";
|
|
52
|
+
family: keyof typeof UNIT_CONVERSIONS;
|
|
53
|
+
/** Canonical unit → its size in the ladder's smallest unit. */
|
|
54
|
+
steps: Readonly<Record<string, number>>;
|
|
55
|
+
}
|
|
56
|
+
declare const UNIT_LADDERS: readonly UnitLadder[];
|
|
57
|
+
/** Where a unit stands on its ladder. */
|
|
58
|
+
interface LadderStep {
|
|
59
|
+
ladder: UnitLadder;
|
|
60
|
+
/** The canonical unit (`cup` for `cups`, `tbsp` for `càs`). */
|
|
61
|
+
unit: string;
|
|
62
|
+
/** Its size in the ladder's smallest unit. */
|
|
63
|
+
size: number;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* The ladder a unit belongs to (any spelling: `cups`, `càs`, `kilo`), or
|
|
67
|
+
* `null` for a unit on no ladder (`pinch`, `gousse`, no unit at all).
|
|
68
|
+
*/
|
|
69
|
+
declare function ladderOf(rawUnit: string | undefined | null, lang?: string): LadderStep | null;
|
|
70
|
+
/**
|
|
71
|
+
* True when every unit stands on one same ladder (`cup`, `tbsp`, `tsp`), so
|
|
72
|
+
* their amounts add up exactly. False for no unit at all, for a unit on no
|
|
73
|
+
* ladder, and across systems (`cup` and `ml`, `oz` and `g`).
|
|
74
|
+
*/
|
|
75
|
+
declare function sameLadder(rawUnits: readonly (string | undefined | null)[], lang?: string): boolean;
|
|
76
|
+
/** The spelling of a canonical unit (`tbsp`) in a language (`càs` in French). */
|
|
77
|
+
declare function unitSpelling(canonical: string, lang?: string): string;
|
|
39
78
|
/**
|
|
40
79
|
* Normalizes a raw string unit into a standard canon unit.
|
|
41
80
|
* Examples: 'càs' -> 'tbsp', 'kilo' -> 'kg'.
|
|
@@ -69,6 +108,25 @@ declare function toLargerMetricUnit(value: number, rawUnit: string | undefined |
|
|
|
69
108
|
value: number;
|
|
70
109
|
unit: string;
|
|
71
110
|
};
|
|
111
|
+
/**
|
|
112
|
+
* Converts a value between two units of the same family, mass to mass or
|
|
113
|
+
* volume to volume (`1 l` → `1000 ml`, `1 lb` → `453.59 g`), through
|
|
114
|
+
* `UNIT_CONVERSIONS` alone. The same unit, however spelled, gives the value
|
|
115
|
+
* back. Across families (mass and volume), or for a unit that is neither,
|
|
116
|
+
* `null`: crossing needs a density, which only the caller can bring.
|
|
117
|
+
*/
|
|
118
|
+
declare function convertUnitInFamily(value: number, fromUnit: string | null | undefined, toUnit: string | null | undefined, lang?: string): number | null;
|
|
119
|
+
/**
|
|
120
|
+
* True when two counting units (neither a mass nor a volume) name the same
|
|
121
|
+
* thing: the same spelling, or one is the other with a plural ending `s`,
|
|
122
|
+
* `es` or `x` (`gousse`/`gousses`, `tranche`/`tranches`, `box`/`boxes`,
|
|
123
|
+
* `chou`/`choux`). Forms are compared, never a suffix stripped (`tranches`
|
|
124
|
+
* less `es` is `tranch`), and no plural is looked for under three letters.
|
|
125
|
+
* No unit, and every spelling of "a piece" (`pièce`, `pc`, `unit`...), count
|
|
126
|
+
* as the same: no unit. For ratios only: the shopping list keeps `gousse` and
|
|
127
|
+
* `gousses` apart.
|
|
128
|
+
*/
|
|
129
|
+
declare function sameCountUnit(a: string | null | undefined, b: string | null | undefined, lang?: string): boolean;
|
|
72
130
|
/** True for a unit of mass or volume Gram knows (g, kg, cup, tbsp, c.à.s...). */
|
|
73
131
|
declare function isMeasureUnit(rawUnit: string | undefined | null, lang?: string): boolean;
|
|
74
132
|
/**
|
|
@@ -92,11 +150,21 @@ declare function formatNumber(value: number, lang?: string, maxDecimals?: number
|
|
|
92
150
|
/** The decimal separator of a language: `"."` in English, `","` in French. */
|
|
93
151
|
declare function decimalSeparator(lang?: string): string;
|
|
94
152
|
/**
|
|
95
|
-
* The decimal
|
|
96
|
-
* `1.5-2`, a timer `1
|
|
97
|
-
*
|
|
153
|
+
* The decimal separators of a quantity already written as text (a range
|
|
154
|
+
* `1.5-2`, a timer `1,5`) in the reader's language: `"1,5-2"` in French,
|
|
155
|
+
* `"1.5"` in English. Gram reads a point or a comma between two digits as a
|
|
156
|
+
* decimal separator, so both change; `1/2` or a unit stay as they are.
|
|
98
157
|
*/
|
|
99
158
|
declare function localizeDecimals(text: string, lang?: string): string;
|
|
159
|
+
/**
|
|
160
|
+
* A comma that a reader could take for a thousands separator: exactly three
|
|
161
|
+
* digits after it and a whole part of one to three digits, not zero
|
|
162
|
+
* (`1,000`, `12,500`). Gram reads it as a decimal (1, 12.5), as it reads every
|
|
163
|
+
* comma between two digits, and has no thousands separator; `0,125` or
|
|
164
|
+
* `1,25` cannot be one. The point is not concerned: it has always been a
|
|
165
|
+
* decimal in Gram, so `1.000` keeps meaning 1.
|
|
166
|
+
*/
|
|
167
|
+
declare function looksLikeThousands(text: string): boolean;
|
|
100
168
|
/** `"1/4"` for a value strictly between 0 and 1 that is (nearly) a common fraction. */
|
|
101
169
|
declare function commonFraction(value: number): string | undefined;
|
|
102
170
|
/** True for a unit read in fractions (spoons, cups, imperial measures). */
|
|
@@ -268,6 +336,10 @@ declare const en: {
|
|
|
268
336
|
runSheetInStock: string;
|
|
269
337
|
runSheetProgramStep: string;
|
|
270
338
|
runSheetProgramSteps: string;
|
|
339
|
+
/**
|
|
340
|
+
* @deprecated Since 1.5.0, will be removed in 2.0.0. (Ref: i18n-run-sheet-range)
|
|
341
|
+
* The run sheet writes a range with `formatDurationRange` (`8–16 h`), as the steps do.
|
|
342
|
+
*/
|
|
271
343
|
runSheetRange: string;
|
|
272
344
|
runSheetPossibleFrom: string;
|
|
273
345
|
runSheetFixedService: string;
|
|
@@ -316,6 +388,8 @@ declare const en: {
|
|
|
316
388
|
tooltipBakers: string;
|
|
317
389
|
tooltipTakenFrom: string;
|
|
318
390
|
alternatives: string;
|
|
391
|
+
tooltipRatio: string;
|
|
392
|
+
relativeOf: string;
|
|
319
393
|
decreasePortions: string;
|
|
320
394
|
editPortions: string;
|
|
321
395
|
increasePortions: string;
|
|
@@ -477,6 +551,10 @@ declare const en: {
|
|
|
477
551
|
stepQuantitiesDesc: string;
|
|
478
552
|
nutritionBasis: string;
|
|
479
553
|
nutritionBasisAuto: string;
|
|
554
|
+
clock: string;
|
|
555
|
+
clockAuto: string;
|
|
556
|
+
clock12h: string;
|
|
557
|
+
clock24h: string;
|
|
480
558
|
rejectedSlots: string;
|
|
481
559
|
forceReference: string;
|
|
482
560
|
autoDetect: string;
|
|
@@ -500,6 +578,7 @@ declare const en: {
|
|
|
500
578
|
scaleByIngredient: string;
|
|
501
579
|
bakersMath: string;
|
|
502
580
|
comments: string;
|
|
581
|
+
clock: string;
|
|
503
582
|
stepQuantities: string;
|
|
504
583
|
nutritionBasis: string;
|
|
505
584
|
bakersMathOnly: string;
|
|
@@ -534,6 +613,8 @@ declare const en: {
|
|
|
534
613
|
show: string;
|
|
535
614
|
expandConsole: string;
|
|
536
615
|
collapseConsole: string;
|
|
616
|
+
notInDatabase: string;
|
|
617
|
+
showDatabase: string;
|
|
537
618
|
};
|
|
538
619
|
errorState: {
|
|
539
620
|
title: string;
|
|
@@ -541,6 +622,12 @@ declare const en: {
|
|
|
541
622
|
jumpToError: string;
|
|
542
623
|
line: string;
|
|
543
624
|
};
|
|
625
|
+
database: {
|
|
626
|
+
tabLabel: string;
|
|
627
|
+
project: string;
|
|
628
|
+
docLink: string;
|
|
629
|
+
docHref: string;
|
|
630
|
+
};
|
|
544
631
|
tabs: {
|
|
545
632
|
addFile: string;
|
|
546
633
|
removeFile: string;
|
|
@@ -566,6 +653,18 @@ declare const en: {
|
|
|
566
653
|
statusWarnings: string;
|
|
567
654
|
copyBtn: string;
|
|
568
655
|
};
|
|
656
|
+
cook: {
|
|
657
|
+
/** Under a step of `gram cook`: the state that ends it (`={ribbon stage}`). */
|
|
658
|
+
targetState: string;
|
|
659
|
+
/** When a timer of a step rings: the target states to check, `{states}`. */
|
|
660
|
+
checkTargetState: string;
|
|
661
|
+
};
|
|
662
|
+
languageServer: {
|
|
663
|
+
/** Hover on a section anchor: `{duration}` is the anticipation. */
|
|
664
|
+
anchorReady: string;
|
|
665
|
+
anchorInDays: string;
|
|
666
|
+
anchorInHours: string;
|
|
667
|
+
};
|
|
569
668
|
};
|
|
570
669
|
type GramLocale = typeof en;
|
|
571
670
|
|
|
@@ -578,4 +677,322 @@ declare function getDictionary(lang?: string): GramLocale;
|
|
|
578
677
|
*/
|
|
579
678
|
declare function fillTemplate(template: string, values: Readonly<Record<string, string>>): string;
|
|
580
679
|
|
|
581
|
-
|
|
680
|
+
/**
|
|
681
|
+
* Durations as a recipe writes them: `1h30`, `1 hr 30 mins`, `1 heure 30`,
|
|
682
|
+
* `1:30 h`, `5'30"`, `45 min - 1 h`. `parseDuration` reads one into minutes,
|
|
683
|
+
* or says precisely why it will not: it never guesses, and never turns an
|
|
684
|
+
* unclear duration into 0.
|
|
685
|
+
*
|
|
686
|
+
* Reading happens in two steps. The text is first cut into tokens by kind of
|
|
687
|
+
* character (numbers, letters, primes, `:`, `+`, `-`), so spaces carry no
|
|
688
|
+
* meaning (`1h30`, `1 h 30`, `1hr 30` read alike), except between a whole
|
|
689
|
+
* number and a fraction (`1 1/2`). The token sequence is then checked against
|
|
690
|
+
* the three forms (units, clock, primes) and the range rules.
|
|
691
|
+
*
|
|
692
|
+
* The units come from `TIME_DICTIONARIES`, every language at once: a timer
|
|
693
|
+
* reads without knowing the language of the recipe.
|
|
694
|
+
*/
|
|
695
|
+
/** A canonical time unit: day, hour, minute, second. */
|
|
696
|
+
type DurationUnit = "d" | "h" | "m" | "s";
|
|
697
|
+
/** How a duration is written: `1h30` (units), `1:30 h` (clock), `5'30"` (primes). */
|
|
698
|
+
type DurationForm = "units" | "clock" | "prime";
|
|
699
|
+
/** One term of a duration, in the unit it was written in (`1h30` is `1 h` and `30 m`). */
|
|
700
|
+
interface DurationPart {
|
|
701
|
+
value: number;
|
|
702
|
+
unit: DurationUnit;
|
|
703
|
+
}
|
|
704
|
+
/** One duration, or one side of a range. */
|
|
705
|
+
interface DurationSide {
|
|
706
|
+
minutes: number;
|
|
707
|
+
parts: DurationPart[];
|
|
708
|
+
form: DurationForm;
|
|
709
|
+
}
|
|
710
|
+
/**
|
|
711
|
+
* Why a text is not a duration Gram reads:
|
|
712
|
+
* - `empty`: nothing between the braces;
|
|
713
|
+
* - `missingUnit`: a number with no unit at all (`30`, `1-2`);
|
|
714
|
+
* - `unknownUnit`: a word right after a number that is not a time unit (`3 bananas`);
|
|
715
|
+
* - `words`: any other word (`half an hour`, `1 heure et demie`, `about 10 min`);
|
|
716
|
+
* - `multiplication`: `2 * 2 min`, written as the total instead;
|
|
717
|
+
* - `iso8601`: `PT1H30M`, a notation for machines;
|
|
718
|
+
* - `unexpected`: a character or a sign out of place (`1h, 30min`, `-10 min`, `1/0 h`);
|
|
719
|
+
* - `ambiguousClock`: a two-part clock with no unit (`1:30`: hours or minutes?);
|
|
720
|
+
* - `clockFormat`: a malformed clock (`1:5 h`, `1:30 d`, more than three parts);
|
|
721
|
+
* - `unitOrder`: units not from the largest to the smallest (`30min 1h`);
|
|
722
|
+
* - `duplicateUnit`: the same unit twice (`1h 2h`);
|
|
723
|
+
* - `overflow60`: 60 or more after an hour or a minute, where the unit is
|
|
724
|
+
* implied, in a clock or with a prime (`1h75`, `1:75 h`, `5'90"`); with its
|
|
725
|
+
* unit written out it is read as written (`1 h 75 min` is 2 h 15 min);
|
|
726
|
+
* - `decimalInCompound`: a decimal or a fraction in a duration of several terms (`1.5h30`);
|
|
727
|
+
* - `decimalPrime`: a decimal or a fraction with a prime (`1.5'`);
|
|
728
|
+
* - `bareNumber`: a number with no unit where none can be implied (`1j3`, `1 30 min`);
|
|
729
|
+
* - `reversedRange`: a range written from the largest to the smallest (`2-1 h`):
|
|
730
|
+
* the minimum comes first, in the order of the text (logical order, so a
|
|
731
|
+
* right-to-left language writes it the same way);
|
|
732
|
+
* - `emptyRange`: a range whose two sides are equal (`1-1 h`);
|
|
733
|
+
* - `ambiguousRange`: a range where one side's unit cannot be told (`1-2h30`).
|
|
734
|
+
*/
|
|
735
|
+
type DurationFailure = "empty" | "missingUnit" | "unknownUnit" | "words" | "multiplication" | "iso8601" | "unexpected" | "ambiguousClock" | "clockFormat" | "unitOrder" | "duplicateUnit" | "overflow60" | "decimalInCompound" | "decimalPrime" | "bareNumber" | "reversedRange" | "emptyRange" | "ambiguousRange";
|
|
736
|
+
type DurationResult = {
|
|
737
|
+
ok: true;
|
|
738
|
+
/** The duration the schedule uses: the middle of a range. */
|
|
739
|
+
minutes: number;
|
|
740
|
+
range?: {
|
|
741
|
+
min: number;
|
|
742
|
+
max: number;
|
|
743
|
+
};
|
|
744
|
+
/** One side, or the two sides of a range. */
|
|
745
|
+
sides: [DurationSide] | [DurationSide, DurationSide];
|
|
746
|
+
} | {
|
|
747
|
+
ok: false;
|
|
748
|
+
reason: DurationFailure;
|
|
749
|
+
/** The word read as a unit, for `unknownUnit`. */
|
|
750
|
+
unit?: string;
|
|
751
|
+
};
|
|
752
|
+
type Failure = Extract<DurationResult, {
|
|
753
|
+
ok: false;
|
|
754
|
+
}>;
|
|
755
|
+
/**
|
|
756
|
+
* `int`: digits only (`30`). `decimal`: `1.5`, `1,5`. `fraction`: `1/2`, `½`,
|
|
757
|
+
* `1½`, `1 1/2`. Only an `int` follows an hour or a minute without a unit, or
|
|
758
|
+
* makes a clock.
|
|
759
|
+
*/
|
|
760
|
+
type NumKind = "int" | "decimal" | "fraction";
|
|
761
|
+
type Token = {
|
|
762
|
+
kind: "num";
|
|
763
|
+
value: number;
|
|
764
|
+
text: string;
|
|
765
|
+
num: NumKind;
|
|
766
|
+
space: boolean;
|
|
767
|
+
} | {
|
|
768
|
+
kind: "word";
|
|
769
|
+
text: string;
|
|
770
|
+
unit?: DurationUnit;
|
|
771
|
+
} | {
|
|
772
|
+
kind: "prime";
|
|
773
|
+
unit: "m" | "s";
|
|
774
|
+
} | {
|
|
775
|
+
kind: "colon";
|
|
776
|
+
} | {
|
|
777
|
+
kind: "plus";
|
|
778
|
+
} | {
|
|
779
|
+
kind: "dash";
|
|
780
|
+
} | {
|
|
781
|
+
kind: "star";
|
|
782
|
+
};
|
|
783
|
+
/**
|
|
784
|
+
* Cuts a duration into tokens: the step that makes `1h30`, `1 h 30` and
|
|
785
|
+
* `1hr 30` the same sequence. A unit is any run of letters, in any script,
|
|
786
|
+
* lowercased, with a `.` right after it dropped (`hr.`, `min.`, `Std.`).
|
|
787
|
+
*/
|
|
788
|
+
declare function tokenizeDuration(text: string): {
|
|
789
|
+
ok: true;
|
|
790
|
+
tokens: Token[];
|
|
791
|
+
} | Failure;
|
|
792
|
+
/**
|
|
793
|
+
* Reads a duration as a recipe writes it, in any language Gram knows:
|
|
794
|
+
* `parseDuration("1h30")` is `{ ok: true, minutes: 90, … }`,
|
|
795
|
+
* `parseDuration("1:30")` is `{ ok: false, reason: "ambiguousClock" }`.
|
|
796
|
+
*
|
|
797
|
+
* A range keeps both sides and gives its middle as `minutes`, as the schedule
|
|
798
|
+
* uses it. No sign is read (an anchor's `-` is the caller's), and no duration
|
|
799
|
+
* is capped: that is the compiler's job.
|
|
800
|
+
*/
|
|
801
|
+
declare function parseDuration(text: string): DurationResult;
|
|
802
|
+
|
|
803
|
+
/**
|
|
804
|
+
* A numeric value as the compiled recipe stores it: a plain number, or the
|
|
805
|
+
* parser's single / fraction / range shape (structurally the parser's
|
|
806
|
+
* `QuantityValueAST`, redeclared here so this module stays free of it).
|
|
807
|
+
*/
|
|
808
|
+
type QuantityValue = {
|
|
809
|
+
type: "single";
|
|
810
|
+
value: number;
|
|
811
|
+
text?: string;
|
|
812
|
+
} | {
|
|
813
|
+
type: "fraction";
|
|
814
|
+
value: number;
|
|
815
|
+
numerator: number;
|
|
816
|
+
denominator: number;
|
|
817
|
+
text?: string;
|
|
818
|
+
} | {
|
|
819
|
+
type: "range";
|
|
820
|
+
value: number;
|
|
821
|
+
range: {
|
|
822
|
+
min: number;
|
|
823
|
+
max: number;
|
|
824
|
+
};
|
|
825
|
+
text?: string;
|
|
826
|
+
};
|
|
827
|
+
/** The value of one term: kept in the shape it was written in. */
|
|
828
|
+
type TermValue = number | QuantityValue;
|
|
829
|
+
interface Term {
|
|
830
|
+
value: TermValue;
|
|
831
|
+
unit: string | null;
|
|
832
|
+
/** Taken away from the total (`- 2 tbsp`). */
|
|
833
|
+
minus?: boolean;
|
|
834
|
+
}
|
|
835
|
+
/** What a list of terms amounts to, in the compiled recipe's `qty` / `unit` shape. */
|
|
836
|
+
interface TermsTotal {
|
|
837
|
+
qty: TermValue;
|
|
838
|
+
unit: string | null;
|
|
839
|
+
}
|
|
840
|
+
/** Raised by `scaleTerms` when a scaled value stops being a finite number. */
|
|
841
|
+
declare class QuantityOverflowError extends RangeError {
|
|
842
|
+
readonly factor: number;
|
|
843
|
+
constructor(factor: number);
|
|
844
|
+
}
|
|
845
|
+
/**
|
|
846
|
+
* Rounds a mass/quantity value to 2 decimal places, returning a `number`
|
|
847
|
+
* (not a string). Centralizes the `parseFloat(x.toFixed(2))` idiom used
|
|
848
|
+
* throughout kitchen/analyzer so there is a single, documented rounding rule
|
|
849
|
+
* to port when the compiler is reimplemented in another language: `toFixed`
|
|
850
|
+
* uses round-half-away-from-zero on the value's shortest decimal
|
|
851
|
+
* representation, which differs from IEEE round-half-to-even on exact ties.
|
|
852
|
+
*/
|
|
853
|
+
declare const round2: (value: number) => number;
|
|
854
|
+
/** True for a value a term can hold (a number, or a single / fraction / range). */
|
|
855
|
+
declare function isTermValue(value: unknown): value is TermValue;
|
|
856
|
+
/**
|
|
857
|
+
* The number a value stands for: the number itself, or its `value` (the
|
|
858
|
+
* middle of a range). `null` when the value carries no number.
|
|
859
|
+
*/
|
|
860
|
+
declare function termValueNumber(value: TermValue): number | null;
|
|
861
|
+
/**
|
|
862
|
+
* What the terms amount to.
|
|
863
|
+
*
|
|
864
|
+
* - no term: `null`;
|
|
865
|
+
* - one term added: that term as written (a range stays a range, a fraction
|
|
866
|
+
* keeps its text);
|
|
867
|
+
* - several terms of one unit (its spellings count as one: `cup` / `cups`):
|
|
868
|
+
* their sum in that unit, never converted (`1 tasse + 1 tasse` is
|
|
869
|
+
* `2 tasses`), spelled as the first term added;
|
|
870
|
+
* - several units of one ladder (`UNIT_LADDERS`): their exact sum in the
|
|
871
|
+
* smallest unit written (`1 cup + 1 tbsp` is `17 tbsp`);
|
|
872
|
+
* - several units of one family across systems (`cup` and `ml`, `oz` and
|
|
873
|
+
* `g`): their sum in grams or milliliters, rounded to 2 decimals;
|
|
874
|
+
* - otherwise (`cup` and `g`, `gousse` and `pièce`, a term with no unit next
|
|
875
|
+
* to one with a unit): `null`, the terms do not add up to one amount.
|
|
876
|
+
*
|
|
877
|
+
* A range is added by its bounds (`2-3 g + 200 g` is `202-203 g`): a term
|
|
878
|
+
* taken away removes its highest number from the lowest bound and its lowest
|
|
879
|
+
* number from the highest one. A total with a range in it stays a range.
|
|
880
|
+
*/
|
|
881
|
+
declare function termsTotal(terms: readonly Term[]): TermsTotal | null;
|
|
882
|
+
/**
|
|
883
|
+
* How terms are grouped (`mergeKey`): by unit, by ladder of units (`cup` and
|
|
884
|
+
* `tbsp`), or by family, the kind of amount a unit measures (`familyOf`:
|
|
885
|
+
* every mass together, every volume together).
|
|
886
|
+
*/
|
|
887
|
+
type MergeMode = "unit" | "ladder" | "family";
|
|
888
|
+
/**
|
|
889
|
+
* The kind of amount a unit measures, for telling the families of a sum
|
|
890
|
+
* apart: a mass, a volume, or (a unit Gram cannot convert, `gousse`) that
|
|
891
|
+
* unit itself.
|
|
892
|
+
*/
|
|
893
|
+
declare function familyOf(unit: string | null): string;
|
|
894
|
+
/**
|
|
895
|
+
* The key `mergeTerms` groups a term's unit under: its family in `"family"`
|
|
896
|
+
* mode (`familyOf`), its ladder in `"ladder"` mode (`cup` and `tbsp`, `g`
|
|
897
|
+
* and `kg`), otherwise the unit itself, its spellings counted as one (`cup`
|
|
898
|
+
* / `cups`). A unit Gram does not know (`gousse`) is only lowercased:
|
|
899
|
+
* `gousse` and `gousses` stay two units.
|
|
900
|
+
*/
|
|
901
|
+
declare function mergeKey(unit: string | null, mode: MergeMode): string;
|
|
902
|
+
/** The terms grouped by `mergeKey`, groups in the order their first term comes. */
|
|
903
|
+
declare function groupTerms(terms: readonly Term[], mode: MergeMode): Term[][];
|
|
904
|
+
/**
|
|
905
|
+
* Puts the terms of several amounts of one ingredient together, terms added
|
|
906
|
+
* before terms taken away (`2 tbsp` then `1 cup - 4 tbsp` gives
|
|
907
|
+
* `1 cup - 2 tbsp`, never a term taken away first).
|
|
908
|
+
*
|
|
909
|
+
* - `"unit"` adds up the terms of each unit into one, its spellings counted
|
|
910
|
+
* as one (`100 g` and `100 g` give `200 g`); two units stay apart, even on
|
|
911
|
+
* one ladder (`1 cup`, `2 tbsp`): this is how a section lists an
|
|
912
|
+
* ingredient it uses several times.
|
|
913
|
+
* - `"ladder"` adds up the terms of each ladder into one, in the smallest
|
|
914
|
+
* unit written (`1 cup`, `2 tbsp` and `- 4 tbsp` give `14 tbsp`, see
|
|
915
|
+
* `termsTotal`), and the terms of each unit on no ladder into one; two
|
|
916
|
+
* systems (`cup` and `ml`) or two families stay apart.
|
|
917
|
+
*
|
|
918
|
+
* Each result keeps the place of the first term it adds up; a negative
|
|
919
|
+
* result is a term taken away, a result of zero is left out (unless nothing
|
|
920
|
+
* else is left). A lone term stays as written.
|
|
921
|
+
*/
|
|
922
|
+
declare function mergeTerms(terms: readonly Term[], mode: MergeMode): Term[];
|
|
923
|
+
/**
|
|
924
|
+
* Multiplies a value by `factor`, rounded to 2 decimals. The source text of a
|
|
925
|
+
* value (`text`, a fraction's `numerator` / `denominator`) only describes the
|
|
926
|
+
* unscaled value, so it is dropped: a scaled fraction becomes a single value.
|
|
927
|
+
* A value that is not a number (a malformed object) comes back untouched.
|
|
928
|
+
* Throws `QuantityOverflowError` when the product is no longer finite.
|
|
929
|
+
*/
|
|
930
|
+
declare function scaleTermValue<T extends TermValue>(value: T, factor: number): TermValue;
|
|
931
|
+
/** Every term multiplied by `factor` (see `scaleTermValue`); units are kept. */
|
|
932
|
+
declare function scaleTerms(terms: readonly Term[], factor: number): Term[];
|
|
933
|
+
/** One term as written: its number (or source text) and its unit, without its sign. */
|
|
934
|
+
declare function formatTerm(term: Term): string;
|
|
935
|
+
interface FormatTermsOptions {
|
|
936
|
+
/** Placed between two terms added. Default ` + `. */
|
|
937
|
+
plus?: string;
|
|
938
|
+
/** Placed before a term taken away. Default ` − `. */
|
|
939
|
+
minus?: string;
|
|
940
|
+
/**
|
|
941
|
+
* `"written"` (default): the terms as the author wrote them.
|
|
942
|
+
* `"computed"`: an amount Gram worked out (scaled, or added up from
|
|
943
|
+
* several occurrences), written the way a cook measures it (see
|
|
944
|
+
* `formatTerms`).
|
|
945
|
+
*/
|
|
946
|
+
mode?: "written" | "computed";
|
|
947
|
+
/** The reader's language: decimals, and the spelling of a unit Gram brings in. */
|
|
948
|
+
lang?: string;
|
|
949
|
+
/**
|
|
950
|
+
* Writes a number next to its unit. Default: the number as it is in
|
|
951
|
+
* `"written"` mode; in `"computed"` mode a whole number, a kitchen
|
|
952
|
+
* fraction for a spoon or an imperial unit (`1 1/2`), otherwise a
|
|
953
|
+
* decimal in the reader's language.
|
|
954
|
+
*/
|
|
955
|
+
number?: (value: number, unit: string | null) => string;
|
|
956
|
+
/** Writes a value's source text (`1/2`, `2.5-3`). Default: as it is. */
|
|
957
|
+
text?: (text: string) => string;
|
|
958
|
+
/**
|
|
959
|
+
* `"computed"` only: an amount the reader buys (a shopping list). A
|
|
960
|
+
* metric amount reaches the larger unit (`1500 g` is `1.5 kg`), and a
|
|
961
|
+
* spoon or imperial amount is recomposed from the top of its scale
|
|
962
|
+
* (`34 tbsp` is `2 cup + 2 tbsp`) once it reaches one of a unit at least
|
|
963
|
+
* four times larger than its own (`3 tsp` stays `3 tsp`).
|
|
964
|
+
*/
|
|
965
|
+
buying?: boolean;
|
|
966
|
+
/**
|
|
967
|
+
* `"computed"` only, default `true`: a recomposition may round its last
|
|
968
|
+
* term to what its unit measures (a scaled amount was no exact measure
|
|
969
|
+
* anyway: `1.1 cup` is `1 cup + 1 tbsp + 2 tsp`). `false` writes an
|
|
970
|
+
* amount that does not recompose exactly as it is (`1.6 cup`).
|
|
971
|
+
*/
|
|
972
|
+
rounding?: boolean;
|
|
973
|
+
}
|
|
974
|
+
/**
|
|
975
|
+
* The terms as text, in their written order (`1 cup + 1 tbsp`,
|
|
976
|
+
* `1 cup − 2 tbsp + 30 g`); a list that would start with a term taken away
|
|
977
|
+
* writes the terms added first (`1 cup − 2 tbsp`, never `−2 tbsp + 1 cup`).
|
|
978
|
+
*
|
|
979
|
+
* `"written"` mode (the default) writes each term as the author wrote it.
|
|
980
|
+
* `"computed"` mode writes an amount Gram worked out, ladder by ladder (two
|
|
981
|
+
* systems stay apart, term by term):
|
|
982
|
+
*
|
|
983
|
+
* - a spoon, cup or imperial amount is recomposed the way a cook measures
|
|
984
|
+
* it: one amount of the largest unit written when that unit measures it
|
|
985
|
+
* (`MEASURED_FRACTIONS`: `1 1/2 cup`, never `2 1/8 cup`), the terms as they
|
|
986
|
+
* are when each is measurable, otherwise whole units then the rest in the
|
|
987
|
+
* next unit down (`cup`, `tbsp`, `tsp`; `gal`, `qt`, `pt`, `fl oz`; `lb`,
|
|
988
|
+
* `oz`), never above the largest unit written, three terms at most;
|
|
989
|
+
* - a metric amount is one decimal amount in the largest unit written
|
|
990
|
+
* (`1 kg + 200 g` doubled is `2.4 kg`; `800 g + 200 g` is `1000 g`, never
|
|
991
|
+
* `1 kg`, unless `buying`);
|
|
992
|
+
* - a range shares what both bounds have in common and puts the range on
|
|
993
|
+
* the last term (`2 cup + 2-4 tbsp`), otherwise writes each bound in full;
|
|
994
|
+
* - a unit on no ladder adds up with itself only (`2 gousses`).
|
|
995
|
+
*/
|
|
996
|
+
declare function formatTerms(terms: readonly Term[], options?: FormatTermsOptions): string;
|
|
997
|
+
|
|
998
|
+
export { CATEGORY_KEYS, type CategoryKey, type CompiledDict, type DurationFailure, type DurationForm, type DurationPart, type DurationResult, type DurationSide, type DurationUnit, type FormatTermsOptions, type GramLocale, type LadderStep, type LanguageDict, type MergeMode, QuantityOverflowError, type QuantityValue, TIME_BY_LANG, TIME_DICTIONARIES, TIME_GLOBAL, TIME_TO_MINUTES, type Term, type TermValue, type TermsTotal, UNIT_BY_LANG, UNIT_CONVERSIONS, UNIT_DICTIONARIES, UNIT_GLOBAL, UNIT_LADDERS, type UnitLadder, type UnitMap, commonFraction, compileDictionary, convertUnitInFamily, decimalSeparator, familyOf, fillTemplate, formatNumber, formatTerm, formatTerms, getAiLanguageInstruction, getCategoryLabels, getDefaultCategories, getDictionary, groupTerms, isCategoryKey, isCoarseUnit, isFractionUnit, isMeasureUnit, isMetricMassUnit, isTermValue, ladderOf, localizeDecimals, looksLikeThousands, mergeKey, mergeTerms, normalizeUnit, parseDuration, resolveTimeUnit, round2, sameCountUnit, sameLadder, scaleTermValue, scaleTerms, termValueNumber, termsTotal, toKitchenFraction, toLargerMetricUnit, tokenizeDuration, unitContainsQuantity, unitKey, unitSpelling };
|