RosaeNLG

https://rosaenlg.org/rosaenlg/4.4.0/
Admin
RosaeNLG is a Natural Language Generation (NLG) library for Node.js or client-side execution, based...
Tokens:58,848
Snippets:439
Trust Score:7.1
Update:1 year ago
Show doc for...
Tokens:
Raw
### Initialize Node.js Project and Install RosaeNLG

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_de_DE

Sets up a new Node.js project, initializes it with npm, and installs the RosaeNLG library. This is a standard procedure for any Node.js project requiring external packages.

```bash
npm init
npm install rosaenlg
```

--------------------------------

### Dockerfile for RosaeNLG Server Deployment (Dockerfile)

Source: https://rosaenlg.org/rosaenlg/4.4.0/dev_experience

This multi-stage Dockerfile builds a RosaeNLG server image. The first stage prepares the application by installing dependencies and packaging templates. The second stage creates a lean final image containing only the necessary files for the server to run, copying the packaged templates into the correct directory and renaming them for server access.

```dockerfile
FROM rosaenlg/server:3.2.0
COPY package.json /
COPY package-lock.json /
RUN npm i
COPY ./ / 
RUN npx gulp package

FROM rosaenlg/server:3.2.0
ENV ROSAENLG_HOMEDIR=/templates
RUN mkdir /templates
COPY --from=0 /dist/ ./templates/
RUN cd /templates && for i in *.json; do mv $i "DEFAULT_USER#$i";done && cd -
```

--------------------------------

### Install rosaenlg-countries npm package

Source: https://rosaenlg.org/rosaenlg/4.4.0/libs/libs

This command installs the rosaenlg-countries library, which provides country-related data and functions for RosaeNLG. Ensure you have Node.js and npm installed.

```bash
npm install rosaenlg-countries
```

--------------------------------

### Install and Run RosaeNLG Server with npm

Source: https://rosaenlg.org/rosaenlg/4.4.0/integration/node-server

This snippet demonstrates the steps to initialize a new Node.js project, install the RosaeNLG server package, and run the server using npm. It's a straightforward method for local development and testing.

```bash
mkdir my-rosaenlg-server
cd my-rosaenlg-server
npm init --yes
npm install rosaenlg-node-server
npx rosaenlg-server
```

--------------------------------

### Install rosaenlg-packager using npm

Source: https://rosaenlg.org/rosaenlg/4.4.0/integration/rosaenlg_packager

This command installs the rosaenlg-packager package, which is necessary for using the RosaeNLG compilation and packaging tools. Ensure you have Node.js and npm installed.

```bash
npm install rosaenlg-packager
```

--------------------------------

### Docker Deployment

Source: https://rosaenlg.org/rosaenlg/4.4.0/dev_experience

Instructions for deploying RosaeNLG as a Docker container and managing templates.

```APIDOC
## Docker Deployment

### Description
This section details how to deploy RosaeNLG using Docker, including building a custom image with your templates.

### Running the RosaeNLG Server Docker Image
To start a basic RosaeNLG server accessible on port 80 (forwarded from the container's port 5000):
```bash
docker run -p 80:5000 -i rosaenlg/server:latest
```

### Building a Custom Docker Image with Packaged Templates
This multi-stage Docker build process packages your project and copies the compiled templates into a RosaeNLG server image.

```dockerfile
# First stage: Build the packaged templates
FROM rosaenlg/server:3.2.0
COPY package.json / 
COPY package-lock.json / 
RUN npm i 
COPY ./ / 
RUN npx gulp package

# Second stage: Create the final image with the server and packaged templates
FROM rosaenlg/server:3.2.0
ENV ROSAENLG_HOMEDIR=/templates
RUN mkdir /templates
COPY --from=0 /dist/ ./templates/
RUN cd /templates && for i in *.json; do mv $i "DEFAULT_USER#$i";done && cd -
```

**Note:** Replace `3.2.0` with the desired RosaeNLG server version.
```

--------------------------------

### Template Deployment API

Source: https://rosaenlg.org/rosaenlg/4.4.0/dev_experience

This API allows you to push your packaged RosaeNLG templates to the server for deployment.

```APIDOC
## POST /templates

### Description
Upload a packaged RosaeNLG template to the server.

### Method
POST

### Endpoint
/templates

### Parameters
#### Request Body
- **templateFile** (file) - Required - The packaged RosaeNLG template file (usually a JSON file).

### Request Example
(Example would typically involve multipart/form-data for file uploads, but is omitted here for brevity as it's a file upload)

### Response
#### Success Response (200)
- **templateId** (string) - A unique identifier for the uploaded template.
- **sha1** (string) - The SHA1 hash of the uploaded template, used for rendering.

#### Response Example
{
  "templateId": "uniqueTemplateId",
  "sha1": "a1b2c3d4e5f67890abcdef1234567890abcdef12"
}
```

--------------------------------

### Rosaenlg: Generating Diverse Introduction Texts

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_en_US

This example showcases the `synz` and `syn` mixins in Rosaenlg for creating varied introduction texts. It defines an 'intro' mixin with multiple synonymous sentences about a phone, allowing for random selection.

