Open main menu

Difference between revisions of "AGIWiki/Message"

No change in size ,  18:58, 21 September 2016
m
syntax -> source
(fixing link)
m (syntax -> source)
Line 2: Line 2:


A '''message''' is a string of text that is used by commands like [[AGIWiki/Print|print]] to give the user information. Each [[AGIWiki/Logic|logic resource]] can contain up to 255 messages, with message numbers starting from 1 and going to 255. A message can also be as long as you like; however, there are practical limitations to this. See the [[AGIWiki/Message too verbose error|message too verbose error]]. Messages can be defined implicitly or explicitly. An explicit message definition uses the <code>#message</code> command:
A '''message''' is a string of text that is used by commands like [[AGIWiki/Print|print]] to give the user information. Each [[AGIWiki/Logic|logic resource]] can contain up to 255 messages, with message numbers starting from 1 and going to 255. A message can also be as long as you like; however, there are practical limitations to this. See the [[AGIWiki/Message too verbose error|message too verbose error]]. Messages can be defined implicitly or explicitly. An explicit message definition uses the <code>#message</code> command:
<syntax type="C++">
<source lang="cpp">
#message 2 "He's not here."
#message 2 "He's not here."
</syntax>
</source>
This sets the text of message 2, or <code>m2</code>, to "He's not here." Messages are implicitly defined when they do not appear in any <code>#message</code> command but do appear within a print command:
This sets the text of message 2, or <code>m2</code>, to "He's not here." Messages are implicitly defined when they do not appear in any <code>#message</code> command but do appear within a print command:
<syntax type="C++">
<source lang="cpp">
print("He's not here.");
print("He's not here.");
</syntax>
</source>
When a message is implicitly defined in this manner, the compiler will essentially add a <code>#message</code> command to the logic, but it will be invisible. Although possible, it is not generally practical to find out which message number is assigned to the message. Furthermore, additional implicit assignments in the logic file can change which message number is assigned to it. If you need to know the number of a message for sure, use an explicit message definition.
When a message is implicitly defined in this manner, the compiler will essentially add a <code>#message</code> command to the logic, but it will be invisible. Although possible, it is not generally practical to find out which message number is assigned to the message. Furthermore, additional implicit assignments in the logic file can change which message number is assigned to it. If you need to know the number of a message for sure, use an explicit message definition.


If you use an explicit message definition such as the one shown previously, you can print the message by either duplicating the message in full or specifying the message number:
If you use an explicit message definition such as the one shown previously, you can print the message by either duplicating the message in full or specifying the message number:
<syntax type="C++">
<source lang="cpp">
print("He's not here.");
print("He's not here.");
print(m2);
print(m2);
</syntax>
</source>
As you might expect, there are advantages and disadvantages to both methods of defining messages.
As you might expect, there are advantages and disadvantages to both methods of defining messages.


Line 29: Line 29:


You can refer to one message from within another by using message referencing. This is done by including %m and then the message number within the other message. For example:
You can refer to one message from within another by using message referencing. This is done by including %m and then the message number within the other message. For example:
<syntax type="C++">
<source lang="cpp">
#message 2 "He's not here."
#message 2 "He's not here."


print("%m2 But he'll be back soon.");
print("%m2 But he'll be back soon.");
</syntax>
</source>
The message is stored like this in the logic resource, but when the [[AGIWiki/Interpreter|interpreter]] displays it, it will replace <code>%m2</code> with message 2, so the text "He’s not here. But he’ll be back soon." will be displayed. See [[AGIWiki/Message#Building messages|Building messages]] for more details.
The message is stored like this in the logic resource, but when the [[AGIWiki/Interpreter|interpreter]] displays it, it will replace <code>%m2</code> with message 2, so the text "He’s not here. But he’ll be back soon." will be displayed. See [[AGIWiki/Message#Building messages|Building messages]] for more details.


Line 39: Line 39:


For an example where explicitly defining a message can avoid code duplication, let's take a simple "You're not close enough." message that occurs commonly in [[AGIWiki/AGI|AGI]] games.
For an example where explicitly defining a message can avoid code duplication, let's take a simple "You're not close enough." message that occurs commonly in [[AGIWiki/AGI|AGI]] games.
<syntax type="C++">
<source lang="cpp">
if (said("get", "cat"))
if (said("get", "cat"))
{
{
Line 55: Line 55:
     }
     }
}
}
</syntax>
</source>
Obviously here we've got some duplicate code: print("You're not close enough.");. At first glance, using explicit messages can provide a small advantage:
Obviously here we've got some duplicate code: print("You're not close enough.");. At first glance, using explicit messages can provide a small advantage:
<syntax type="C++">
<source lang="cpp">
if (said("get", "cat"))
if (said("get", "cat"))
{
{
Line 75: Line 75:


#message 1 "You're not close enough."
#message 1 "You're not close enough."
</syntax>
</source>


Or, using [[AGIWiki/Defines|defines]]:
Or, using [[AGIWiki/Defines|defines]]:
<syntax type="C++">
<source lang="cpp">
#define NotCloseEnough m1
#define NotCloseEnough m1


Line 98: Line 98:


#message 1 "You're not close enough."
#message 1 "You're not close enough."
</syntax>
</source>


Obviously, either example saves a few keystrokes, but it also provides another advantage. Suppose you want to change your "not close enough" message to read "You're too far away." In the original code, where the message is implicitly defined, you will have to search and replace in your code for every place where the text "You're not close enough." appears.
Obviously, either example saves a few keystrokes, but it also provides another advantage. Suppose you want to change your "not close enough" message to read "You're too far away." In the original code, where the message is implicitly defined, you will have to search and replace in your code for every place where the text "You're not close enough." appears.
<syntax type="C++">
<source lang="cpp">
if (said("get", "cat"))
if (said("get", "cat"))
{
{
Line 117: Line 117:
     }
     }
}
}
</syntax>
</source>


The danger that is not necessarily obvious here is that if you miss one or make a typo, you will accidently create a new implicitly-defined message!
The danger that is not necessarily obvious here is that if you miss one or make a typo, you will accidently create a new implicitly-defined message!
<syntax type="C++">
<source lang="cpp">
if (said("get", "cat"))
if (said("get", "cat"))
{
{
Line 138: Line 138:
     }
     }
}
}
</syntax>
</source>
Using explicit message definitions allows the change to be made in just one place: the message definition.
Using explicit message definitions allows the change to be made in just one place: the message definition.
<syntax type="C++">
<source lang="cpp">
#define NotCloseEnough m1
#define NotCloseEnough m1


