Word generator
==============

The word generator is used and configured in the modal to :ref:`add a word <dictionary add word>`.  

| The engine is a slightly modified version of `fantasy name generator <https://github.com/skeeto/fantasyname>`_.  
| In a few words it worsk by creating patterns which randomly pick elements from your symbols to create new words.  

.. raw:: html

   <hr>

.. _word generator symbols:

Symbols
#######

.. figure:: /images/examples/generator_symbols.png
	:align: left

| Each symbol contains a list of elements which can be randomly selected to be included in the output of the generator.  
| Each element can contain one or more characters.  

| Lingomancy checks all symbols to find any missing :ref:`romanizations<phonology romaniation>`.  
| This check is just informative, no errors are generated if you don't use all romanizations.  

.. raw:: html

   <hr>

Patterns
########

.. figure:: /images/examples/generator_patterns.png
	:align: left

A pattern is a string of characters which is processed to generate random words based on the following rules:

- Characters grouped between angle brackets (``<`` and ``>``) will be processed by the engine as described in these steps (You can think about the pattern already being surrounded by them)
- Characters grouped between parentheses (``(`` and ``)``) won't be processed and will be send to the output as they are.  
- A vertical bar (``|``) can be used to randomly select between choices in that group.  
- An exclamation point (``!``) can be used to capitalize the next element of the pattern (character, symbol, or group)  
- A tilde (``~``) can be used to capitalize the next element of the pattern (character, symbol, or group)  
- Any character used which is associated with a symbol will be replaced with an element from that symbol chosen at random.  
- Any other character will be send to the output as it is.  

.. raw:: html

   <hr>

Example
#######

Let's assume we have the following symbols configured:  

- ``C``: ``p``, ``m``, ``nn``
- ``N``: ``m``, ``nn``
- ``V``: ``a``, ``o``, ``u``
- ``A``: ``a``

This is the expected behavior of these patterns:  

- ``NVCAF``: Will produce a word replacing each character for a random element of each corresponding symbol while having ``F`` at the end, since it doesn't correspond to any configured symbol: ``nnopaF``.  
- ``~<NVCAF>``: Will produce a similar result as the previous example with all character in the reverse order: assuming the output would have been the same this would be ``Faponn``.  
- ``!CV|Na(CV)``: Will produce a word as if the pattern was either ``!CV`` or ``Na(CV)``: 
  - ``!CV`` Will behave as the first example with the first letter from C capitalized: ``Nnu``.  
  - ``Na(CV)`` Will produce a word with the first part from the symbol ``N``, the character ``a`` as is (since there's no symbol for this character), and the characters ``CV`` as they are grouped between parentheses (even when they represent symbols): ``maCV``

Generating words
################

Once you have configured the patterns and symbols you can use them to generate new words.  

.. figure:: /images/examples/generator_usage.png
	:align: left

| When you first open the modal, the generator will automatically select and generate words for the first pattern of the list.  
| You can change the pattern from the button "Patterns".  

.. |refresh_icon| image:: /images/shared/refresh_icon.png

To generate new words you need to click one of the two buttons:  

- | |refresh_icon| will generate the amount of words in the field "Words to generate" minus the duplicate ones.  
  | You then can click any of the words to place it in the "Current generated word" text box.  
- "Generate" will generate one word at a time and replace it in the "Current generated word" text box.