```pug
mixin intro
  synz
    syn
      | the #{phone.name} is really a fantastic phone.
    syn
      | i really love the new #{phone.name}.
    syn
      | #{phone.name} : a great phone !
```

--------------------------------

### Example Render Request for RosaeNLG API (JSON)

Source: https://rosaenlg.org/rosaenlg/4.4.0/dev_experience

This JSON object represents a sample request payload for rendering texts using the RosaeNLG API. It specifies the desired language and provides an array of phone objects with their attributes, which will be used by the template to generate the output.

```json
{
    "language": "en_US",
    "phones": [
        {
            "name": "OnePlus 35T",
            "colors": [
                "White"
            ],
            "displaySize": 6,
            "screenRatio": 99,
            "battery": 5500
        }
    ]
}
```

--------------------------------

### RosaeNLG English - Paragraph Assembly

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/example_en_US

Assembles the generated text into paragraphs using the `itemz` block in RosaeNLG. It combines the output of the `queenInfo`, `succession`, and `crownJewels` mixins into a structured narrative.

```javascript
itemz {mode: 'paragraphs', separator: '.'}
  item
    | #[+queenInfo]
  item
    | #[+succession]
  item
    | #[+crownJewels]
```

--------------------------------

### Combining Introduction and Color Mixins for Phone Descriptions (Pug)

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_de_DE

This example combines previously defined mixins (`intro` and `colors`) into a new mixin `printPhone` to generate a complete sentence describing a phone. It then iterates through a list of phones, calling `printPhone` for each.

```pug
mixin printPhone
  | #[+intro] .
  | #[+colors] .

- let phone;
each phoneElt in phones
  - phone = phoneElt;
  p #[+printPhone]
```

--------------------------------

### Begin Sentences with General Text in RosaeNLG

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_de_DE

This example illustrates how to prepend a general introductory phrase to a list of items using the `begin_with_general` parameter within RosaeNLG's `itemz` structure. This ensures consistent sentence beginnings, especially when the list might be empty.

```RosaeNLG
mixin display
  itemz { begin_with_general: 'das Telefon verfügt über ein Display mit', separator:',', last_separator:'und' }
    item
      | einer physischen Größe von #[+value(phone.displaySize)] Zoll
    item
      | einem Bildschirm-zu-Körper-Verhältnis von #[+value(phone.screenRatio)]%
```

--------------------------------

### Template Rendering API

Source: https://rosaenlg.org/rosaenlg/4.4.0/dev_experience

This API enables rendering of deployed RosaeNLG templates with specified data and language.

```APIDOC
## POST /templates/{templateId}/{templateSha1}/render

### Description
Render a specific version of a deployed RosaeNLG template with provided data.

### Method
POST

### Endpoint
/templates/{templateId}/{templateSha1}/render

### Parameters
#### Path Parameters
- **templateId** (string) - Required - The unique identifier of the template.
- **templateSha1** (string) - Required - The SHA1 hash of the specific template version to render.

#### Request Body
- **language** (string) - Required - The language code for rendering (e.g., "en_US", "fr_FR").
- **jsonData** (object) - Optional - The data to be used for rendering the template. The structure should match the expected data for the template.

### Request Example
```json
{
    "language": "en_US",
    "jsonData": {
        "phones": [
            {
                "name": "OnePlus 35T",
                "colors": [
                    "White"
                ],
                "displaySize": 6,
                "screenRatio": 99,
                "battery": 5500
            }
        ]
    }
}
```

### Response
#### Success Response (200)
- **renderedText** (string) - The rendered text output from the RosaeNLG template.

#### Response Example
(Example response would be the rendered text, e.g., "This is a rendered sentence.")
```

--------------------------------

### Rosaenlg: Iterating and Rendering Phone Descriptions

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_en_US

This example shows how to iterate through a list of phone objects in Rosaenlg and render a description for each using the 'printPhone' mixin. It sets a 'phone' variable within the loop to be used by the mixins.

```pug
- let phone;
each phoneElt in phones
  - phone = phoneElt;
  p #[+printPhone]
```

--------------------------------

### Syntactic Shortcut for Gender Lookup (RosaeNLG)

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_de_DE

Illustrates a syntactic shortcut in RosaeNLG to write a word, automatically find its gender in the dictionary, and store it. It shows examples for 'Telefon', 'Handy', and 'Gurke' with different determiners and genders.

```RosaeNLG
syn
  | das #[+value('Telefon', {represents: phone})]
syn
  | dieses #[+value('Telefon', {represents: phone})]
syn
  | das #[+value('Handy', {represents: phone})]
syn
  | die #[+value('Gurke', {represents: phone})]
syn
  | diese #[+value('Gurke', {represents: phone})]
syn
  | #{getMorF(['er', 'sie', 'es'], phone)}
```

--------------------------------

### Pug Template Example for RosaeNLG

Source: https://rosaenlg.org/rosaenlg/4.4.0/integration/java-wrapper

A sample RosaeNLG template written in Pug syntax. This template demonstrates how to use RosaeNLG's built-in functions like 'verb' and how to interpolate data passed during rendering.

```pug
p
  | il #[+verb(getAnonMS(), {verb: 'chanter', tense:'FUTUR'} )]
  | "#{chanson.nom}"
  | de #{chanson.auteur}
```

