Vision Messages

The basic rules for message definition are presented in the document Vision Fundamentals. This document presents a much more detailed description of message definition and management.

Review

Messages provide the basic mechanism for interacting with objects.

Four types of message can be defined:

A message is a request for an object to return the value of one of its properties or execute one of its methods. You do not need to know what type of message has been defined in order to use the message. In all cases, the form:

  object messageName

is used to request that the recipient object carry out the specific function indicated by the message.

To view a method, you prepend the : character to the message:

  Number :absoluteValue

This displays the definition of the method absoluteValue instead of evaluating it. If you wish to display the definition of a method that has multiple parameters, you must supply "dummy" values for each parameter. For example, the expression:

  Number :log: 0

displays the definition of the log: method. If the method has several parameters, you only need to place the ":" in front of the first one to display its contents, but you must supply a value for each parameter.

There is a special type of message known as a Primitive. Primitive messages are defined as part of the process of bootstrapping a Vision database. The implementation for a Primitive cannot be viewed. Instead you will see the name of the primitive as illustrated below:

  Object :do: 0

displays:

  <SendForExecution>

The message selectorList can be sent to any object and returns a list of String objects representing the messages that have been defined directly at the recipient object's class. For example, the expression:

  Number selectorList do: [ printNL ] ;

returns and prints a list that includes the strings "absoluteValue" and "log:". The list does not include messages that are defined at the object's super classes.

Message Descriptors

The class Schema MessageImplementationDescriptor is used to maintain information about the messages in your Vision database. Each instance of Schema MessageImplementationDescriptor corresponds to a specific message in the Vision database. These instances track information about the message itself including its type, function, and description, as well as tracking changes to methods over time.

New instances of the Schema MessageImplementationDescriptor class are NOT created automatically. Each time you use one of the define messages, the class is flagged to indicate that new messages are pending. To process and refresh all messages, execute the expression:

  Schema processAllMessages

This process creates and refreshes message descriptors in the Schema database as needed. Depending on the number of messages that have been defined since the last time this processing was run, the update time will range from a few seconds to a few minutes. In general, you will probably want to incorporate this procedure into a standard nightly update.

The expression:

  object getMessage: "message"

is used to access the descriptor associated with a specific implementation of a message. This message returns an instance of the class Schema MessageImplementationDescriptor. The messages displayInfo and describe display useful information about this message in a short and long format. For example, the expression:

  Number getMessage: "absoluteValue" . describe

displays a report in the form:

  Message:                 absoluteValue
  Class:                   Number
  Created:                 10/30/1992
  Updated:                 10/30/1992
  Function Type:                 NA 
  Returns:                 Object
  Implementation Type:     Method
  {|absoluteValue|
  ^self < 0 ifTrue: [^self negated]
  ifFalse: [^self]}

Access Techniques

The expression:

  object showMessages

can be used to display all the messages defined for the object directly. If the recipient object contains extensions, messages defined at each extension are displayed first. Messages that have been created or changed since the last Schema database update are flagged.

For example, the expression:

  Number showMessages

produces:

  Messages Defined At Class: Number
  !=                            Method
  >                             Method
  >=                            Method
  absoluteValue                 Method
  arcCosine                     Method
  arcSine                       Method
  arcTangent                    Method
  asAPowerOf:                   Method
  asDate                        Method

The expression:

  Object showMessagesX

can be used to display all the messages defined for the object and any of its super classes excluding Object. Messages that have not been posted to the Schema database are also excluded. For example, the expression:

  Number showMessagesX

produces:

  Messages Defined In Class Hierarchy Of: Number
    --> Excludes Messages Defined At Object 

  Message                            Type         Defined At
  -----------------------------------------------------------
  !=                                 Method       Number
  <                                  Method       Ordinal
  <=                                 Method       Ordinal
  >                                  Method       Ordinal
  >                                  Method       Number
  >=                                 Method       Ordinal
  >=                                 Method       Number
  absoluteValue                      Method       Number
  . . . 
  whatAmI                            Constant     Ordinal
  whatAmI                            Constant     Number
  within:percentOf:                  Method       Number

