Coldread.exe 
A Cold Reading Production Engine 
Charles Shapiro 21 Dec 1997
Revised 20 Sep 1999


Overview

The coldread program will produce cold readings using numbers from
a variety of sources.  Numbers will be used to produce cold readings
by hashing into a file containing relevant sentences.  The first
coldread resource file will contain what is needed to produce a
standard cold reading such as any astrologer, graphologist, palmist,
or gypsy fortune teller can give.  Later resource files
could use the scales of the Minnesota Multiphasic Personality
Inventory. This will allow users to test various biometric,
astrological, or other personality tests conveniently against the
MMPI. See Appendix C for a sample of coldread.exe's output.

The Coldread resource file

On startup, coldread.exe will look for a resource file named on its
command line.  This resource file will contain all the information
coldread.exe needs to produce a cold reading except for the source
numbers and scales themselves.  The resource file is a flat ASCII file
containing the following kinds of lines:

* Data          any line which does not begin with a special character, or 
		which begins with a special character preceded by the "\" 
		special character, will be considered a possible sentence 
		to be output in a cold reading.

* comments   	any line beginning with a "#", "\n", or " " will be a comment.

* keywords	any line beginning with a "%" will be a keyword. Keywords are
                only important up to the first space.
* Comparisions	Any line beginning with "!"  or "(" will be a comparision 
		line. The coldread program will print the data line beneath it 
		if and only if (iff) the comparision is true.

Data lines will appear between keyword lines in ascending order --
that is, the lines corresponding to the smallest coldread input values
will appear closest to the start of the file.  If coldread encounters
a keyword in its template which it does not have a current scale
indicator for, it will skip the keyword. See Appendix A for a sample
coldread resource file. Keywords may occur without any corresponding data;
they will work as you expect. Nothing will print out in direct response
to the values passed to coldread for these keywords, but you can use them
in comparisions to determine if other phrases will print.

Comparisions

Comparisions are coldread resource lines which control comparisions
of coldread data to other coldread data or to a constant.  If the
comparision is true, then the coldread program will output the
sentence beneath the comparision.  If it is false or if one of the
data elements is undefined or not available, then the sentence will
always be skipped.

To compare a coldread input to a constant, start the comparision with
the keyword surrounded by "!".  The next element of the line must be
a relational operation, such as "=", "<",">" or "\=".  The element 
following that must be the number.  Hence, the following line:

	!trustworthy! > 40

would output its data sentence if the "trustworthy" input were
greater than forty. 

You can also compare a pair of coldread inputs, as:

!trustworthy! < !honest!

Or you can add and subtract coldread inputs to reach a conclusion:

!trustworthy! + !honest! > 40

Valid arithmetic operators are:

+  	Addition
-	Subtraction
/	Division
* 	Multiplication
** 	Exponentiation 
~	Modulo (that is, the remainder left after an integer division. Five 
	modulo three is equal to two)

Valid comparision operators are:

= 	Equal to
!= 	Not equal to
<	Left smaller than right
> 	Left larger than right
<=	Left smaller than or equal to right
>=	Left greater than or equal to right 

Comparisions can occur anywhere within the coldread parameter
file. Data prints out in the order in which it was placed in the
parameter file. If you check the first keyword against the last
keyword in the first line of the file, then the second line of the
file will print as the first sentence of your reading if the
comparision is true.  This will happen regardless of the order of the
data coldread reads.
	
Boolean Comparisions

You can also make boolean comparisions between pairs of comparisions.
This allows you to print sentences based the truth of various
assertions. For example, you can write expressions such as:

	(!Greedy! > 5) & (!Truthful! < 2)
	You would make a good salesman.

This expression would print the sentence "You would make a good
salesman." iff both the answer to the "Greedy" question was greater
than 5, and the answer to the "Truthful" question was less than 2.
Boolean comparisions only work between comparisions; "(!Greedy! > 4) =
(!Truthful! < 2)" will generate a parser error.

Valid boolean comparisions are:

	&	Both left and right side are true
	|	Either left or right side is true
	&|	Either left or right side is true, but not both.

Reserved keywords