--------------------------------

### Java Template Rendering with RosaeNLG

Source: https://rosaenlg.org/rosaenlg/4.4.0/integration/java-wrapper

Example demonstrating how to compile and render a RosaeNLG template in Java. It involves creating a RosaeContext with compilation options and then using it to render the template with provided data.

```java
import org.json.JSONObject;
import org.rosaenlg.CompileOptions;
import org.rosaenlg.RosaeContext;
import java.io.File;

// ... inside a method ...

CompileOptions compileOpts = new CompileOptions();
compileOpts.setLanguage("fr_FR");

final RosaeContext rc = new RosaeContext(
    "chanson.pug",
    new File("test-templates-repo"),
    compileOpts);

JSONObject renderOpts = new JSONObject();
renderOpts.put("language", "fr_FR");
JSONObject chanson = new JSONObject();
chanson.put("nom", "Non, je ne regrette rien");
chanson.put("auteur", "Édith Piaf");
renderOpts.put("chanson", chanson);

String rendered = rc.render(renderOpts.toString());

// The 'rendered' variable will contain the output string.
// Example output: "Il chantera "Non, je ne regrette rien" d’Édith Piaf."
```

--------------------------------

### Build Executable RosaeNLG Server with pkg

Source: https://rosaenlg.org/rosaenlg/4.4.0/integration/node-server

This snippet outlines the process of building a standalone executable file for the RosaeNLG server using Vercel's pkg tool. It involves installing pkg globally, navigating to the server's package directory, and running the pkg command with specific targets for different operating systems.

```bash
npm install -g pkg
cd packages/rosaenlg-node-server
pkg package.json --targets node12-win-x64
```

--------------------------------

### Generate Varied Text with Synonyms using synz/syn (JavaScript)

Source: https://context7.com/context7/rosaenlg_rosaenlg_4_4_0/llms.txt

Demonstrates rendering a Pug template that includes synonym variations using `synz`. The example shows how multiple renders can produce different outputs due to the random selection of synonyms, adding linguistic diversity.

```javascript
const rosaenlgPug = require('rosaenlg');
for (let i = 0; i < 3; i++) {
  console.log(rosaenlgPug.renderFile('synonyms.pug', { language: 'en_US' }));
}
// Output (randomized, no repeats):
// <p>The product is remarkable.</p>
// <p>The product is excellent.</p>
// <p>The product is outstanding.</p>
```

--------------------------------

### RosaeNLG: Developer Documentation for New Languages

Source: https://rosaenlg.org/rosaenlg/4.4.0/changelog_1.x

Developer documentation has been added to guide the process of adding new languages to RosaeNLG. This aims to streamline the contribution process for language support.

```text
developer doc to add new languages
```

--------------------------------

### RosaeNLG English - Queen Information Sentences

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/example_en_US

Generates a series of sentences about the Queen using the `queenInfo` mixin in RosaeNLG. It demonstrates the use of `itemz` for sentence construction, `value` for displaying information, and `subjectVerb` for conjugating verbs.

```javascript
mixin queenInfo
  itemz {mode:'sentences', separator:'.'} 
    item
      | #[+value(QUEEN)] is the Queen of the United Kingdom,
      | #[+value(12, {'ORDINAL_TEXTUAL':true})] monarch
    item
      | #[+subjectVerb(QUEEN, {verb:'marry', tense:'PAST'})]
      | on #[+value( new Date(1947, 10, 20), {dateFormat:'d MMMM Y'} )]
    item
      | #[+subjectVerb(QUEEN, {verb:'refuse', tense:'PERFECT_PRESENT'})] to name a heir
    item
      | Rumors say that #[+subjectVerb(QUEEN, {verb:'plan', tense:'PROGRESSIVE_PRESENT'})] to step down in 2021
```

--------------------------------

### Render Pug Template with Docker CLI

Source: https://rosaenlg.org/rosaenlg/4.4.0/integration/docker-cli

Renders a simple Pug template using the RosaeNLG Docker CLI. This example assumes a local 'fruits.pug' file without includes. It pipes the template content to the Docker container and specifies the language.

```pug
- var data = ['apples', 'bananas', 'apricots', 'pears'];
p
  eachz fruit in data with { separator: ',', last_separator: 'and', begin_with_general: 'I love', end:'!' }
    | #{fruit}

```

```bash
cat fruits.pug | docker run -i rosaenlg/cli:latest -l en_US
```

--------------------------------

### Using Synonyms for Text Variation (Pug)

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_de_DE

This example shows how to use the `syn` mixin in Pug to introduce word variations, making the generated text less repetitive. It replaces a fixed word with one chosen randomly from a list of synonyms.

```pug
mixin colors
  | die verfügbaren #[+syn('Farben', 'Farbtöne', 'Töne')]
  | des Telefons sind
  ...
```

--------------------------------

### RosaeNLG English - Crown Jewels List Generation

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/example_en_US

Generates a sentence describing the Crown Jewels using a RosaeNLG mixin `crownJewels`. It iterates through a list of items, formatting their names and quantities. Dependencies include the `value` and `valueToSorP` functions.

