Filter functions

This is the documentation for 1.5.5 version, which is not the latest version. Consider upgrading to 3.4.0.

Filtering is used to clean the text after generation, adding caps and removing extra punctuation. It is regexp based and will have as an input a string, previously generated by Pug.

The filtering mechanism is called either via the filter(mixinName, params) mixin, or automatically via renderFile. It can also be explicitely disabled when you use RosaeNLG as a plain Pug engine.

Most of the time you should not bother with the explicit filter mechanism. Just let the automatic mechanism trigger.

The automatic mechanim vs the explicit mixin

By default RosaeNLG will automatically filter its whole output. You get the final filtered result.

Still you might prefer using the filter mixin when there are entire sections of your html document (not containing NLG text) that you don’t want to filter.

Filtering must not be performed twice:

  • If you don’t call the filter mixin, the whole text will be filtered once at the end.

  • If you use the filter mixin, it will desactivate the global filtering at the end.

The filter mixin

The filter(mixinName, params) mixin takes 2 arguments:

  • mixinName is the mixin to call, where you have your text to be generated

  • params are the params for your mixin (optional)

It can look like that:

div
  - var myProduct = ...;
  +filter('product_mixin', myProduct)

mixin product_mixin(product)
  ...
Just after calling this mixin, the unfiltered string (the original one) is available in util.lastUnfiltered. This can be useful for debug.

Protect sections from being filtered

Filtering is nice because it will automatically manage capitalization etc. for you. But sometimes you want to disable this mechanim for some sections: Baba Inc. is a nice company instead of Baba Inc. Is a nice company.

Also, filtering currently does not work well when applied on common html tags, like <i>, <b> or <a href=…​>.

Use the protectString(string) js function to protect your strings from begin filtered:

will output protected.string (and not protected. String).

You should favor the protect tag which better cares for spacing.

Use the protect tag to protect structures:

will output the same.

Disable filtering

When you want to generate texts, filtering is mandatory. But when you simply want to use RosaeNLG’s Pug features, without any Natural Language generation features, you need to disable filtering:

const rosaenlgPug = require('rosaenlg');

rosaenlgPug.renderFile('plainPugTemplate.pug', {
    language: 'en_US',
    disableFiltering: true
});