latte 3.1.4

Author: dg

latte/cs/custom-tags.texy

@@ -160,7 +160,7 @@ Když Latte narazí na `{datetime}` v šabloně, zavolá parsovací funkci `crea
 
 Metoda `print()` generuje PHP kód, který bude spuštěn při vykreslování šablony. Voláme metodu `$context->format()`, která sestavuje výsledný řetězec PHP kódu pro kompilovanou šablonu. První argument, `'echo date('Y-m-d H:i:s') %line;'`, je maska, do které jsou doplněny následující parametry. Zástupný symbol `%line` říká metodě `format()`, aby použila druhý argument, kterým je `$this->position`, a vložila komentář jako `/* line 15 */`, který propojuje vygenerovaný PHP kód zpět na původní řádek šablony, což je klíčové pro ladění.
 
-Vlastnost `$this->position` je zděděna ze základní třídy `Node` a je automaticky nastavena parserem Latte. Obsahuje objekt [api:Latte\Compiler\Position], který indikuje, kde byl tag nalezen ve zdrojovém souboru `.latte`.
+Vlastnost `$this->position` je zděděna ze základní třídy `Node` a je automaticky nastavena parserem Latte. Obsahuje objekt [api:Latte\Compiler\Range] (potomek třídy `Position` rozšířený o vlastnost `length` v bajtech), který udává, kde se tag v souboru `.latte` nachází. U párových tagů pokrývá rozsah od otevíracího po uzavírací tag a potomci `StatementNode` navíc nabízejí pole `$this->tagRanges` s objekty `Range` pro každý dílčí tag (otevírací, mezilehlé jako `{else}`/`{case}` i uzavírací).
 
 Metoda `getIterator()` je zásadní pro kompilační průchody. Musí poskytovat všechny dětské uzly, ale náš jednoduchý `DatetimeNode` aktuálně nemá žádné argumenty ani obsah, tedy žádné dětské uzly. Nicméně metoda musí stále existovat a být generátorem, tj. klíčové slovo `yield` musí být nějakým způsobem přítomno v těle metody.
 
@@ -1003,7 +1003,7 @@ Zástupné symboly `PrintContext::format()`
 - **`%args`**: Argument musí být `Expression\ArrayNode`. Vypíše položky pole formátované jako argumenty pro volání funkce nebo metody (oddělené čárkami, zpracovává pojmenované argumenty, pokud jsou přítomny).
 	- `$argsNode = new ArrayNode([...]);`
 	- `$context->format('myFunc(%args);', $argsNode)` -> `myFunc(1, name: 'Joe');`
-- **`%line`**: Argument musí být objekt `Position` (obvykle `$this->position`). Vkládá PHP komentář `/* line X */` indikující číslo řádku zdroje.
+- **`%line`**: Argument musí být objekt `Position` (nebo `Range`, obvykle `$this->position`). Vkládá PHP komentář `/* line X */` indikující číslo řádku zdroje.
 	- `$context->format('echo "Hi" %line;', $this->position)` -> `echo "Hi" /* line 42:1 */;`
 - **`%escape(...)`**: Generuje PHP kód, který *za běhu* escapuje vnitřní výraz pomocí aktuálních kontextově uvědomělých pravidel escapování.
 	- `$context->format('echo %escape(%node);', $variableNode)`

latte/cs/filters.texy

@@ -12,6 +12,7 @@ V šablonách můžeme používat funkce, které pomáhají upravit nebo přefor
 | `clamp`      | [ohraničí hodnotu do daného rozsahu |#clamp]
 | `column`     | [extrahuje jeden sloupec z pole |#column]
 | `commas`     | [spojí pole čárkami |#commas]
+| `limit`      | [omezí délku pole, řetězce nebo iterátoru |#limit]
 | `dataStream` | [konverze pro Data URI protokol |#dataStream]
 | `date`       | [formátuje datum a čas |#date]
 | `explode`    | [rozdělí řetězec na pole podle oddělovače |#explode]
@@ -812,6 +813,21 @@ Pokud je zadaný parametr length a je kladný, posloupnost bude obsahovat tolik
 
 Ve výchozím nastavení filtr změní pořadí a resetuje celočíselného klíče pole. Toto chování lze změnit nastavením preserveKeys na true. Řetězcové klíče jsou vždy zachovány, bez ohledu na tento parametr.
 
+Viz také [#limit].
+
+
+limit(int $length) .[filter]{data-version:3.1.3}
+------------------------------------------------
+Omezí délku pole, řetězce nebo iterátoru. U polí a iterátorů zachovává klíče. U řetězců respektuje UTF-8.
+
+```latte
+{foreach ($items|limit: 5) as $item}
+	...
+{/foreach}
+
+{$text|limit: 100}
+```
+
 
 sort(?Closure $comparison, string|int|\Closure|null $by=null, string|int|\Closure|bool $byKey=false) .[filter]
 --------------------------------------------------------------------------------------------------------------

latte/en/custom-tags.texy

@@ -160,7 +160,7 @@ When Latte encounters `{datetime}` in a template, it calls the tag parsing funct
 
 The `print()` method generates the PHP code that will be executed when the template is rendered. We call the `$context->format()` method, which assembles the resulting PHP code string for the compiled template. The first argument, `'echo date('Y-m-d H:i:s') %line;'`, is the mask into which the subsequent parameters are substituted. The `%line` placeholder tells the `format()` method to take the second following argument, which is `$this->position`, and inserts a comment like `/* line 15 */` that links the generated PHP code back to the original template line, which is crucial for debugging.
 
-Property `$this->position` is inherited from the base `Node` class, and is automatically set by Latte's parser. It holds a [api:Latte\Compiler\Position] object indicating where the tag was found in the source `.latte` file.
+Property `$this->position` is inherited from the base `Node` class, and is automatically set by Latte's parser. It holds a [api:Latte\Compiler\Range] object (a subclass of `Position` extended with a `length` in bytes) indicating where the tag is located in the source `.latte` file. For paired tags the range spans from the opening to the closing tag, and `StatementNode` descendants additionally expose `$this->tagRanges` listing the `Range` of every constituent tag (opening, intermediate like `{else}`/`{case}`, and closing).
 
 The `getIterator()` method is vital for compiler passes. It must yield all child nodes, but our simple `DatetimeNode` currently has no arguments or content, thus no child nodes. However, the method must still exist and be a generator, i.e. the `yield` keyword must be somehow present in the method body.
 
@@ -1003,7 +1003,7 @@ We've frequently used `PrintContext::format()` to generate PHP code in the `prin
 - **`%args`**: Argument must be an `Expression\ArrayNode`. It prints the array items formatted as arguments for a function or method call (comma-separated, handling named arguments if present).
 	- `$argsNode = new ArrayNode([...]);`
 	- `$context->format('myFunc(%args);', $argsNode)` -> `myFunc(1, name: 'Joe');`