```javascript
mixin crownJewels
  - 
    const crownStuff = [
      ['sword', 6],
      ['orb', 2],
      ['trumpet', 16],
      ['ampulla', 1],
      ['armlet', 1],
    ];
  | the Crown Jewels are made up of 142 objects, for example
  - setWordData('armlet', {aan: 'an'});
  eachz stuff in crownStuff with {separator: ',', last_separator: ', plus', end: '!'}
    - 
      const name = stuff[0];
      const num = stuff[1];
    if num > 1
      | #[+value(num, {'TEXTUAL':true })]
    else
      | a
    | #[+value(name, {number: valueToSorP(num)})]
```

--------------------------------

### Italian Verb Conjugation Example (RosaeNLG)

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/verbs_italian

Demonstrates how to conjugate Italian verbs using RosaeNLG. It shows basic conjugation and compound tenses, including specifying auxiliary verbs and participle agreement. Requires the RosaeNLG library.

```text
#[+verb(getAnonMS(), 'mangiare')]
#[+verb(getAnonMP(), {verb:'mangiare', aux:'AVERE', tense:'TRAPASSATO_REMOTO'})]
```

--------------------------------

### Generate Multiple Sentences with `eachz` Assembly Parameters (JavaScript)

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/eachz_itemz

Demonstrates generating multiple sentences from a list using `eachz`. This example utilizes parameters like `mode: 'sentences'`, `begin_with_general` (as an array for varied beginnings), `begin_last`, and `begin_last_1` to control sentence construction.

```pug
eachz elt in ['A', 'B', 'C', 'D', 'E'] with
  mode: 'sentences'
  begin_with_general: ['First, ', 'Second, ', 'As well, ']
  begin_last: 'At last, '
  begin_last_1: 'Finally, '
  = elt
```

--------------------------------

### RosaeNLG English - Succession List Generation

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/example_en_US

Generates a sentence listing the line of succession using the `succession` mixin in RosaeNLG. It utilizes `thirdPossession` for possessive pronouns and `eachz` to iterate through a list, formatting each successor with their ordinal number.

```javascript
mixin succession
  - 
    const successors = [
      'Charles, Prince of Wales',
      'Prince William, Duke of Cambridge',
      'Prince George of Cambridge',
    ];
  | #[+thirdPossession(QUEEN, 'line')] of succession includes
  eachz successor in successors with {separator:',', last_separator: 'and'}
    | #[+value(successor)]
    | (
    | #[+value(successors.indexOf(successor)+1, {ORDINAL_NUMBER:true})]
    | )
```

--------------------------------

### Set 'a/an' Article for English Adjective

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/dict

Example of using `setAdjData` to specify the correct indefinite article ('a' or 'an') for an English adjective. This is useful for adjectives starting with vowels.

```javascript
setAdjData('intelligent', {aan: 'a'})
```

--------------------------------

### Generate Introductory Phrases for a Phone (RosaeNLG)

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_en_US

The `intro` mixin provides several ways to introduce a phone using RosaeNLG's `synz` and `syn` tags for variations. These variations allow the generated text to describe the phone as fantastic, loved, or simply a great product.

```RosaeNLG
mixin intro
  synz
    syn
      | the #[+value(phone)] is really a fantastic phone.
    syn
      | i really love the new #[+value(phone)].
    syn
      | #[+value(phone)] : a great phone !
```

--------------------------------

### Set 'h aspiré' for French Word

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/dict

Example of using `setWordData` to indicate if a French word starts with an 'h aspiré' (aspirated h). This affects elision and article usage.

```javascript
setWordData('hérisson', {contracts: true})
```

--------------------------------

### Generate Phone Display Description (RosaeNLG)

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_en_US

Defines the `itHasADisplay` mixin to start a sentence about the phone's display and the `display` mixin which structures the display information using `itemz`. This allows for a list of display characteristics like physical size and screen-to-body ratio, separated by commas and 'and'.

```RosaeNLG
mixin itHasADisplay
  | #[+value(phone)] has a display with

mixin display
  itemz { begin_with_general: itHasADisplay, separator:',', last_separator:'and', mix:true }
    item
      | a physical size of #[+value(phone.displaySize)] inches
    item
      | a screen-to-body ratio of #[+value(phone.screenRatio)] %
```

--------------------------------

### Rosaenlg Mixin for Introduction Synonyms

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_en_US

This Rosaenlg mixin provides several variations for introducing a phone, using 'synz' to select one of the predefined phrases randomly or sequentially. This adds variety to the generated text.

```rosaenlg
mixin intro
  synz
    syn
      | the #[+value(phone)] is really a fantastic phone.
    syn
      | i really love the new #[+value(phone)].
    syn
      | #[+value(phone)] : a great phone !

```

--------------------------------

### Set 'h aspiré' for French Adjective

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/dict

Example of using `setAdjData` to specify whether a French adjective starts with an 'h aspiré'. This impacts how definite and indefinite articles are used before the adjective.

```javascript
setAdjData('horrible', {contracts: false})
```

--------------------------------

### Browser IDE Demo Enhancements

Source: https://rosaenlg.org/rosaenlg/4.4.0/changelog_1.x