Line 160: Line 160:


#message 1 "You're too far away." // changed
#message 1 "You're too far away." // changed
</syntax>
</source>


== Building messages ==
== Building messages ==
Line 191: Line 191:


=== Example ===
=== Example ===
<syntax type="C++">
<source lang="cpp">
v255 = 20;
v255 = 20;
print("The value of v255 is %v255.");
print("The value of v255 is %v255.");
</syntax>
</source>
This code will print the message "The value of v255 is 20."
This code will print the message "The value of v255 is 20."


Line 202: Line 202:


Take the following code from logic 0 of the [[AGIWiki/AGI Studio Template Game|AGI Studio Template Game]], which informs the player that he or she used a word that the game doesn't understand:
Take the following code from logic 0 of the [[AGIWiki/AGI Studio Template Game|AGI Studio Template Game]], which informs the player that he or she used a word that the game doesn't understand:
<syntax type="C++">
<source lang="cpp">
if (input_recieved &&
if (input_recieved &&
     unknown_word_no > 0) {
     unknown_word_no > 0) {
Line 225: Line 225:
   }
   }
}
}
</syntax>
</source>


This code is in fact wasting a few dozen bytes of memory. Although this does not seem like much, in a programming environment like AGI where memory is a precious resource, these bytes can make a difference. When the compiler sees this code, it will generate invisible message definitions similar to the following:
This code is in fact wasting a few dozen bytes of memory. Although this does not seem like much, in a programming environment like AGI where memory is a precious resource, these bytes can make a difference. When the compiler sees this code, it will generate invisible message definitions similar to the following:
<syntax type="C++">
<source lang="cpp">
#message 10 "I don't understand \"%w1\""
#message 10 "I don't understand \"%w1\""
#message 11 "\"%w2\" is not in my vocabulary."
#message 11 "\"%w2\" is not in my vocabulary."
Line 235: Line 235:
#message 14 "\"%w5\" is not in my vocabulary."
#message 14 "\"%w5\" is not in my vocabulary."
#message 15 "What is \"%w6\""
#message 15 "What is \"%w6\""
</syntax>
</source>
'''Note:''' the message numbers were chosen arbitrarily and are not necessarily the message numbers that will be generated by the compiler.
'''Note:''' the message numbers were chosen arbitrarily and are not necessarily the message numbers that will be generated by the compiler.


Line 245: Line 245:


Each of these phrases appears in two of the messages above. Using explicit message definitions we can reduce the amount of memory used, as shown below:
Each of these phrases appears in two of the messages above. Using explicit message definitions we can reduce the amount of memory used, as shown below:
<syntax type="C++">
<source lang="cpp">
if (input_recieved &&
if (input_recieved &&
     unknown_word_no > 0) {
     unknown_word_no > 0) {
Line 272: Line 272:
#message 11 "\" is not in my vocabulary."
#message 11 "\" is not in my vocabulary."
#message 12 "What is \""
#message 12 "What is \""
</syntax>
</source>


'''Note:''' this code uses <code>%g</code><var>N</var> because the messages are defined in logic 0.
'''Note:''' this code uses <code>%g</code><var>N</var> because the messages are defined in logic 0.


This code does the exact same thing as the earlier code, but it uses less memory. The obvious disadvantage here is that the code is a little less readable. Unfortunately, this trade-off is somtimes necessary. You can use [[AGIWiki/Defines|defines]] to overcome it if you like. The advantage is that the compiler will now use something similar to the following message definitions:
This code does the exact same thing as the earlier code, but it uses less memory. The obvious disadvantage here is that the code is a little less readable. Unfortunately, this trade-off is somtimes necessary. You can use [[AGIWiki/Defines|defines]] to overcome it if you like. The advantage is that the compiler will now use something similar to the following message definitions:
<syntax type="C++">
<source lang="cpp">
#message 10 "I don't understand \""
#message 10 "I don't understand \""
#message 11 "\" is not in my vocabulary."
#message 11 "\" is not in my vocabulary."
Line 287: Line 287:
#message 17 "\"%w5%g11"
#message 17 "\"%w5%g11"
#message 18 "%g12%w6\""
#message 18 "%g12%w6\""
</syntax>
</source>
The next obvious question is how much memory this actually saves. Because the message numbers are chosen at random and do not necessarily reflect what the real message numbers would be, this figure is not necessarily exact (you will have to give or take 6 bytes):
The next obvious question is how much memory this actually saves. Because the message numbers are chosen at random and do not necessarily reflect what the real message numbers would be, this figure is not necessarily exact (you will have to give or take 6 bytes):


885

edits