The CFGSongNameEngine is a SongNameEngine that uses a CFG (context-free grammar) in order to generate random song names (song titles). A CFG approach provides a powerful, yet comprehensible way to generate sentences, titles, etc., which can be specified by providing grammar rules.

The CFGSongNameEngine uses a set of user-defined variables (or production rules), which constitute the context-free grammar, to create a song name. Each variable defines a list of strings, which themselves can contain references to other variables. A song name is created by starting with the variable called "songName" (which is mandatory to be defined), choosing a random string from that variable and recursively replacing further variable references with randomly-chosen strings until no further replacement is possible. Care must be taken in the definition of the variables to avoid the possibility of endless loops.

If the same variable is used more than once throughout the generation of a song title (no matter at which recursion levels), the CFGSongNameEngine makes sure that it will not reuse an already used string unless you have used up all the strings of the variable. For example, if you have a variable "x" with the string list "A,B,C,D", then "${x}${x}${x}${x}" will give you a random permutation of the characters A, B, C and D, without using the same character twice. If, however, you reference "x" for the fifth time, the "used" flags are reset and any character can be chosen again (e.g., "${x}${x}${x}${x}${x}${x}${x}${x}" would give you two independent permutations of A, B, C and D). This feature can be controlled per variable by using the "once" attribute. If you set this attribute to false, then the random selection is done without considering the previous random selections of the same variable, otherwise previous selections are considered.

You need to make sure that the production rules of the CFG are complex enough to be able to generate as many different song names as possible, because the number of different song names is directly related to the amount of different songs that can be generated by SoundHelix if no title has been specified. For example, if the CFG can only generate one title, then this title will be used for every song (unless you have started SoundHelix with an explicit song title); in other words, SoundHelix would only be able to generate one song, because the title is used as the random seed.

You can also use the CFGSongNameEngine to create a small fixed number of song names. For example, you might have checked a number of song names and might have made a selection of songs you like. Just enter the song names as indicated in the second configuration example below.


Tag Attribute Type # Example Description
variable name string 1 songName The name of the variable
variable once boolean 0-1 true Boolean indicating whether all strings must have been used before a string can be used again. If set to true, it is possible to refer to the same variable several times while preventing duplicate strings from that variable to be used (provided the variable contains enough strings). If set to false, the strings will be randomly selected without preventing duplicate usage. Defaults to true.
variable - list of strings 1-n text1,text2,${variable3} The comma-separated list of strings. Strings can contain references to variables by using ${variable}.

Note: In the list of strings, backslashes serve as escape characters. You can get a literal comma (instead of starting the next string) by using "\," and a backslash by using "\\".

Configuration example

<songNameEngine class="CFGSongNameEngine">
  <variable name="adjective">adventurous,superstitious,dependent,unfriendly</variable>
  <variable name="ending">on a plate,in the streets,in the 21st century,in the sky,in the dark,from ${city}</variable>
  <variable name="city">New York,Boston,San Francisco,Los Angeles,Houston,Paris,London,Berlin,Perth,Sydney,Melbourne</variable>
  <variable name="optionalEnding" once="false">, ${ending}</variable>
  <variable name="animal">hamster,cat,dog,horse,cow,sheep,frog,crocodile,mouse,rat,snake</variable>
  <variable name="subject">boy,girl,man,woman,father,mother,brother,sister,grandpa,grandma,coward,idiot,dwarf,giant,genius,doctor,magician,technician,engineer</variable>
  <variable name="songName">${adjective} ${subject}'s ${adjective} ${animal}${optionalEnding},The ${adjective} ${subject}${optionalEnding},The ${adjective} ${animal}${option
alEnding},${adjective} and ${adjective}</variable>

<songNameEngine class="CFGSongNameEngine">
  <!-- some fixed song names -->
  <variable name="songName">song name 1,song name 2,song name 3</variable>

Add new comment