The `browser-ide-demo` has received several usability improvements. It now displays a warning when attempting to load an example with unsaved code changes and defaults to auto-rendering. It also features a new sidebar and is built upon a clean Vue project structure.

```text
`browser-ide-demo`:
    * warning when load example while code has changed
    * auto render by default
```

```text
`browser-ide-demo`
    * added sidebar
    * now based on a clean Vue project
```

--------------------------------

### Real-time Template Rendering with RosaeNLG CLI (Bash)

Source: https://rosaenlg.org/rosaenlg/4.4.0/dev_experience

This command uses the RosaeNLG CLI to watch for changes in a specified template file (templates/phoneCli.pug) and render it in real time. It supports specifying the language locale (fr_FR). This is useful for quick feedback during development.

```bash
npx rosaenlg-cli -l fr_FR -w templates\phoneCli.pug
```

--------------------------------

### Render Pug Template with RosaeNLG in JavaScript

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_fr_FR

This JavaScript code snippet demonstrates how to use the RosaeNLG library to render a Pug template. It defines an array of phone objects and then uses `rosaenlgPug.renderFile` to process the 'tuto.pug' template with the provided data and language settings. The output is then logged to the console.

```javascript
const rosaenlgPug = require('rosaenlg');
let phones = [
  {
    name: 'OnePlus 5T',
    colors: ['Black', 'Red', 'White'],
    displaySize: 6,
    screenRatio: 80.43,
    battery: 3300,
  },
  {
    name: 'OnePlus 5',
    colors: ['Gold', 'Gray'],
    displaySize: 5.5,
    screenRatio: 72.93,
    battery: 3300,
  },
  {
    name: 'OnePlus 3T',
    colors: ['Black', 'Gold', 'Gray'],
    displaySize: 5.5,
    screenRatio: 73.15,
    battery: 3400,
  },
];
const res = rosaenlgPug.renderFile('tuto.pug', {
  language: 'fr_FR',
  phones: phones,
  cache: true,
});
console.log(res);
```

--------------------------------

### Conjugate French Verbs with Rosaenlg

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/verbs_french

Demonstrates the basic conjugation of French verbs using the `verb` function in Rosaenlg. It shows how to specify the verb and tense, with examples for simple conjugation and handling pronominal verbs.

```NLG
ils #[+verb(subjMP, 'oindre')]
elles #[+verb(getAnonFP(), {verb: 'sortir', tense:'PASSE_COMPOSE', aux:'ETRE', agree: getAnonFP()})]
elles #[+verb(getAnonFP(), {verb: 'sortir', tense:'PASSE_COMPOSE', aux:'AVOIR'})] la poubelle
ils #[+verb(getAnonMP(), {verb: 'immerger', tense:'IMPARFAIT', pronominal:true})]
```

--------------------------------

### Randomize List Item Order in RosaeNLG

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_de_DE

This example demonstrates how to randomize the order of items within a list using the `mix:true` parameter in RosaeNLG's `itemz` structure. This enhances text variety by shuffling the sequence of displayed properties.

```RosaeNLG
itemz { begin_with_general: 'das Telefon verfügt über ein Display mit', separator:',', last_separator:'und', mix:true }
```

--------------------------------

### Rosaenlg: Combining Introduction and Detail Mixins

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_en_US

This snippet illustrates how to combine different Rosaenlg mixins to generate complete sentences. The 'printPhone' mixin calls both the 'intro' and 'colors' mixins to describe a phone and its available colors.

```pug
mixin printPhone
  | #[+intro] .
  | #[+colors] .
```

--------------------------------

### Curl Example Fix and Mode Check in RosaeNLG

Source: https://rosaenlg.org/rosaenlg/4.4.0/changelog

Includes a fix for the `curl` example and adds a check for 'paragraph' mode before throwing a paragraph error. These improvements enhance the usability and robustness of RosaeNLG.

```plaintext
* `curl` example is fixed
* checking asm mode for 'paragraph' before throwing a paragraph error
```

--------------------------------

### Render RosaeNLG Template with JavaScript

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_en_US

This JavaScript code snippet utilizes the RosaeNLG library to render a Pug template file ('tuto.pug') with provided data. It defines an array of phone objects and passes them to the rendering engine, outputting the generated text to the console. Ensure RosaeNLG and its dependencies are installed.

```javascript
const rosaenlgPug = require('rosaenlg');
let phones = [
  {
    name: 'OnePlus 5T',
    colors: ['Black', 'Red', 'White'],
    displaySize: 6,
    screenRatio: 80.43,
    battery: 3300,
  },
  {
    name: 'OnePlus 5',
    colors: ['Gold', 'Gray'],
    displaySize: 5.5,
    screenRatio: 72.93,
    battery: 3300,
  },
  {
    name: 'OnePlus 3T',
    colors: ['Black', 'Gold', 'Gray'],
    displaySize: 5.5,
    screenRatio: 73.15,
    battery: 3400,
  },
];
const res = rosaenlgPug.renderFile('tuto.pug', {
  language: 'en_US',
  phones: phones,
  cache: true,
});
console.log(res);
```

--------------------------------

### Creating Diverse Introduction Texts with Synonyms (Pug)

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_de_DE

