Cabal Common Library Doc PhraseGen - Revision history

Cholmondely: Added Links

2025-06-29T01:54:45Z

Added Links

Cholmondely: Retagged!

2023-09-20T14:09:47Z

Retagged!

Svengali: added conditionals G (galaxyNumber) and N (None, bitmask)

2013-09-14T14:00:20Z

added conditionals G (galaxyNumber) and N (None, bitmask)

Svengali at 11:44, 6 September 2013

2013-09-06T11:44:01Z

Svengali: part XXIII

2013-08-29T19:32:29Z

part XXIII

Svengali: added bitmask check all(A) and any (Y)

2013-08-16T20:04:18Z

added bitmask check all(A) and any (Y)

Svengali: XXI

2013-08-16T15:41:51Z

XXI

Svengali at 12:32, 14 August 2013

2013-08-14T12:32:13Z

Svengali: part XX

2013-08-14T12:02:35Z

part XX

Svengali: part XIX

2013-08-13T21:19:42Z

part XIX

@@ Line 328: / Line 328: @@
 * splitRules
 ----
 [[Category:OXP API's]]

← Older revision		Revision as of 14:09, 20 September 2023
Line 329:		Line 329:

	----		----
−	[[Category:~~OXPDoc~~]]	+	[[Category:OXP API's]]

@@ Line 295: / Line 295: @@
       Number in range 1-100. Checked if greaterthan random number, e.g. (D50=yes|no). Ignored if seed is used.
       or 3 Numbers to generate random number in range param1-param2 in steps of param3 e.g. (D25,150,25)
   S, P: (node handling with S = @S, P = @P)
     multiple conditions are separated by , (logical AND)

@@ Line 15: / Line 15: @@
 == How it works ==
-CCL_PhraseGen uses a collection (a [[#Samples|Sample]]) of words, sylables or phrases which are ordered in 18 available arrays ([[#Fields|Fields]]) and a special array which controls how these should be combined ([[#Patterns|Pattern]]). Fields and Patterns have their own set of rules (e.g. to control pluralization). Fields can hold lots of single words or even complete sentences and, basically, entries in Fields are selected randomly.
+CCL_PhraseGen uses a collection (a [[#Samples|Sample]]) of words, sylables or phrases which are ordered in 18 available arrays ([[#Fields|Fields]]) and a special array which controls how these should be combined ([[#Patterns|Pattern]]). Fields and Patterns have their own set of rules (e.g. to control pluralization). Fields can hold lots of single words or even complete sentences and, basically, entries in Fields are selected randomly, but a optional seed is available.
 You can imagine a Sample as a wardrobe with drawers. The Pattern controls which drawer gets opened and the script picks one item out of it and attaches it to the final output before it walks further over the Pattern.
@@ Line 126: / Line 126: @@
 == Methods ==
 === makePhrase() ===
-{{CodeEx|codeex=var a = worldScripts.Cabal_Common_PhraseGen.makePhrase( samplename [,pattern [,store [,seed]]] );}}
+{{CodeEx|codeex=var a = worldScripts.Cabal_Common_PhraseGen.makePhrase( samplename [,pattern [,store [,seed [,custom]]]] );}}
 Is simple and straightforward. When called the method returns the created string.
@@ Line 136: / Line 136: @@
 :;pattern: String/Array. Optional. If not specified PhraseGen will use a randomly choosen pattern from the current Sample.
 :::String: Pattern.
-:::Array: PhraseGen will randomly choose a element.
+:::Array: PhraseGen will randomly choose a element, if seed is not used.
 :;store: Boolean. Optional. It true PhraseGen will return a array instead.
-:;seed: Number.
+:;seed: Number. Optional. If a positive integer it influences the selection of Patterns and Field entries and the conditional (D) dice roll.
 '''Returns:'''
@@ Line 213: / Line 215: @@
     ^(?:[aei]|o[^ne]|ho(?:ur|nest|no|mage|mbre|rs d')|he(?:ir|rb)) -> an
   a followed by superlative -> the
-  [a-zA-Z_] -> Sample combiner. Recursion depth is limited.
+  [a-zA-Z_] -> Sample combiner. Recursion depth is limited. By prefixing the Sample name with !, seed will be ignored.
 === Fields ===
@@ Line 291: / Line 293: @@
       = -> checks the bit and handles the following actions, e.g. (B2=[3]|[5])
   D: (Dice roll)
-      Number in range 1-100. Checked if greaterthan random number, e.g. (D50=yes|no)
+      Number in range 1-100. Checked if greaterthan random number, e.g. (D50=yes|no). Ignored if seed is used.
       or 3 Numbers to generate random number in range param1-param2 in steps of param3 e.g. (D25,150,25)
   S, P: (node handling with S = @S, P = @P)
@@ Line 320: / Line 322: @@
 == Undocumented yet ==
 * splitRules
 ----
 [[Category:OXPDoc]]

@@ Line 85: / Line 85: @@
 == Examples of usage ==
 === Simple ===
-{{CodeEx|codeex=var a = worldScripts.Cabal_Common_PhraseGen.makePhrase("CCL_Names");}}
+ var a = worldScripts.Cabal_Common_PhraseGen.makePhrase("CCL_Names");
 === Simple with specific Pattern ===
-{{CodeEx|codeex=var a = worldScripts.Cabal_Common_PhraseGen.makePhrase("CCL_Names","1 {12");}}
+ var a = worldScripts.Cabal_Common_PhraseGen.makePhrase("CCL_Names","1 {12");
 === Own Samples ===
-{{CodeEx|codeex=var b = {<br>
+ var b = {
-&nbsp;fieldA:["hello"],fieldB:["world"],fieldC:[],fieldD:[],fieldE:[],fieldF:[],fieldG:[],fieldH:[],fieldI:[],<br>
+   fieldA:["hello"],fieldB:["world"],fieldC:[],fieldD:[],fieldE:[],fieldF:[],fieldG:[],fieldH:[],fieldI:[],
-&nbsp;fieldJ:[],fieldK:[],fieldL:[],fieldM:[],fieldN:[],fieldO:[],fieldP:[],fieldQ:[],fieldR:[],sentences:["1 2!"]<br>
+   fieldJ:[],fieldK:[],fieldL:[],fieldM:[],fieldN:[],fieldO:[],fieldP:[],fieldQ:[],fieldR:[],sentences:["1 2!"]
-};<br>
+ };
-var a = worldScripts.Cabal_Common_PhraseGen.makePhrase(b);
+ var a = worldScripts.Cabal_Common_PhraseGen.makePhrase(b);
 }}
@@ Line 129: / Line 149: @@
-=== addSet() ===
+=== addSample() ===
 {{CodeEx|codeex=var a = worldScripts.Cabal_Common_PhraseGen.addSet( samplename, obj [,clone] );}}
-For adding data to the pool there are two possible ways.
+For adding data to the Sample pool there are two possible ways.
 '''Parameters:'''
@@ Line 301: / Line 321: @@
 * splitRules
 * custom Sample settings
 ----
 [[Category:OXPDoc]]

@@ Line 261: / Line 261: @@
 Syntax:
   Must be enclosed by round brackets.
   B: (Bitmask)
     Number 0-24
@@ Line 287: / Line 290: @@
       > -> greaterthan
       ! -> not equal
   actions:
     = -> identifies the actions

@@ Line 27: / Line 27: @@
 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 [[#Field combiner|related to each other]] and even a [[#Conditional|conditional markup]] is processed (recursion depth is limited). Samples can additionally use other more specialized Samples, e.g. to create names (again recursion depth is limited).
-All Samples have the same form:
+All Samples have the same form (although some may have more members):
   SampleName: {
     fieldA: [],
@@ Line 36: / Line 36: @@
     sentences: []
+  }
-The Fields A-I are treated as row1, J-R as row2.
+The Fields A-I (1-9) are treated as row1, J-R (10-18) as row2.
@@ Line 97: / Line 101: @@
 == Properties ==
 === recGuard ===
-Boolean. Recursion depth guard. If depth limit is reached it will spit out warnings.
+Boolean. Recursion depth guard. If depth limit is reached it will spit out warnings. The Helper tool has a option to enable it.
@@ Line 169: / Line 173: @@
   @X -> Select random system
   @W -> Random full name *
   @Z -> Random Brew name *
   @a -> Random Roman Numerals
@@ Line 257: / Line 262: @@
   Must be enclosed by round brackets.
   B: (Bitmask)
-    Number 0-9
+    Number 0-24
     operators:
       + -> sets the bit, e.g. (B2+)
@@ Line 285: / Line 290: @@
     = -> identifies the actions
     | -> separator matched / not matched
 ----
 [[Category:OXPDoc]]

← Older revision		Revision as of 12:32, 14 August 2013
Line 80:		Line 80:

	== Examples of usage ==		== Examples of usage ==
−	~~To be written next~~...	+	=== Simple ===
		+	{{CodeEx\|codeex=var a = worldScripts.Cabal_Common_PhraseGen.makePhrase("CCL_Names");}}
		+
		+	=== Simple with specific Pattern ===
		+	{{CodeEx\|codeex=var a = worldScripts.Cabal_Common_PhraseGen.makePhrase("CCL_Names","1 {12");}}
		+
		+	=== Own Samples ===
		+	{{CodeEx\|codeex=var b = {<br>
		+	fieldA:["hello"],fieldB:["world"],fieldC:[],fieldD:[],fieldE:[],fieldF:[],fieldG:[],fieldH:[],fieldI:[],<br>
		+	fieldJ:[],fieldK:[],fieldL:[],fieldM:[],fieldN:[],fieldO:[],fieldP:[],fieldQ:[],fieldR:[],sentences:["1 2!"]<br>
		+	};<br>
		+	var a = worldScripts.Cabal_Common_PhraseGen.makePhrase(b);
		+	}}

@@ Line 10: / Line 10: @@
 * the build script (Cabal_Common_PhraseGen.js) which prefills some lists, processes OXP input and handles the rules.
 * the helper script (PhraseGen.js) which does the communication between HTML and build script. This is not used in Oolite.
 == How it works ==
-CCL_PhraseGen uses a collection (a Sample) of words, sylables or phrases which are ordered in 18 available arrays (Fields) and a special array which controls how these should be combined (Pattern). Fields and Patterns have their own set of rules (e.g. to control pluralization). Fields can hold lots of single words or even complete sentences and, basically, entries in Fields are selected randomly.
+CCL_PhraseGen uses a collection (a [[#Samples|Sample]]) of words, sylables or phrases which are ordered in 18 available arrays ([[#Fields|Fields]]) and a special array which controls how these should be combined ([[#Patterns|Pattern]]). Fields and Patterns have their own set of rules (e.g. to control pluralization). Fields can hold lots of single words or even complete sentences and, basically, entries in Fields are selected randomly.
 You can imagine a Sample as a wardrobe with drawers. The Pattern controls which drawer gets opened and the script picks one item out of it and attaches it to the final output before it walks further over the Pattern.
@@ Line 19: / Line 21: @@
 The script simply replaces the numbers (1-9) in the Pattern with content from the Field 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).
+Switching between Field 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|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).
+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 [[#Field combiner|related to each other]] and even a [[#Conditional|conditional markup]] is processed (recursion depth is limited). Samples can additionally use other more specialized Samples, e.g. to create names (again recursion depth is limited).
 All Samples have the same form:
@@ Line 35: / Line 37: @@
+  }
 The Fields A-I are treated as row1, J-R as row2.

@@ Line 3: / Line 3: @@
 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 with lots of additional features. It uses 3 scripts:
+Generating meaningful sentences from a pool of available words is hard to achieve, combining lots of available words often needs thinking, planning and pen and paper work before it gets halfway useable (or pretty complex tools).
-* the data script (Cabal_Common_PhraseGenWords.js) holds a few objects only (words, samples, irregular nouns, irregular verbs and superlatives).
+CCL_PhraseGen is a tool to aid OXP developers in this process and also implements a way to use these presets in the game itself. It works similiar to other random mechanisms on the net with lots of additional features and uses the 'soft' references in JS.
 * the build script (Cabal_Common_PhraseGen.js) which prefills some lists, processes OXP input and handles the rules.
 * the helper script (PhraseGen.js) 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 samples. 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|RandomShipNames.oxp]]. The concept is basically using the 'soft' references in JS.
+== How it works ==
-Every sample contains 18 arrays with words (or phrases) and 1 array with sentence patterns.
+You can imagine a Sample as a wardrobe with drawers. The Pattern controls which drawer gets opened and the script picks one item out of it and attaches it to the final output before it walks further over the Pattern.
-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.
+The script simply replaces the numbers (1-9) in the Pattern with content from the Field 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).
+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).
+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 samples have the same form:
+All Samples have the same form:
   SampleName: {
     fieldA: [],
@@ Line 35: / Line 34: @@
     sentences: []
+  }
-The fields A-I are treated as row1, J-R as row2.
+The Fields A-I are treated as row1, J-R as row2.
@@ Line 50: / Line 49: @@
 '''Parameters:'''
 :;samplename: String/Object.
-:::String: PhraseGen looks up if the pool contains a sample with this name.
+:::String: PhraseGen looks up if the pool contains a Sample 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 sample.
+:;pattern: String/Array. Optional. If not specified PhraseGen will use a randomly choosen pattern from the current Sample.
 :::String: Pattern.
 :::Array: PhraseGen will randomly choose a element.
@@ Line 73: / Line 72: @@
 '''Parameters:'''
-:;samplename:String. Unique identifier for the sample. Probably the easist way is to use OXPName_SetID.
+:;samplename:String. Unique identifier for the Sample. Probably the easist way is to use OXPName_SetID.
-:;obj:Object. Holds the arrays with words and patterns.
+:;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 sample was placed, otherwise false.
+:;success:Boolean. True if Sample was placed, otherwise false.
@@ Line 86: / Line 85: @@
 === Patterns ===
 Patterns are simple strings to control the sentence building. They can contain plain text, control chars
-or [[#Conditional|conditional checks]] (with [[#Field combiner|field combiners]] or words/phrases as actions). The script replaces numers (in range 1-9) with content from the samples field arrays.
+or [[#Conditional|conditional checks]] (with [[#Field combiner|Field combiners]] or words/phrases as actions). The script replaces numers (in range 1-9) with content from the Samples Field arrays.
   First letter and next word after . ! or ? is capitalized
   + -> Forces capitalization
-  } -> Forces fields 1-9
+  } -> Forces Fields 1-9
-  { -> Forces fields 10-18
+  { -> Forces Fields 10-18
   > -> Applies plural rules
   < -> Applies singular rules (probably obsolete)
@@ Line 134: / Line 133: @@
 === Fields ===
-Fields can contain plain text, [[#Field combiner|field combiners]] or [[#Conditional|conditional checks]].
+Fields can contain plain text, [[#Field combiner|Field combiners]] or [[#Conditional|conditional checks]].
   $ -> identifies verb (e.g. decide$)
@@ Line 178: / Line 177: @@
 === Field combiner ===
-Field combiner are used to place content of fields of the same row in other fields.
+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). Recursion depth is limited.
+The rows are Field 1-9 (A-I) and Field 10-18 (J-R). Recursion depth is limited.
-  [#] -> field combiner
+  [#] -> Field combiner
 === Conditional ===
@@ Line 187: / Line 186: @@
 After <tt>.startUp</tt> and <tt>.playerEnteredNewGalaxy</tt> PhraseGen stores the 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 the nodes values. E.g.
+These nodes are used to compare the instructions in Fields and Patterns against the nodes values. E.g.
   (Sg>0,e!5=[7]|[6])
@@ Line 194: / Line 193: @@
   fieldC (Se>0=[7]|[6])
-Multiple checks in the same field are supported
+Multiple checks in the same Field are supported
   The (Sg>0=standard|anarchy) system is (Se>4=agricultural|industrial)