Some keywords represent global information about the numbers coldread
has read.  These are automatically created and maintained by coldread;
they have no sentences associated with them, but you can use them in
comparisions to print your own sentences.  All coldread reserved words
begin and end with the underscore ("_") character. Future reserved
words will share this characteristic. It is wise to avoid this
construction in parameter files. There are three reserved words in this
version of coldread. They are:

	_Total_		Contains the total of all the numbers read by
			coldread
	_Average_	Contains the average of all the numbers read
			by coldread
	_Answers_	Contains the number of answers coldread has read. This
  		        could be smaller than the number of keywords in 
			the coldread parameter file.


The Coldread API

Coldread will read its readings from stdin.  Each reading will consist
of a line of ASCII text containing the following space-separated
elements:

* A keyword
* A scale maximum
* A scale minimum
* The current scale indicator

Boundaries and indicators must be integers in the range from 0 to 65535.
The coldread program will automatically scale the results to the
number of data lines in its coldread resource file in order to get the
coldread data line which comes closest to its input. Lines containing
keywords not present in the resource file will be ignored.  Lines for
which the maximum is smaller than the minimum will be ignored.  Lines
for which the current scale indicator falls outside of the maximum or
minimum will be ignored. See appendix B for a sample cold reading
produced by an arbitrary driver. The scale minimum must be one less than 
the minimum digit you expect in the file; hence, if your values will run from 
1 to 50, then the scale minimum will be 0.

Appendix A: A Sample coldread resource file

#This is a cold reading resource file.  It is designed to give an 
#equally valid, but different, cold reading for any set of coldread inputs.

%temperament%

You are often optimistic, but you are sometimes disappointed.
You are usually optimistic, but sometimes you are easily disappointed.
You are optimistic, but you are often disappointed.
You are optimistic by nature, but you are too easily disappointed.
You have been disappointed often, but you remain optimistic at heart.
Your temperment ranges from extremely optimistic, to extremely pessimistic.

%shyness%

You have a lot of friends, but few know the real you.
You have many acquaintances, but few close friends.
You have some acquaintances and a few very close friends.
You have some close friends, but very few know the real you.

!shyness! + !temperment! > 5
Nobody likes you anyway.

%avarice%

You are very careful with your money.
You are generally careful with your money, but you can spend a lot on what you really want.
You are generally careful with your money, but sometimes you spend more than you meant to.
You often spend more money than you intended to.

%planning%

You plan your affairs carefully.
You plan your affairs carefully, but sometimes find that your plans are not fulfilled.
You plan your affairs, but often your plans do not come out as you expect.
You sometimes plan your affairs carefully, but many times your plans do not come out as you expect.
You have planned your affairs sometimes, but you often can play it by ear.

%Conclusions%
!planning! + !avarice! > 5
You have trouble holding on to your savings.
!shyness! + !planning! < 4
You are secretive.
#End of file.

Appendix B: A sample cold reading

planning 5 0 4
temperment 7 0 6
shyness 12 0 11
avarice 100 0 75
conclusions 0 0 0

Appendix C: A sample cold reading output

You are optimistic by nature, but you are too easily disappointed. 
You sometimes plan your affairs carefully,  but many times your plans 
do not come out as you expect. You have some close friends, 
but very few know the real you. You are generally careful with 
your money, but sometimes you spend more than you meant to.
You have trouble hanging on to your savings. 
 
Appendix D: Possible enhancements


1) Section constants.  A constant preceded by an "at" ("@") character
   would be relative to the number of sentences in the 
   last mentioned section, rather than an absolute.  Hence, you could say:

	(!shyness! => @4) && (!avarice! < @5)
	You don't spend a lot of money at Christmastime.

   The first part of this logical test here would be true iff 
   the sentence printed at the "%shyness%" section was the fourth 
   or higher, and the last part would be true iff the sentence printed
   at the "%avarice%" section was before the fifth.  

   The language may be more flexible if section constants are described in
   some other way.  Perhaps preceding them with a section name:
   
	@shyness@4

   Or defaulting to the last-mentioned section and allowing this 
   syntax. 		

   This enhancement would allow you to write parameter files which were 
   independent of the scales used in coldread's input.
	
	
                        -- End --