@gram-lang/i18n 1.4.2 → 1.5.1
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 +443 -4
- package/dist/index.js +963 -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
|
/**
|
|
@@ -89,14 +147,37 @@ declare function unitContainsQuantity(rawUnit: string | undefined | null, lang?:
|
|
|
89
147
|
* `formatNumber(1500, "fr")` is `"1500"`.
|
|
90
148
|
*/
|
|
91
149
|
declare function formatNumber(value: number, lang?: string, maxDecimals?: number): string;
|
|
150
|
+
/**
|
|
151
|
+
* How many decimals an amount keeps when it is shown: 3 significant digits,
|
|
152
|
+
* never fewer than its whole part (`152.37` → `152`, `15.24` → `15.2`,
|
|
153
|
+
* `1.15` → `1.15`), and 2 significant digits below 1 (`0.15`, `0.03`,
|
|
154
|
+
* `0.0047`), so a small amount is never shown as `0`. The precision follows
|
|
155
|
+
* the size of the amount, not its unit: rounded to a fixed decimal in the
|
|
156
|
+
* author's unit, `0.15 kg` read `0.2 kg` and `0.02 kg` read `0 kg` (#230).
|
|
157
|
+
*/
|
|
158
|
+
declare function amountDecimals(value: number): number;
|
|
159
|
+
/** An amount rounded as it is shown (see `amountDecimals`). */
|
|
160
|
+
declare function roundAmount(value: number): number;
|
|
161
|
+
/** An amount as it is shown, in the reader's language (see `amountDecimals`). */
|
|
162
|
+
declare function formatAmount(value: number, lang?: string): string;
|
|
92
163
|
/** The decimal separator of a language: `"."` in English, `","` in French. */
|
|
93
164
|
declare function decimalSeparator(lang?: string): string;
|
|
94
165
|
/**
|
|
95
|
-
* The decimal
|
|
96
|
-
* `1.5-2`, a timer `1
|
|
97
|
-
*
|
|
166
|
+
* The decimal separators of a quantity already written as text (a range
|
|
167
|
+
* `1.5-2`, a timer `1,5`) in the reader's language: `"1,5-2"` in French,
|
|
168
|
+
* `"1.5"` in English. Gram reads a point or a comma between two digits as a
|
|
169
|
+
* decimal separator, so both change; `1/2` or a unit stay as they are.
|
|
98
170
|
*/
|
|
99
171
|
declare function localizeDecimals(text: string, lang?: string): string;
|
|
172
|
+
/**
|
|
173
|
+
* A comma that a reader could take for a thousands separator: exactly three
|
|
174
|
+
* digits after it and a whole part of one to three digits, not zero
|
|
175
|
+
* (`1,000`, `12,500`). Gram reads it as a decimal (1, 12.5), as it reads every
|
|
176
|
+
* comma between two digits, and has no thousands separator; `0,125` or
|
|
177
|
+
* `1,25` cannot be one. The point is not concerned: it has always been a
|
|
178
|
+
* decimal in Gram, so `1.000` keeps meaning 1.
|
|
179
|
+
*/
|
|
180
|
+
declare function looksLikeThousands(text: string): boolean;
|
|
100
181
|
/** `"1/4"` for a value strictly between 0 and 1 that is (nearly) a common fraction. */
|
|
101
182
|
declare function commonFraction(value: number): string | undefined;
|
|
102
183
|
/** True for a unit read in fractions (spoons, cups, imperial measures). */
|
|
@@ -268,6 +349,10 @@ declare const en: {
|
|
|
268
349
|
runSheetInStock: string;
|
|
269
350
|
runSheetProgramStep: string;
|
|
270
351
|
runSheetProgramSteps: string;
|
|
352
|
+
/**
|
|
353
|
+
* @deprecated Since 1.5.0, will be removed in 2.0.0. (Ref: i18n-run-sheet-range)
|
|
354
|
+
* The run sheet writes a range with `formatDurationRange` (`8–16 h`), as the steps do.
|
|
355
|
+
*/
|
|
271
356
|
runSheetRange: string;
|
|
272
357
|
runSheetPossibleFrom: string;
|
|
273
358
|
runSheetFixedService: string;
|
|
@@ -316,6 +401,8 @@ declare const en: {
|
|
|
316
401
|
tooltipBakers: string;
|
|
317
402
|
tooltipTakenFrom: string;
|
|
318
403
|
alternatives: string;
|
|
404
|
+
tooltipRatio: string;
|
|
405
|
+
relativeOf: string;
|
|
319
406
|
decreasePortions: string;
|
|
320
407
|
editPortions: string;
|
|
321
408
|
increasePortions: string;
|
|
@@ -477,6 +564,10 @@ declare const en: {
|
|
|
477
564
|
stepQuantitiesDesc: string;
|
|
478
565
|
nutritionBasis: string;
|
|
479
566
|
nutritionBasisAuto: string;
|
|
567
|
+
clock: string;
|
|
568
|
+
clockAuto: string;
|
|
569
|
+
clock12h: string;
|
|
570
|
+
clock24h: string;
|
|
480
571
|
rejectedSlots: string;
|
|
481
572
|
forceReference: string;
|
|
482
573
|
autoDetect: string;
|
|
@@ -500,6 +591,7 @@ declare const en: {
|
|
|
500
591
|
scaleByIngredient: string;
|
|
501
592
|
bakersMath: string;
|
|
502
593
|
comments: string;
|
|
594
|
+
clock: string;
|
|
503
595
|
stepQuantities: string;
|
|
504
596
|
nutritionBasis: string;
|
|
505
597
|
bakersMathOnly: string;
|
|
@@ -534,6 +626,8 @@ declare const en: {
|
|
|
534
626
|
show: string;
|
|
535
627
|
expandConsole: string;
|
|
536
628
|
collapseConsole: string;
|
|
629
|
+
notInDatabase: string;
|
|
630
|
+
showDatabase: string;
|
|
537
631
|
};
|
|
538
632
|
errorState: {
|
|
539
633
|
title: string;
|
|
@@ -541,6 +635,12 @@ declare const en: {
|
|
|
541
635
|
jumpToError: string;
|
|
542
636
|
line: string;
|
|
543
637
|
};
|
|
638
|
+
database: {
|
|
639
|
+
tabLabel: string;
|
|
640
|
+
project: string;
|
|
641
|
+
docLink: string;
|
|
642
|
+
docHref: string;
|
|
643
|
+
};
|
|
544
644
|
tabs: {
|
|
545
645
|
addFile: string;
|
|
546
646
|
removeFile: string;
|
|
@@ -566,6 +666,18 @@ declare const en: {
|
|
|
566
666
|
statusWarnings: string;
|
|
567
667
|
copyBtn: string;
|
|
568
668
|
};
|
|
669
|
+
cook: {
|
|
670
|
+
/** Under a step of `gram cook`: the state that ends it (`={ribbon stage}`). */
|
|
671
|
+
targetState: string;
|
|
672
|
+
/** When a timer of a step rings: the target states to check, `{states}`. */
|
|
673
|
+
checkTargetState: string;
|
|
674
|
+
};
|
|
675
|
+
languageServer: {
|
|
676
|
+
/** Hover on a section anchor: `{duration}` is the anticipation. */
|
|
677
|
+
anchorReady: string;
|
|
678
|
+
anchorInDays: string;
|
|
679
|
+
anchorInHours: string;
|
|
680
|
+
};
|
|
569
681
|
};
|
|
570
682
|
type GramLocale = typeof en;
|
|
571
683
|
|
|
@@ -578,4 +690,331 @@ declare function getDictionary(lang?: string): GramLocale;
|
|
|
578
690
|
*/
|
|
579
691
|
declare function fillTemplate(template: string, values: Readonly<Record<string, string>>): string;
|
|
580
692
|
|
|
581
|
-
|
|
693
|
+
/**
|
|
694
|
+
* Durations as a recipe writes them: `1h30`, `1 hr 30 mins`, `1 heure 30`,
|
|
695
|
+
* `1:30 h`, `5'30"`, `45 min - 1 h`. `parseDuration` reads one into minutes,
|
|
696
|
+
* or says precisely why it will not: it never guesses, and never turns an
|
|
697
|
+
* unclear duration into 0.
|
|
698
|
+
*
|
|
699
|
+
* Reading happens in two steps. The text is first cut into tokens by kind of
|
|
700
|
+
* character (numbers, letters, primes, `:`, `+`, `-`), so spaces carry no
|
|
701
|
+
* meaning (`1h30`, `1 h 30`, `1hr 30` read alike), except between a whole
|
|
702
|
+
* number and a fraction (`1 1/2`). The token sequence is then checked against
|
|
703
|
+
* the three forms (units, clock, primes) and the range rules.
|
|
704
|
+
*
|
|
705
|
+
* The units come from `TIME_DICTIONARIES`, every language at once: a timer
|
|
706
|
+
* reads without knowing the language of the recipe.
|
|
707
|
+
*/
|
|
708
|
+
/** A canonical time unit: day, hour, minute, second. */
|
|
709
|
+
type DurationUnit = "d" | "h" | "m" | "s";
|
|
710
|
+
/** How a duration is written: `1h30` (units), `1:30 h` (clock), `5'30"` (primes). */
|
|
711
|
+
type DurationForm = "units" | "clock" | "prime";
|
|
712
|
+
/** One term of a duration, in the unit it was written in (`1h30` is `1 h` and `30 m`). */
|
|
713
|
+
interface DurationPart {
|
|
714
|
+
value: number;
|
|
715
|
+
unit: DurationUnit;
|
|
716
|
+
}
|
|
717
|
+
/** One duration, or one side of a range. */
|
|
718
|
+
interface DurationSide {
|
|
719
|
+
minutes: number;
|
|
720
|
+
parts: DurationPart[];
|
|
721
|
+
form: DurationForm;
|
|
722
|
+
}
|
|
723
|
+
/**
|
|
724
|
+
* Why a text is not a duration Gram reads:
|
|
725
|
+
* - `empty`: nothing between the braces;
|
|
726
|
+
* - `missingUnit`: a number with no unit at all (`30`, `1-2`);
|
|
727
|
+
* - `unknownUnit`: a word right after a number that is not a time unit (`3 bananas`);
|
|
728
|
+
* - `words`: any other word (`half an hour`, `1 heure et demie`, `about 10 min`);
|
|
729
|
+
* - `multiplication`: `2 * 2 min`, written as the total instead;
|
|
730
|
+
* - `iso8601`: `PT1H30M`, a notation for machines;
|
|
731
|
+
* - `unexpected`: a character or a sign out of place (`1h, 30min`, `-10 min`, `1/0 h`);
|
|
732
|
+
* - `ambiguousClock`: a two-part clock with no unit (`1:30`: hours or minutes?);
|
|
733
|
+
* - `clockFormat`: a malformed clock (`1:5 h`, `1:30 d`, more than three parts);
|
|
734
|
+
* - `unitOrder`: units not from the largest to the smallest (`30min 1h`);
|
|
735
|
+
* - `duplicateUnit`: the same unit twice (`1h 2h`);
|
|
736
|
+
* - `overflow60`: 60 or more after an hour or a minute, where the unit is
|
|
737
|
+
* implied, in a clock or with a prime (`1h75`, `1:75 h`, `5'90"`); with its
|
|
738
|
+
* unit written out it is read as written (`1 h 75 min` is 2 h 15 min);
|
|
739
|
+
* - `decimalInCompound`: a decimal or a fraction in a duration of several terms (`1.5h30`);
|
|
740
|
+
* - `decimalPrime`: a decimal or a fraction with a prime (`1.5'`);
|
|
741
|
+
* - `bareNumber`: a number with no unit where none can be implied (`1j3`, `1 30 min`);
|
|
742
|
+
* - `reversedRange`: a range written from the largest to the smallest (`2-1 h`):
|
|
743
|
+
* the minimum comes first, in the order of the text (logical order, so a
|
|
744
|
+
* right-to-left language writes it the same way);
|
|
745
|
+
* - `emptyRange`: a range whose two sides are equal (`1-1 h`);
|
|
746
|
+
* - `ambiguousRange`: a range where one side's unit cannot be told (`1-2h30`).
|
|
747
|
+
*/
|
|
748
|
+
type DurationFailure = "empty" | "missingUnit" | "unknownUnit" | "words" | "multiplication" | "iso8601" | "unexpected" | "ambiguousClock" | "clockFormat" | "unitOrder" | "duplicateUnit" | "overflow60" | "decimalInCompound" | "decimalPrime" | "bareNumber" | "reversedRange" | "emptyRange" | "ambiguousRange";
|
|
749
|
+
type DurationResult = {
|
|
750
|
+
ok: true;
|
|
751
|
+
/** The duration the schedule uses: the middle of a range. */
|
|
752
|
+
minutes: number;
|
|
753
|
+
range?: {
|
|
754
|
+
min: number;
|
|
755
|
+
max: number;
|
|
756
|
+
};
|
|
757
|
+
/** One side, or the two sides of a range. */
|
|
758
|
+
sides: [DurationSide] | [DurationSide, DurationSide];
|
|
759
|
+
} | {
|
|
760
|
+
ok: false;
|
|
761
|
+
reason: DurationFailure;
|
|
762
|
+
/** The word read as a unit, for `unknownUnit`. */
|
|
763
|
+
unit?: string;
|
|
764
|
+
};
|
|
765
|
+
type Failure = Extract<DurationResult, {
|
|
766
|
+
ok: false;
|
|
767
|
+
}>;
|
|
768
|
+
/**
|
|
769
|
+
* `int`: digits only (`30`). `decimal`: `1.5`, `1,5`. `fraction`: `1/2`, `½`,
|
|
770
|
+
* `1½`, `1 1/2`. Only an `int` follows an hour or a minute without a unit, or
|
|
771
|
+
* makes a clock.
|
|
772
|
+
*/
|
|
773
|
+
type NumKind = "int" | "decimal" | "fraction";
|
|
774
|
+
type Token = {
|
|
775
|
+
kind: "num";
|
|
776
|
+
value: number;
|
|
777
|
+
text: string;
|
|
778
|
+
num: NumKind;
|
|
779
|
+
space: boolean;
|
|
780
|
+
} | {
|
|
781
|
+
kind: "word";
|
|
782
|
+
text: string;
|
|
783
|
+
unit?: DurationUnit;
|
|
784
|
+
} | {
|
|
785
|
+
kind: "prime";
|
|
786
|
+
unit: "m" | "s";
|
|
787
|
+
} | {
|
|
788
|
+
kind: "colon";
|
|
789
|
+
} | {
|
|
790
|
+
kind: "plus";
|
|
791
|
+
} | {
|
|
792
|
+
kind: "dash";
|
|
793
|
+
} | {
|
|
794
|
+
kind: "star";
|
|
795
|
+
};
|
|
796
|
+
/**
|
|
797
|
+
* Cuts a duration into tokens: the step that makes `1h30`, `1 h 30` and
|
|
798
|
+
* `1hr 30` the same sequence. A unit is any run of letters, in any script,
|
|
799
|
+
* lowercased, with a `.` right after it dropped (`hr.`, `min.`, `Std.`).
|
|
800
|
+
*/
|
|
801
|
+
declare function tokenizeDuration(text: string): {
|
|
802
|
+
ok: true;
|
|
803
|
+
tokens: Token[];
|
|
804
|
+
} | Failure;
|
|
805
|
+
/**
|
|
806
|
+
* Reads a duration as a recipe writes it, in any language Gram knows:
|
|
807
|
+
* `parseDuration("1h30")` is `{ ok: true, minutes: 90, … }`,
|
|
808
|
+
* `parseDuration("1:30")` is `{ ok: false, reason: "ambiguousClock" }`.
|
|
809
|
+
*
|
|
810
|
+
* A range keeps both sides and gives its middle as `minutes`, as the schedule
|
|
811
|
+
* uses it. No sign is read (an anchor's `-` is the caller's), and no duration
|
|
812
|
+
* is capped: that is the compiler's job.
|
|
813
|
+
*/
|
|
814
|
+
declare function parseDuration(text: string): DurationResult;
|
|
815
|
+
|
|
816
|
+
/**
|
|
817
|
+
* A numeric value as the compiled recipe stores it: a plain number, or the
|
|
818
|
+
* parser's single / fraction / range shape (structurally the parser's
|
|
819
|
+
* `QuantityValueAST`, redeclared here so this module stays free of it).
|
|
820
|
+
*/
|
|
821
|
+
type QuantityValue = {
|
|
822
|
+
type: "single";
|
|
823
|
+
value: number;
|
|
824
|
+
text?: string;
|
|
825
|
+
} | {
|
|
826
|
+
type: "fraction";
|
|
827
|
+
value: number;
|
|
828
|
+
numerator: number;
|
|
829
|
+
denominator: number;
|
|
830
|
+
text?: string;
|
|
831
|
+
} | {
|
|
832
|
+
type: "range";
|
|
833
|
+
value: number;
|
|
834
|
+
range: {
|
|
835
|
+
min: number;
|
|
836
|
+
max: number;
|
|
837
|
+
};
|
|
838
|
+
text?: string;
|
|
839
|
+
};
|
|
840
|
+
/** The value of one term: kept in the shape it was written in. */
|
|
841
|
+
type TermValue = number | QuantityValue;
|
|
842
|
+
interface Term {
|
|
843
|
+
value: TermValue;
|
|
844
|
+
unit: string | null;
|
|
845
|
+
/** Taken away from the total (`- 2 tbsp`). */
|
|
846
|
+
minus?: boolean;
|
|
847
|
+
}
|
|
848
|
+
/** What a list of terms amounts to, in the compiled recipe's `qty` / `unit` shape. */
|
|
849
|
+
interface TermsTotal {
|
|
850
|
+
qty: TermValue;
|
|
851
|
+
unit: string | null;
|
|
852
|
+
}
|
|
853
|
+
/** Raised by `scaleTerms` when a scaled value stops being a finite number. */
|
|
854
|
+
declare class QuantityOverflowError extends RangeError {
|
|
855
|
+
readonly factor: number;
|
|
856
|
+
constructor(factor: number);
|
|
857
|
+
}
|
|
858
|
+
/**
|
|
859
|
+
* Rounds a mass/quantity value to 2 decimal places, returning a `number`
|
|
860
|
+
* (not a string). Centralizes the `parseFloat(x.toFixed(2))` idiom used
|
|
861
|
+
* throughout kitchen/analyzer so there is a single, documented rounding rule
|
|
862
|
+
* to port when the compiler is reimplemented in another language: `toFixed`
|
|
863
|
+
* uses round-half-away-from-zero on the value's shortest decimal
|
|
864
|
+
* representation, which differs from IEEE round-half-to-even on exact ties.
|
|
865
|
+
*/
|
|
866
|
+
declare const round2: (value: number) => number;
|
|
867
|
+
/**
|
|
868
|
+
* Rounds a stored quantity or mass like `round2`, but never to fewer than 2
|
|
869
|
+
* significant digits: `1.234` → `1.23` and `0.333` → `0.33` as before, but
|
|
870
|
+
* `0.0047` stays `0.0047` instead of becoming `0`. Rounded to 2 decimals in
|
|
871
|
+
* the author's unit, a recipe divided by 10 lost its `0.02 kg` of salt, and
|
|
872
|
+
* a ratio of a pinch weighed `0 g` (#230). The views round what they show
|
|
873
|
+
* (`formatAmount`).
|
|
874
|
+
*/
|
|
875
|
+
declare const roundQuantity: (value: number) => number;
|
|
876
|
+
/** True for a value a term can hold (a number, or a single / fraction / range). */
|
|
877
|
+
declare function isTermValue(value: unknown): value is TermValue;
|
|
878
|
+
/**
|
|
879
|
+
* The number a value stands for: the number itself, or its `value` (the
|
|
880
|
+
* middle of a range). `null` when the value carries no number.
|
|
881
|
+
*/
|
|
882
|
+
declare function termValueNumber(value: TermValue): number | null;
|
|
883
|
+
/**
|
|
884
|
+
* What the terms amount to.
|
|
885
|
+
*
|
|
886
|
+
* - no term: `null`;
|
|
887
|
+
* - one term added: that term as written (a range stays a range, a fraction
|
|
888
|
+
* keeps its text);
|
|
889
|
+
* - several terms of one unit (its spellings count as one: `cup` / `cups`):
|
|
890
|
+
* their sum in that unit, never converted (`1 tasse + 1 tasse` is
|
|
891
|
+
* `2 tasses`), spelled as the first term added;
|
|
892
|
+
* - several units of one ladder (`UNIT_LADDERS`): their exact sum in the
|
|
893
|
+
* smallest unit written (`1 cup + 1 tbsp` is `17 tbsp`);
|
|
894
|
+
* - several units of one family across systems (`cup` and `ml`, `oz` and
|
|
895
|
+
* `g`): their sum in grams or milliliters, rounded to 2 decimals;
|
|
896
|
+
* - otherwise (`cup` and `g`, `gousse` and `pièce`, a term with no unit next
|
|
897
|
+
* to one with a unit): `null`, the terms do not add up to one amount.
|
|
898
|
+
*
|
|
899
|
+
* A range is added by its bounds (`2-3 g + 200 g` is `202-203 g`): a term
|
|
900
|
+
* taken away removes its highest number from the lowest bound and its lowest
|
|
901
|
+
* number from the highest one. A total with a range in it stays a range.
|
|
902
|
+
*/
|
|
903
|
+
declare function termsTotal(terms: readonly Term[]): TermsTotal | null;
|
|
904
|
+
/**
|
|
905
|
+
* How terms are grouped (`mergeKey`): by unit, by ladder of units (`cup` and
|
|
906
|
+
* `tbsp`), or by family, the kind of amount a unit measures (`familyOf`:
|
|
907
|
+
* every mass together, every volume together).
|
|
908
|
+
*/
|
|
909
|
+
type MergeMode = "unit" | "ladder" | "family";
|
|
910
|
+
/**
|
|
911
|
+
* The kind of amount a unit measures, for telling the families of a sum
|
|
912
|
+
* apart: a mass, a volume, or (a unit Gram cannot convert, `gousse`) that
|
|
913
|
+
* unit itself.
|
|
914
|
+
*/
|
|
915
|
+
declare function familyOf(unit: string | null): string;
|
|
916
|
+
/**
|
|
917
|
+
* The key `mergeTerms` groups a term's unit under: its family in `"family"`
|
|
918
|
+
* mode (`familyOf`), its ladder in `"ladder"` mode (`cup` and `tbsp`, `g`
|
|
919
|
+
* and `kg`), otherwise the unit itself, its spellings counted as one (`cup`
|
|
920
|
+
* / `cups`). A unit Gram does not know (`gousse`) is only lowercased:
|
|
921
|
+
* `gousse` and `gousses` stay two units.
|
|
922
|
+
*/
|
|
923
|
+
declare function mergeKey(unit: string | null, mode: MergeMode): string;
|
|
924
|
+
/** The terms grouped by `mergeKey`, groups in the order their first term comes. */
|
|
925
|
+
declare function groupTerms(terms: readonly Term[], mode: MergeMode): Term[][];
|
|
926
|
+
/**
|
|
927
|
+
* Puts the terms of several amounts of one ingredient together, terms added
|
|
928
|
+
* before terms taken away (`2 tbsp` then `1 cup - 4 tbsp` gives
|
|
929
|
+
* `1 cup - 2 tbsp`, never a term taken away first).
|
|
930
|
+
*
|
|
931
|
+
* - `"unit"` adds up the terms of each unit into one, its spellings counted
|
|
932
|
+
* as one (`100 g` and `100 g` give `200 g`); two units stay apart, even on
|
|
933
|
+
* one ladder (`1 cup`, `2 tbsp`): this is how a section lists an
|
|
934
|
+
* ingredient it uses several times.
|
|
935
|
+
* - `"ladder"` adds up the terms of each ladder into one, in the smallest
|
|
936
|
+
* unit written (`1 cup`, `2 tbsp` and `- 4 tbsp` give `14 tbsp`, see
|
|
937
|
+
* `termsTotal`), and the terms of each unit on no ladder into one; two
|
|
938
|
+
* systems (`cup` and `ml`) or two families stay apart.
|
|
939
|
+
*
|
|
940
|
+
* Each result keeps the place of the first term it adds up; a negative
|
|
941
|
+
* result is a term taken away, a result of zero is left out (unless nothing
|
|
942
|
+
* else is left). A lone term stays as written.
|
|
943
|
+
*/
|
|
944
|
+
declare function mergeTerms(terms: readonly Term[], mode: MergeMode): Term[];
|
|
945
|
+
/**
|
|
946
|
+
* Multiplies a value by `factor`, rounded to 2 decimals. The source text of a
|
|
947
|
+
* value (`text`, a fraction's `numerator` / `denominator`) only describes the
|
|
948
|
+
* unscaled value, so it is dropped: a scaled fraction becomes a single value.
|
|
949
|
+
* A value that is not a number (a malformed object) comes back untouched.
|
|
950
|
+
* Throws `QuantityOverflowError` when the product is no longer finite.
|
|
951
|
+
*/
|
|
952
|
+
declare function scaleTermValue<T extends TermValue>(value: T, factor: number): TermValue;
|
|
953
|
+
/** Every term multiplied by `factor` (see `scaleTermValue`); units are kept. */
|
|
954
|
+
declare function scaleTerms(terms: readonly Term[], factor: number): Term[];
|
|
955
|
+
/** One term as written: its number (or source text) and its unit, without its sign. */
|
|
956
|
+
declare function formatTerm(term: Term): string;
|
|
957
|
+
interface FormatTermsOptions {
|
|
958
|
+
/** Placed between two terms added. Default ` + `. */
|
|
959
|
+
plus?: string;
|
|
960
|
+
/** Placed before a term taken away. Default ` − `. */
|
|
961
|
+
minus?: string;
|
|
962
|
+
/**
|
|
963
|
+
* `"written"` (default): the terms as the author wrote them.
|
|
964
|
+
* `"computed"`: an amount Gram worked out (scaled, or added up from
|
|
965
|
+
* several occurrences), written the way a cook measures it (see
|
|
966
|
+
* `formatTerms`).
|
|
967
|
+
*/
|
|
968
|
+
mode?: "written" | "computed";
|
|
969
|
+
/** The reader's language: decimals, and the spelling of a unit Gram brings in. */
|
|
970
|
+
lang?: string;
|
|
971
|
+
/**
|
|
972
|
+
* Writes a number next to its unit. Default: the number as it is in
|
|
973
|
+
* `"written"` mode; in `"computed"` mode a whole number, a kitchen
|
|
974
|
+
* fraction for a spoon or an imperial unit (`1 1/2`), otherwise a
|
|
975
|
+
* decimal in the reader's language.
|
|
976
|
+
*/
|
|
977
|
+
number?: (value: number, unit: string | null) => string;
|
|
978
|
+
/** Writes a value's source text (`1/2`, `2.5-3`). Default: as it is. */
|
|
979
|
+
text?: (text: string) => string;
|
|
980
|
+
/**
|
|
981
|
+
* `"computed"` only: an amount the reader buys (a shopping list). A
|
|
982
|
+
* metric amount reaches the larger unit (`1500 g` is `1.5 kg`), and a
|
|
983
|
+
* spoon or imperial amount is recomposed from the top of its scale
|
|
984
|
+
* (`34 tbsp` is `2 cup + 2 tbsp`) once it reaches one of a unit at least
|
|
985
|
+
* four times larger than its own (`3 tsp` stays `3 tsp`).
|
|
986
|
+
*/
|
|
987
|
+
buying?: boolean;
|
|
988
|
+
/**
|
|
989
|
+
* `"computed"` only, default `true`: a recomposition may round its last
|
|
990
|
+
* term to what its unit measures (a scaled amount was no exact measure
|
|
991
|
+
* anyway: `1.1 cup` is `1 cup + 1 tbsp + 2 tsp`). `false` writes an
|
|
992
|
+
* amount that does not recompose exactly as it is (`1.6 cup`).
|
|
993
|
+
*/
|
|
994
|
+
rounding?: boolean;
|
|
995
|
+
}
|
|
996
|
+
/**
|
|
997
|
+
* The terms as text, in their written order (`1 cup + 1 tbsp`,
|
|
998
|
+
* `1 cup − 2 tbsp + 30 g`); a list that would start with a term taken away
|
|
999
|
+
* writes the terms added first (`1 cup − 2 tbsp`, never `−2 tbsp + 1 cup`).
|
|
1000
|
+
*
|
|
1001
|
+
* `"written"` mode (the default) writes each term as the author wrote it.
|
|
1002
|
+
* `"computed"` mode writes an amount Gram worked out, ladder by ladder (two
|
|
1003
|
+
* systems stay apart, term by term):
|
|
1004
|
+
*
|
|
1005
|
+
* - a spoon, cup or imperial amount is recomposed the way a cook measures
|
|
1006
|
+
* it: one amount of the largest unit written when that unit measures it
|
|
1007
|
+
* (`MEASURED_FRACTIONS`: `1 1/2 cup`, never `2 1/8 cup`), the terms as they
|
|
1008
|
+
* are when each is measurable, otherwise whole units then the rest in the
|
|
1009
|
+
* next unit down (`cup`, `tbsp`, `tsp`; `gal`, `qt`, `pt`, `fl oz`; `lb`,
|
|
1010
|
+
* `oz`), never above the largest unit written, three terms at most;
|
|
1011
|
+
* - a metric amount is one decimal amount in the largest unit written
|
|
1012
|
+
* (`1 kg + 200 g` doubled is `2.4 kg`; `800 g + 200 g` is `1000 g`, never
|
|
1013
|
+
* `1 kg`, unless `buying`);
|
|
1014
|
+
* - a range shares what both bounds have in common and puts the range on
|
|
1015
|
+
* the last term (`2 cup + 2-4 tbsp`), otherwise writes each bound in full;
|
|
1016
|
+
* - a unit on no ladder adds up with itself only (`2 gousses`).
|
|
1017
|
+
*/
|
|
1018
|
+
declare function formatTerms(terms: readonly Term[], options?: FormatTermsOptions): string;
|
|
1019
|
+
|
|
1020
|
+
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, amountDecimals, commonFraction, compileDictionary, convertUnitInFamily, decimalSeparator, familyOf, fillTemplate, formatAmount, formatNumber, formatTerm, formatTerms, getAiLanguageInstruction, getCategoryLabels, getDefaultCategories, getDictionary, groupTerms, isCategoryKey, isCoarseUnit, isFractionUnit, isMeasureUnit, isMetricMassUnit, isTermValue, ladderOf, localizeDecimals, looksLikeThousands, mergeKey, mergeTerms, normalizeUnit, parseDuration, resolveTimeUnit, round2, roundAmount, roundQuantity, sameCountUnit, sameLadder, scaleTermValue, scaleTerms, termValueNumber, termsTotal, toKitchenFraction, toLargerMetricUnit, tokenizeDuration, unitContainsQuantity, unitKey, unitSpelling };
|