The expression:

  object showProperties

can be used to display all the fixed and time series properties defined for the object and any of its super classes. Messages that have not been posted are excluded from this report. For example, the expression:

  Object showProperties

produces:

  Properties Defined In Class Hierarchy Of: Object
    --> Excludes New Messages Not In Schema

  Message                            Type         Defined At
  -----------------------------------------------------------
  baseObject                         Fixed        Object
  code                               Fixed        Object
  creationDate                       Fixed        Object
  defaultFlag                        Fixed        Object

The expression:

  object showMessagesDefining: "message"

displays a list of all implementations of the supplied message defined for the object or any of its super or sub classes. For example, the expression:

  Object showMessagesDefining: "="

shows all the classes that have re-defined the "=" messages as illustrated below:

  Message                            Type         Defined At
  -----------------------------------------------------------
  =                                  Method       Date
  =                                  Primitive    Double
  =                                  Primitive    Float
  =                                  Primitive    Integer
  =                                  Primitive    Object
  =                                  Primitive    String
  =                                  Method       Utility UnixSeconds

The expression:

  Number showMessagesDefining: "="

shows only the classes related to Number that have redefined this message:

  Message                            Type         Defined At
  -----------------------------------------------------------
  =                                  Primitive    Double
  =                                  Primitive    Float
  =                                  Primitive    Integer
  =                                  Primitive    Object

The expression:

  object showMessageNamesContaining: "substring"

displays a list of all messages defined for the object or any of its super or sub classes that contain the supplied substring as part of their message name. For example, the expression:

  Object showMessageNamesContaining: "showM"

lists all the message names that contain the string "showM" as illustrated below:

  Message                            Type         Defined At
  -----------------------------------------------------------
  showMessageNamesContaining:        Method       Object
  showMessageSummaryFor:             Method       Object
  showMessages                       Method       Object
  showMessagesDefining:              Method       Object
  showMessagesUsing:                 Method       Object
  showMessagesX                      Method       Object
  showMethodsUsing:                  Method       Object

The substring argument can contain wild-card characters suitable for your machine. For example, on Unix machines you can restrict the search to messages beginning with the string "show" by using the substring "^show".

The expression:

  object showMessagesUsing: "string"

displays a list of all implementations defined for the object or any of its super or sub classes that contain the supplied substring as part of its method definition. For example, the expression:

  Object showMessagesUsing: "asDate"

lists all methods that use the message asDate as illustrated below:

  Message                            Type         Defined At
  -----------------------------------------------------------
  *                                  Method       DateOffset
  +                                  Method       DateOffset
  asCurrentYearMMDD                  Method       Date
  asDate                             Method       DateOffset
  asDate                             Method       Number
  asDate                             Method       Integer
  asDateFromMMDD                     Method       Integer
  asDateFromMMDDYY                   Method       Integer
  . . .

The expression:

  Object showMethodsUsing: "asDate"

displays the actual method for each implementation found.

Most of the "show" messages have a "get" equivalent which returns a list of Schema MessageImplementationDescriptor instances instead of displaying them. You can use any of the list messages on this result. For example:

  Object getMessagesUsing: "asDate" .
  do: [ displayInfo ] ;

The following messages have been defined to return a list of Schema MessageImplementationDescriptor instances:

getMessages
getMessagesX
getMessagesInInheritancePath
getMessagesDefining: string
getMessageNamesContaining: string
getMessagesUsing: string

Viewing Method History

The expression:

  Schema processAllMessages

is used to update the Schema classes with all new and changed methods. To find the last time a message was updated use:

  Number getMessage: "absoluteValue" . updateDate

To display all the messages defined at the class Number that have changed since 3 months ago, use:

  Number getMessages select: [ updateDate > ^today - 3 months ] .
  do: [ displayInfo ] ;

Prior versions of methods are preserved in the time series property implementationSource. To display the implementation history for a particular method use:

  Number getMessage: "absoluteValue" .
  :implementationSource     #- returns time series of strings
  do: [ "Implementation As Of: " print; ^date printNL ;
        printNL ;           #- displays implementation
        "-" fill: 50 . printNL ;
      ] ;