This snippet illustrates how to create multiple variations of an introductory sentence using nested `synz` and `syn` mixins. Each `syn` block contains a different introduction, and one is randomly selected during rendering.

```pug
mixin intro
  synz
    syn
      | das #{phone.name} ist wirklich ein fantastisches Telefon.
    syn
      | ich liebe das neue #{phone.name}.
    syn
      | das #{phone.name} : ein tolles Telefon !
```

--------------------------------

### French Adjective Agreement Example (RosaeNLG)

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/adjectives

Example demonstrating adjective agreement in French using `agreeAdj`. This function handles gender and number agreement automatically for French adjectives.

```RosaeNLG
luxueuses / munies
```

--------------------------------

### German Adjective Agreement Example (RosaeNLG)

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/adjectives

Example showing adjective agreement in German using `agreeAdj`. German requires specifying case and determiner for correct agreement, which can be handled by the function.

```RosaeNLG
der alten Gurke
```

--------------------------------

### Italian Adjective Agreement Example (RosaeNLG)

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/adjectives

Example demonstrating adjective agreement in Italian using `agreeAdj`. The function ensures correct gender and number agreement for Italian adjectives modifying a noun.

```RosaeNLG
la #[+agreeAdj('vecchio', 'casa')] casa
```

--------------------------------

### Include RosaeNLG Countries Library in Pug and JS

Source: https://rosaenlg.org/rosaenlg/4.4.0/libs/libs

This example demonstrates how to include the necessary Pug and JavaScript files from the rosaenlg-countries library into your RosaeNLG project. The paths may need adjustment based on your project structure.

```pug
include ../node_modules/rosaenlg-countries/dist/countries.pug
include ../node_modules/rosaenlg-countries/dist/countries_en_US.js

| #[+country({cca2: 'FR'})]
```

--------------------------------

### Pug Template for Phone Description Generation

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_fr_FR

This Pug template defines various mixins to generate descriptive text about phone specifications. It utilizes RosaeNLG's built-in functions for value formatting, synonym selection, adjective agreement, and conditional logic to create varied and natural-sounding descriptions based on phone data.

```pug
//- Copyright 2019 Ludan Stoecklé
//- SPDX-License-Identifier: Apache-2.0

//- tag::displayMixin[]
mixin display
  itemz { begin_with_general: itHasADisplay, separator:',', last_separator:'et', mix:true }
    item
      | couvre #[+value(phone.screenRatio)] % de sa surface
    item
      | fait #[+value(phone.displaySize)] pouces
//- end::displayMixin[]

//- tag::mixinItHasADisplay[]
mixin itHasADisplay
  | #[+value(phone)] a un écran qui
//- end::mixinItHasADisplay[]

//- tag::colorsMixin[]
mixin colors
  | les #[+syn('couleurs', 'teintes', 'finitions')] disponibles pour
  | #[+value(phone, {'NOT_IL_ELLE':true})]
  | #[+agreeAdj(['exceptionnel','fabuleux','singulier'], phone)]
  | sont

  eachz color in phone.colors with { separator:',', last_separator:'et', end:'.' }
    - 
      var colorMapping = {
        'Black': 'Noir',
        'Red': 'Rouge',
        'White': 'Blanc',
        'Gold': 'Or',
        'Gray': 'Gris'
      }
    | #{colorMapping[color]}
//- end::colorsMixin[]

//- tag::introMixin[]
mixin intro
  synz
    syn
      | #[+value(phone)] est vraiment un super téléphone.
    syn
      | j'adore le nouveau #[+value(phone, {'NO_DET':true})].
    syn
      | #[+value(phone)] : un super téléphone !
//- end::introMixin[]

mixin phone_chunks
  itemz {separator: '.', end:'.', mix:true}
    item
      | #[+colors]
    //- tag::hasSaid[]
    item
      | #[+display]
      
      if !hasSaid('BATTERY')
        | , et dispose par ailleurs d'une batterie de #[+value(phone.battery)] mAh
        recordSaid('BATTERY')
    item
      if !hasSaid('BATTERY')
        | #[+value(phone)] a une batterie de #[+value(phone.battery)] mAh
        recordSaid('BATTERY')
    //- end::hasSaid[]

mixin phone_ref(obj, params)
  if !hasFlag(params,'NO_DET')
    | le
    protect
    | #{phone.name}
  - setRefGender(phone, 'M')

mixin phone_refexpr(obj, params)
  synz {mode:'sequence'}
    syn
      | #[+value('<ce appareil>', {represents: phone})]
    syn
      | #[+value('<cette machine>', {represents: phone})]
    syn
      if !hasFlag(params, 'NOT_IL_ELLE')
        | #{getMorF(['il', 'elle'], phone)}
    syn
      | #[+value('<ce téléphone>', {represents: phone})]
    syn
      | #[+value('<le téléphone>', {represents: phone})]

//- tag::phoneMixin[]
mixin printPhone
  | #[+intro] .
  | #[+phone_chunks]
//- end::phoneMixin[]

//- tag::main[]
- let phone;
each phoneElt in phones
  - phone = phoneElt;
  
  p
    - 
      phone.ref = phone_ref;
      phone.refexpr = phone_refexpr;
    | #[+printPhone]
    deleteSaid('BATTERY')
//- end::main[]

```