-- **`%line`**: Argument must be a `Position` object (usually `$this->position`). It inserts a PHP comment `/* line X */` indicating the source line number.
+- **`%line`**: Argument must be a `Position` (or `Range`) object (usually `$this->position`). It inserts a PHP comment `/* line X */` indicating the source line number.
 	- `$context->format('echo "Hi" %line;', $this->position)` -> `echo "Hi" /* line 42:1 */;`
 - **`%escape(...)`**: It generates PHP code that, *at runtime*, will escape the inner expression using the current context-aware escaping rules.
 	- `$context->format('echo %escape(%node);', $variableNode)`

latte/en/filters.texy

@@ -12,6 +12,7 @@ In templates, we can use functions that help modify or reformat data into its fi
 | `clamp`      | [clamps a value to the given range |#clamp]
 | `column`     | [extracts a single column from an array |#column]
 | `commas`     | [joins an array with commas |#commas]
+| `limit`      | [limits the length of an array, string, or iterator |#limit]
 | `dataStream` | [Data URI protocol conversion |#dataStream]
 | `date`       | [formats the date and time |#date]
 | `explode`    | [splits a string into an array by a delimiter |#explode]
@@ -812,6 +813,21 @@ If `length` is given and is positive, then the sequence will have up to that man
 
 By default, the filter reorders and resets the integer array keys. This behavior can be changed by setting `preserveKeys` to true. String keys are always preserved, regardless of this parameter.
 
+See also [#limit].
+
+
+limit(int $length) .[filter]{data-version:3.1.3}
+------------------------------------------------
+Limits the length of an array, string, or iterator. For arrays and iterators, keys are preserved. For strings, it respects UTF-8.
+
+```latte
+{foreach ($items|limit: 5) as $item}
+	...
+{/foreach}
+
+{$text|limit: 100}
+```
+
 
 sort(?Closure $comparison, string|int|\Closure|null $by=null, string|int|\Closure|bool $byKey=false) .[filter]
 --------------------------------------------------------------------------------------------------------------