Preserving Method Format

The expression:

  class defineMethod:
  "[ | selector |
   #--  Code follows this line
   #--  End of code
  ]"

is identical to the defineMethod: message except that the parameter is provided as a string. In this form, the Schema tools are able to preserve all comments and formatting defined within the method. For example, the expression:

  Number  defineMethod:
  "[ | absoluteValue |
  #--  this version has comments and indentation
    ^self < 0    # do the test
      ifTrue: [ ^self negated ]
     ifFalse: [ ^self ]
  ] " ;

can be used to redefine the absoluteValue message at Number to include comments. To confirm the new implementation, describe it again:

  Number getMessage: "absoluteValue" . describe

  Message:                 absoluteValue
  Class:                   Number
  Created:                 10/30/1992
  Updated:                 10/30/1992
  Function Type:           Calc
  Returns the absolute value of the recipient
  Returns:                 Number
  Implementation Type:     Method
  [ | absoluteValue |
  #--  this version has comments and indentation
    ^self < 0    # do the test
      ifTrue: [ ^self negated ]
     ifFalse: [ ^self ]
  ]

Notice that the method's comments and format have been preserved.

If your method includes the quote (") character, you must precede it with the backslash character (\) if you define your method as a string. For example:

  Entity defineMethod:
  "[ | describe |
     #--  print label in quotes; the " must be preceded by \
     \"Code: \" print: 15 ; code printNL ; 
     \"Name: \" print: 15 ; name printNL ;
   ] " ;

The quotes used within the method must be preceded by the \ character so that they can be distinguished from the quote used to end the method definition.

Setting Default Property Values

When a property is defined for a class using the defineFixedProperty: or define: message, the initial value of the property is NA for all instances of the class and for any new instance when it is created. The expression:

  class defineFixedProperty: 'name' withDefault: object

  class define: 'name' withDefault: object

runs the defineFixedProperty: or define: message and sets the default value in the associated message implementation descriptor to the supplied object. All existing instances are initialized to have this value. In addition, this property will be set to this default value as part of the execution of the createInstance method. For example:

  !NewClass <- Object createSubclass ;
  NewClass defineFixedProperty: 'p' withDefault: 10 ;
  !NewInstance <- NewClass createInstance ;
  NewInstance p print ;

displays the value 10.

Adding Descriptive Information

Several messages are available for updating descriptive information about a message including:

setDescriptionTo: string
setReturnObjectTypeTo: class
setDefaultValueTo: object
clearDefaultValue
setFunctionTypeTo: string

The message setDescriptionTo: is used to store a text string that describes the purpose of the message. This string can contain new line characters. The message setReturnObjectTypeTo: is used to define the type of object returned by this message. By default this value is set to Object. The setDefaultValueTo: message is used to provide a default value for a property that is used to initialize new instances. The clearDefaultValue message is used to remove the default value. Values in existing instances are not changed by these messages. The setFunctionTypeTo: message is used to provide an additional level of classification for cross-referencing messages.

All of these messages return the current message implementation descriptor and can therefore be streamed together. For example, to add descriptive information to the absoluteValue message defined at Number:

  Number getMessage: "absoluteValue" .
     setDescriptionTo: "Returns the absolute value of the recipient" .
     setReturnObjectTypeTo: Number .
     setFunctionTypeTo: "Calc" .
     describe ;

producing:

  Message:                 absoluteValue
  Class:                   Number
  Created:                 10/30/1992
  Updated:                 10/30/1992
  Function Type:           Calc
  Returns the absolute value of the recipient
  Returns:                 Number
  Implementation Type:     Method
  {|absoluteValue|
  ^self < 0 ifTrue: [^self negated]
  ifFalse: [^self]}

Deleting Messages

The deleteMessage: message is used to delete a message from a class. The general form for message deletion is:

  object deleteMessage: "message"

Review

Message Descriptors

Access Techniques

Viewing Method History

Preserving Method Format

Setting Default Property Values

Adding Descriptive Information

Deleting Messages

Related Topics