--------------------------------

### List Text Elements with `itemz > item` in Pug

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/eachz_itemz

Illustrates the `itemz > item` structure in RosaeNLG for listing text elements or mixins. This example shows how to conditionally include items based on a product's properties and format the output as sentences.

```pug
itemz > item
  if PRODUCT.gold
    | The ring has a huge central diamond
  | it is made with gold
  if PRODUCT.ruby
    | and it has 3 other diamonds
```

--------------------------------

### Generate Bullet Lists with `eachz` Assembly Parameters (JavaScript)

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/eachz_itemz

Illustrates creating bullet lists (unordered or ordered) from an array using `eachz`. This example uses parameters like `mode: 'list'`, `list_type`, `list_capitalize`, `list_intro`, `list_end_item`, and `list_last_end_item` for customization.

```pug
eachz elt in ['A', 'B', 'C'] with
  mode: 'list'
  list_type: 'ol'
  list_capitalize: true
  list_intro: 'Here is the list:'
  list_end_item: '.'
  list_last_end_item: '!'
  = elt
```

--------------------------------

### German Case and Referring Expression Example in Rosaenlg

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/referring_expression

Provides an example of how Rosaenlg handles different grammatical cases (NOMINATIVE, GENITIVE) for referring expressions in German. It shows the potential variations in output depending on the chosen case and the specific referring expression.

```javascript
p case(NOMINATIVE) #[+value('das Telefon')] / #[+value('diese Gurke')] / #[+value('diese Gurke')] / #[+value('dieses Handy')] / #[+value('dieses Handy')]
p case(GENITIVE) #[+value('des Telefons')] / #[+value('dieser Gurke')] / #[+value('dieses Telefons')] / #[+value('des Telefons')] / #[+value('dieser Gurke')]
```

--------------------------------

### Generate Phone Availability and Features (RosaeNLG)

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_en_US

This snippet defines the `colors` mixin for listing a phone's available colors, tints, or tones. It uses RosaeNLG's `syn` for alternative wording and `eachz` for iterating through the colors with appropriate separators and a final period.

```RosaeNLG
mixin colors
  | #[+value(phone)]'s available #[+syn('colors', 'tints', 'tones')]
  | are
  eachz color in phone.colors with { separator:',', last_separator:'and', end:'.' }
    | #{color}
```

--------------------------------

### Setting Explicit Gender for Referring Expressions in Rosaenlg (French Example)

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/referring_expression

Demonstrates how to explicitly set the gender of an object for referring expression generation using `setRefGender`. This example shows setting it to feminine ('F') for French, enabling correct grammatical agreement in the output.

```javascript
setRefGender(PRODUIT, 'F')
```

--------------------------------

### RosaeNLG Country Mixin Examples (Pug)

Source: https://rosaenlg.org/rosaenlg/4.4.0/libs/countries

Demonstrates the usage of the `country` mixin in Pug templates for different localization needs. The mixin accepts country codes (cca2, ccn3, cca3) and various parameters to format the output, such as definite articles, prepositions, and official names. It covers both English and French language examples.

```pug
- #[+country({cca2: 'GB', 'DEFINITE'})]
- #[+country({cca2: 'GM', 'DEFINITE'})]
- #[+country({cca2: 'BB', 'DEFINITE'})]
- #[+country({cca2: 'NL'}, 'COUNTRY_NAME')]
- #[+country({cca2: 'FR'}, 'OFFICIAL_COUNTRY_NAME')]

- #[+country({cca2: 'FR'}, 'DEFINITE')]
- #[+country({cca2: 'MU'}, 'DEFINITE')]
- #[+country({cca2: 'FR'}, 'IN')]
- #[+country({cca2: 'NL'}, 'IN')]
- #[+country({cca2: 'MU'}, 'IN')]
- #[+country({cca2: 'MU'}, 'FROM')]
```

--------------------------------

### Combine Phone Description Elements with RosaeNLG

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_en_US

This RosaeNLG mixin combines multiple components (intro, colors, display, battery) into a structured phone description. It uses `itemz` with `mix:true` to allow for flexible ordering of the descriptive elements, enhancing natural language variability. The `separator:'.', end:'.'` ensure proper punctuation.

```nlg
mixin phone_chunks
  itemz {separator: '.', end:'.', mix:true}
    item
      | #[+colors]
    item
      | #[+display]
    item
      | this phone has a battery of #[+value(phone.battery)] mAh
```

--------------------------------

### Integrate Color List Generation into Main Template (Pug)

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_de_DE

Includes the `colors` mixin within the main Pug template to display the phone's name followed by its available colors, formatted using the `eachz` structure. This shows how to combine basic output with generated lists.

```pug
p #{phone.name} . #[+colors]
```

--------------------------------

### Rosaenlg: Using Synonyms in Mixins

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_en_US

This snippet demonstrates how to use the `syn` mixin in Rosaenlg to provide synonyms for words, reducing repetition in generated text. It shows a 'colors' mixin that can output 'colors', 'tints', or 'tones'.

```pug
mixin colors
  | the phone's available #[+syn('colors', 'tints', 'tones')]
  | are
  eachz color in phone.colors with { separator:",", last_separator:"and", end:"." }
    | #{color}
```

