WRITE

The WRITE command is central to YeetWords, as this is the only way for words to go into the story*.

WRITE takes a sentence, substitutes specially designated words there from words from a catalog of words, formats the sentence, writes it into the story, and repeats this process the desired amount of times.

* OK, technically NEWCHAPTER writes chapter headings to the story, but other than that, WRITE is the only way to add actual words to the story.

Syntax

WRITE sentences wordcatalog amount random/order-optional

where sentences is either a list or catalog of sentences. Note: the user may use the special catalog name sfolder to indicate the catalog of words read from the user folder beginning with sentence.

wordcatalog is a catalog of words (not a list). Note: the user may use the special catalog name wfolder to indicate the catalog of words read from the user folder beginning with word.

amount is the desired amount of repeats and is optional if it is the last parameter. This may be a number of sentences (e.g. 5), a desired number of words (e.g. 500W), a range of sentence numbers (e.g. 5--12), or a range of words (e.g. 200W--1500W). This parameter is optional if it is the last parameter, and if unspecified it defaults to 1 (i.e. 1 sentence). 0 or 0W or ranges containing those are all allowable.

random/order-optional may have either of two values: random or order. random means that the sentences are taken from sentences in a random order, while order means that the sentences are taken in the order that they appear in sentences (this behaves differently for lists versus catalogs; see below). This parameter is optional, and if not specified it defaults to random

random/order-optional has different behavior when sentences are in a list versus a catalog

The behavior of random/order-optional differs when sentences is a list versus when it is a catalog.

List

Lists go with the intuitive behavior that a value of random selects randomly from the list, while order takes sentences in the order they appear in the list.

Catalog

In the case of a catalog, the behavior is slightly different: random selects a random list name within the sentences catalog and selects a random sentence from that list. order selects a list from the sentence catalog in the order that the list appears in the catalog. It then selects a random sentence from within that list.

Example

Let's take a look at an example sentences in a catalog named dialog:

dialog

greetings

Hello

It's good to see you

Welcome

main

I heard that _PERSON.NAME_ is having some drama

We are hoping to learn more about the _ITEM_

There was a flood and now _CITY.NAME_ is in chaos

end

Goodbye

Have a nice day

It was good talking with you

Suppose you put WRITE dialog mywords 5 random, then this is what would happen: a random list would be selected out of the 3 options: greetings, main, or end. Then, a random sentence from that list would be selected. (Then word substitution and formatting would occur, and then that modified sentence would be written into the story). This process is repeated for a total of 5 sentences.

On the other hand, if you put WRITE dialog mywords 5 order, then this is what would happen: first, the list named greetings would be used because it is the first list in that catalog. A random sentence would be selected from greetings (then word substitution, formatting, and writing to the story). In the second of the desired 5 total, the list named main would be used because it is the second list in that catalog, a random sentence from that list would be selected, etc. In the third of the 5, the list named end would be selected, a random sentence from that list would be chosen, and so on. In the fourth of the 5, it would loop around to the first so it would take from the list named greetings. In the fifth and final, it would take from the list named main. Once the stop condition is reached the writing loop ends even if all sentences are not used.

Take-home message: In some situations a catalog of sentences is more useful than a list, and vice versa, depending on what you are trying to do.

Caveat for random - an attempt is made to ensure the current sentence is different from the previous one

In the case of a random parameter specified for either a list or catalog of sentences, an attempt is made to ensure the current sentence is different from the previous one, since this is generally a desirable outcome for generative fiction. This is done as defined: for a list of sentences that has more than 1 sentence in it, the previous sentence is temporarily removed from consideration when selecting the next random sentence. For a catalog of sentences that has more than one list in it, the previous list used is temporarily removed from consideration when selecting a random list to use.

This means that a catalog containing a single list will not have the ability to make subsequent sentences different.

I have steered away from more stringent attempts to make subsequent sentences different - for example, consider a catalog containing short lists of identical contents; it would be impossible to ensure subsequent sentences are different. Likewise, in the case of a single-item list or a single-list catalog containing a single item, it is impossible to ensure current and previous sentences are different - endless looping would occur. Therefore, to avoid these undesirable effects, it should be considered that YeetWords makes an attempt to ensure two subsequent sentences are not identical, but it cannot be guaranteed to be the case, and this depends on the composition of the sentences list/catalog. This is valid for as many repeats as specified within the one WRITE command line. However, no attempt is made whatsoever to have different sequential sentences between different WRITE commands.

Event sequence - word substitution and formatting

Parameters are first checked for validity, and if either sentences or words are empty or do not exist then the program will halt with an error.

The sequence of events once valid parameters are given in the WRITE command is that for each repetition, these events happen:

1. sentence selection (described above) so that one sentence is selected

2. word substitution - Word substitution codes in the selected sentence are identified. These take the form of underscore, alphanumeric (i.e. alphabet and number) characters and underscore e.g. _NOUN_. These are one at a time substituted for a matching word from the word catalog parameter in the WRITE command: each code is substituted for a random word from a list of the same name without the underscores (e.g. noun) from within the word catalog. Thus it is very important that substitution codes and word list names are spelled the same way. They are not case-sensitive. Important: if no such list is present in the word catalog, a severe warning will be emitted and the word SOMETHING will be used as the replacement in that situation. The word substitution process takes place from left to right in a sentence.

3. formatting - The substituted sentence is then formatted according to that previously specified by the user in the FORMAT command (see Wiki entry for FORMAT for more details). FORMAT parameters may be updated at any time. If unspecified, the FORMAT parameters default to ACPS, which means a/an substitution, capitalization of first letter, period at the end, space at the end.

4. story writing - the substituted formatted sentence is then appended to the story so far.

Going through the above process once with a sentence is considered writing 1 sentence to the story (regardless of how long or short the sentence actually is).

Note: Words written to the story are stored internally and are not written to file output until the end of the program is reached. Thus, if wishing to examine the story at a certain point before it is written to file output, the DISPLAY command may be used, which emits the story so far (or a user-specified amount of the start or end of it) to the screen.

Related commands

FORMAT, NEWCHAPTER, NEWPARA, NEWLINE, DISPLAY, ASSIGNLIST, ASSIGNCATALOG