Difference between revisions of "Cabal Common Library Doc PhraseGen"

From Elite Wiki
(Started documentation)
 
m (part II)
Line 26: Line 26:
  
 
Additionally fields can be related to each other and even a conditional markup is processed (recursion depth is limited).
 
Additionally fields can be related to each other and even a conditional markup is processed (recursion depth is limited).
 +
 +
All sets have the same form:
 +
SetName: {
 +
  fieldA: [],
 +
  fieldB: [],
 +
  fieldC: [],
 +
  ...
 +
  fieldR: [],
 +
  sentences: []
 +
}
 +
The fields A-I are treated as row1, J-R as row2.
  
  
Line 58: Line 69:
 
:;success:Boolean. True if set was placed, otherwise false.
 
:;success:Boolean. True if set was placed, otherwise false.
  
 +
 +
== Rules ==
 +
The following rules are processed by PhraseGen:
 +
 +
=== Patterns ===
 +
Patterns are simple strings to control the sentence building. They can contain plain text, control chars
 +
or conditional checks. The script replaces numers (in range 1-9) with content from the sets field arrays.
 +
 +
First letter and next word after . ! or ? is capitalized.
 +
+ -> Forces capitalization.
 +
} -> Forces fields 1-9.
 +
{ -> Forces fields 10-18.
 +
> -> Applies plural rules.
 +
< -> Applies singular rules (probably obsolete).
 +
| -> Random plural (50%).
 +
# -> Verb case 1. simple present
 +
_ -> Verb case 2. simple past
 +
^ -> Verb case 3. past participle
 +
* -> Verb case 4. perfect
 +
@B -> player.bounty.
 +
@C -> player.name.
 +
@D -> player.ship.displayName.
 +
@F -> Random Firstname.
 +
@f -> Stored @F, else empty string.
 +
@I -> player.ship.name.
 +
@L -> player.legalStatus.
 +
@N -> Random Surname.
 +
@n -> Stored @N, else empty string.
 +
@P -> Current system.name.
 +
@R -> player.rank.
 +
@S -> Random system.name.
 +
@s -> Stored @S, else empty string.
 +
@T -> player.ship.target.displayName.
 +
@Z -> Random Brew name.
 +
@z -> Stored @Z, else empty string.
 +
a followed by vowel a,e,i,o,u -> an
 +
a followed by superlative -> the
 +
 +
=== Fields ===
 +
Fields can contain plain text, field combiners or conditional checks.
 +
 +
$ -> identifies verb (e.g. decide$).
 +
& -> identifies irregular noun or verb (e.g. &go$ or &bison).
 +
[#] -> field combiner.
 +
 +
=== Noun Plural ===
 +
& -> irregular, uses lookup table.
 +
otherwise:
 +
  [^es]s -> unchanged
 +
  fe -> replace with ves
 +
  e -> word + s
 +
  [^o]o,[^ei]x,es[s],[cs]h -> word + es
 +
  [^aeiou]y -> replace with ies
 +
  [^erf]f -> replace with ves
 +
  [ei]x -> replace with ices
 +
  else -> word + s;
 +
 +
=== Verb Tenses ===
 +
& -> irregular, uses lookup table.
 +
  Can be combined with plural prefix.
 +
    case 0 -> base form, e.g. go
 +
    case 1 -> simple present, e.g. goes
 +
    case 2 -> simple past, e.g. went
 +
    case 3 -> past participle, e.g. gone
 +
    case 4 -> singular: has gone
 +
    case 4 -> plural: have gone
 +
otherwise:
 +
  case 0 -> base form
 +
  case 1 -> apply plural noun rules
 +
  case 2 ->
 +
    e -> word + d
 +
    [^aeou]y -> replace with ied
 +
    [aeioy]p -> word + ped
 +
    [aeioy]b -> word + bed
 +
    [^l]l -> word + led
 +
    else -> word + ed
 +
  case 3 ->
 +
    e -> word + d
 +
    [^aeou]y -> replace with ied
 +
    [aeioy]p -> word + ped
 +
    [aeioy]b -> word + bed
 +
    [^l]l -> word + led
 +
    else -> word + ed
 +
  case 4 -> singular: has + case 3
 +
  case 4 -> plural: have + case 3
 +
 +
=== Field combiner ===
 +
Field combiner are used to place content of fields of the same row in other fields.
 +
The rows are field 1-9 (A-I) and field 10-18 (J-R).
 +
 +
[#] -> field combiner.
 +
 +
=== Conditional ===
 +
PhraseGen can also be instructed to check values against collected data and react accordingly.
 +
On every docking (and after <tt>.startUp</tt>) PhraseGen stores randomly choosen nodes from [[Cabal_Common_Library_Doc_Functions#moreInfo|Cabal_Common_Library_Doc_Functions]] and the node of the current system (additionally updated on launching and exiting witchspace).
 +
 +
These nodes are used to compare the instructions in fields and patterns against their values. E.g.
 +
(Sg>0=[7]|[6])
 +
 +
Syntax:
 +
Must be enclosed by round brackets.
 +
S,P -> identifier for the node with S = @S, P = @P
 +
type:
 +
    c -> productivity
 +
    e -> economy
 +
    g -> government
 +
    p -> population
 +
    r -> radius
 +
    s -> sun
 +
    t -> techlevel
 +
operators:
 +
  : -> equal
 +
  < -> lessthan
 +
  > -> greaterthan
 +
  ! -> not equal
 +
actions:
 +
  = -> identifies the actions
 +
  | -> separator matched / not matched
  
 
----
 
----
 
[[Category:OXPDoc]]
 
[[Category:OXPDoc]]

Revision as of 16:20, 13 April 2013

Overview

This is the main class for the generator with its members and part of the Cabal_Common_Library.

PhraseGen is a generator for phrases, names, sentences or other messages and works similiar to other random mechanisms on the net. It uses 3 scripts:

  • a data script holds a few objects only (words, sets, irregular nouns, irregualar verbs and superlatives).
  • a build script which prefills some lists, processes OXP input and handles the rules.
  • a helper script which does the communication between HTML and build script. This is not used in Oolite.


The words object is the heart of the whole thing. It contains arrays which are used in the sets. Multiple arrays can be concatenated easily and content can be reused - if I recall it right it's a similiar approach to CMcLs RandomShipNames.oxp. The concept is basically using the 'soft' references in JS.

Every set contains 18 arrays with words (or phrases) and a array with sentence patterns.

The helper script + HTML will be available as separate download, but probably only works properly in Firefox/SeaMonkey. If someone wants to create a crossbrowser version, give me a call.


How it works

The script simply replaces the numbers (1-9) in the pattern with content from the arrays.

Switching between 1-9 and 10-18 is done via special char. Some other special chars are giving patterns some more oompf, e.g. for displaying player.name or setting flags for the word processing. And when a word is picked from the arrays additional rules are applied before it replaces the number in the pattern. The rules are designed to work with english words (some exceptions are handled).

Main goal is performance while handling a wide range of possibilities and it really looks promising.

The script also precreates some specials and populates the corresponding arrays to be combined via pattern when a OXP requests it.

Additionally fields can be related to each other and even a conditional markup is processed (recursion depth is limited).

All sets have the same form: 

SetName: {
  fieldA: [],
  fieldB: [],
  fieldC: [],
  ...
  fieldR: [],
  sentences: []
}

The fields A-I are treated as row1, J-R as row2.


Methods

makePhrase()

var a = worldScripts.Cabal_Common_PhraseGen.makePhrase(setname [,pattern]);

Is simple and straightforward. When called the method returns the created string.

Parameters:

setname
String/Object.
String:PhraseGen looks up if the pool contains a set with this name.
Object:PhraseGen uses the passed object.
pattern
String/Array. Optional. If not specified PhraseGen will use a randomly choosen pattern from the current set.
String:
Array:PhraseGen will randomly choose a element.

Returns:

phrase
String. The generated string or false.


addSet()

var a = worldScripts.Cabal_Common_PhraseGen.addSet(setname, obj [,clone]);

For adding data to the pool there are two possible ways.

Parameters:

setname
String. Unique identifier for the set. Probably the easist way is to use OXPName_SetID.
obj
Object. Holds the arrays with words and patterns.
clone
Boolean. Optional. If specified PhraseGen creates a deepcopy of the object. Otherwise it will store a object holding references.

Returns:

success
Boolean. True if set was placed, otherwise false.


Rules

The following rules are processed by PhraseGen:

Patterns

Patterns are simple strings to control the sentence building. They can contain plain text, control chars or conditional checks. The script replaces numers (in range 1-9) with content from the sets field arrays. 

First letter and next word after . ! or ? is capitalized.
+ -> Forces capitalization.
} -> Forces fields 1-9.
{ -> Forces fields 10-18.
> -> Applies plural rules.
< -> Applies singular rules (probably obsolete).
| -> Random plural (50%).
# -> Verb case 1. simple present
_ -> Verb case 2. simple past
^ -> Verb case 3. past participle
* -> Verb case 4. perfect
@B -> player.bounty.
@C -> player.name.
@D -> player.ship.displayName.
@F -> Random Firstname.
@f -> Stored @F, else empty string.
@I -> player.ship.name.
@L -> player.legalStatus.
@N -> Random Surname.
@n -> Stored @N, else empty string.
@P -> Current system.name.
@R -> player.rank.
@S -> Random system.name.
@s -> Stored @S, else empty string.
@T -> player.ship.target.displayName.
@Z -> Random Brew name.
@z -> Stored @Z, else empty string.
a followed by vowel a,e,i,o,u -> an
a followed by superlative -> the

Fields

Fields can contain plain text, field combiners or conditional checks. 

$ -> identifies verb (e.g. decide$).
& -> identifies irregular noun or verb (e.g. &go$ or &bison).
[#] -> field combiner.

Noun Plural

& -> irregular, uses lookup table.
otherwise:
  [^es]s -> unchanged
  fe -> replace with ves
  e -> word + s
  [^o]o,[^ei]x,es[s],[cs]h -> word + es
  [^aeiou]y -> replace with ies
  [^erf]f -> replace with ves
  [ei]x -> replace with ices
  else -> word + s;

Verb Tenses

& -> irregular, uses lookup table.
  Can be combined with plural prefix.
    case 0 -> base form, e.g. go
    case 1 -> simple present, e.g. goes
    case 2 -> simple past, e.g. went
    case 3 -> past participle, e.g. gone
    case 4 -> singular: has gone
    case 4 -> plural: have gone
otherwise:
  case 0 -> base form
  case 1 -> apply plural noun rules
  case 2 ->
    e -> word + d
    [^aeou]y -> replace with ied
    [aeioy]p -> word + ped
    [aeioy]b -> word + bed
    [^l]l -> word + led
    else -> word + ed
  case 3 ->
    e -> word + d
    [^aeou]y -> replace with ied
    [aeioy]p -> word + ped
    [aeioy]b -> word + bed
    [^l]l -> word + led
    else -> word + ed
  case 4 -> singular: has + case 3
  case 4 -> plural: have + case 3

Field combiner

Field combiner are used to place content of fields of the same row in other fields. The rows are field 1-9 (A-I) and field 10-18 (J-R). 

[#] -> field combiner.

Conditional

PhraseGen can also be instructed to check values against collected data and react accordingly. On every docking (and after .startUp) PhraseGen stores randomly choosen nodes from Cabal_Common_Library_Doc_Functions and the node of the current system (additionally updated on launching and exiting witchspace).

These nodes are used to compare the instructions in fields and patterns against their values. E.g. 

(Sg>0=[7]|[6])

Syntax: 

Must be enclosed by round brackets.
S,P -> identifier for the node with S = @S, P = @P
type:
   c -> productivity
   e -> economy
   g -> government
   p -> population
   r -> radius
   s -> sun
   t -> techlevel
operators:
  : -> equal
  < -> lessthan
  > -> greaterthan
  ! -> not equal
actions:
  = -> identifies the actions
  | -> separator matched / not matched
Retrieved from "https://wiki.alioth.net/index.php?title=Cabal_Common_Library_Doc_PhraseGen&oldid=36602"