--------------------------------

### RosaeNLG Mixin for Display Properties

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_en_US

Defines a RosaeNLG mixin named 'display' to structure sentences about phone display features. It uses `itemz` to list the physical size and screen-to-body ratio, with options for general introductory text, separators, and randomizing the order of listed items.

```RosaeNLG
mixin display
  itemz { begin_with_general: 'it has a display', separator:',', last_separator:'and', mix:true }
    item
      | a physical size of #[+value(phone.displaySize)] inches
    item
      | a screen-to-body ratio of #[+value(phone.screenRatio)] %
```

--------------------------------

### Set Plural for Spanish Word

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/dict

Example of using `setWordData` to define the plural form of a Spanish word. This ensures correct pluralization.

```javascript
setWordData('joya', {plural: 'joyaPLURAL'})
```

--------------------------------

### Rosaenlg Main Loop for Phone Descriptions

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_en_US

This Rosaenlg code iterates through a list of phones, setting each phone as the current context and then calling the 'printPhone' mixin to generate its description. It also assigns reference mixins to the phone object.

```rosaenlg
- let phone;
each phoneElt in phones
  - phone = phoneElt;
  p
    - 
      phone.ref = phone_ref;
      phone.refexpr = phone_refexpr;
    | #[+printPhone]

```

--------------------------------

### Generate Only Determiner (Rosaenlg)

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/value_nominal_groups

Provides an example of generating only a determiner without a noun. This is useful in rare cases where only the determiner itself is needed, and its gender and number can be specified.

```Rosaenlg
#[+value('', {det:'DEFINITE', gender:'M', number:'S'})]
```

--------------------------------

### List Sentence Parts with RosaeNLG

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_de_DE

This snippet demonstrates how to structure parts of a sentence using RosaeNLG's `itemz` and `item` constructs. It allows for flexible assembly of sentence fragments with customizable separators, suitable for listing properties like display size and screen ratio.

```RosaeNLG
mixin display
  itemz { separator:',', last_separator:'und' }
    item
      | einer physischen Größe von #[+value(phone.displaySize)] Zoll
    item
      | einem Bildschirm-zu-Körper-Verhältnis von #[+value(phone.screenRatio)]%
```

--------------------------------

### Rosaenlg Mixin for Display Information

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_en_US

This Rosaenlg mixin constructs a descriptive phrase about a phone's display. It uses a combination of general introductory phrases and specific itemized details about physical size and screen-to-body ratio.

```rosaenlg
mixin itHasADisplay
  | #[+value(phone)] has a display with

mixin display
  itemz { begin_with_general: itHasADisplay, separator:',', last_separator:'and', mix:true }
    item
      | a physical size of #[+value(phone.displaySize)] inches
    item
      | a screen-to-body ratio of #[+value(phone.screenRatio)] %

```

--------------------------------

### Set Gender for Italian Word

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/dict

Example of using `setWordData` to specify the gender (Masculine 'M' or Feminine 'F') of an Italian word. This is important for agreement.

```javascript
setWordData('foto', {'G': 'M'})
```

--------------------------------

### Rosaenlg Mixin for Printing Phone Details

Source: https://rosaenlg.org/rosaenlg/4.4.0/tutorials/tutorial_en_US

This Rosaenlg mixin orchestrates the generation of a complete description for a phone. It combines introductory phrases with detailed chunks of information about the phone's attributes.

```rosaenlg
mixin printPhone
  | #[+intro] .
  | #[+phone_chunks]

```

--------------------------------

### Run RosaeNLG Java Server with Embedded Server

Source: https://rosaenlg.org/rosaenlg/4.4.0/integration/java-server

This command demonstrates how to run the RosaeNLG Java Server directly using its executable war file with an embedded server. It also shows how to set a custom directory for storing templates using the 'rosaenlg.homedir' system property.

```bash
java -jar java-server-VERSION.war
```

```bash
java -Drosaenlg.homedir="C:/some_folder" -jar target/java-server-VERSION.war
```

--------------------------------

### Set Spanish Adjective Flex Forms

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/dict

Example of setting flex forms for Spanish adjectives using `setAdjData`. The boolean indicates if the form comes before or after the noun.

```javascript
setAdjData('hermoso', {FStrue: 'hermosoFStrue'})
```

--------------------------------

### Set Plural for Italian Word

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/dict

Example of using `setWordData` to define the plural form of an Italian word. The key 'P' is used for plural, and 'S' for singular.

```javascript
setWordData('gioiello', {'P': 'gioielloTEST'})
```

--------------------------------

### Set Gender for German Word

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/dict

Example of using `setWordData` to assign a grammatical gender (Masculine, Feminine, or Neuter) to a German word. This is crucial for German grammar.

```javascript
setWordData('Mädchen', {G: 'M'})
```

--------------------------------

### Set Gender for Spanish Word

Source: https://rosaenlg.org/rosaenlg/4.4.0/mixins_ref/dict

Example of using `setWordData` to assign a gender (Masculine 'M' or Feminine 'F') to a Spanish word. Gender agreement is crucial in Spanish.

```javascript
setWordData('correa', {gender: 'M'})
```
Tokens:
Raw