3.5. ::METHOD

The ::METHOD directive creates a method object and defines the method attributes.

A ::METHOD directive creates method objects that may be associated with a class instance. The created method may be from Rexx code, mapped to method in an external native library, or automatically generated. The type of method is determined by the combination of options specified.

The methodname is a literal string or a symbol that is taken as a constant. The method is defined as methodname in the class specified in the most recent ::CLASS directive. Only one ::METHOD directive can appear for any methodname in a class.

A ::CLASS directive is not required before a ::METHOD directive. If no ::CLASS directive precedes ::METHOD, the method is not associated with a class but is accessible to the main (executable) part of a program through the .METHODS built-in object. Only one ::METHOD directive can appear for any method name not associated with a class.

If you specify the CLASS option, the method is a class method. See Chapter 4, Objects and Classes. The method is associated with the class specified on the most recent ::CLASS directive. The ::METHOD directive must follow a ::CLASS directive when the CLASS option is used.

If ABSTRACT is specified, then the created method will be marked as an abstract method and will raise an error if directly invoked. For abstract methods there is no method code body following the directive, so another directive (or the end of the program) must follow the ::METHOD directive.

If ABSTRACT, ATTRIBUTE, DELEGATE, or EXTERNAL is not specified, the ::METHOD directive starts a section of method code which is ended by another directive or the end of the program. The ::METHOD is not included in the source of the created METHOD object.

Example 3.10. METHOD examples

r = .rectangle~new(20,10)
say "Area is" r~area       /* Produces "Area is 200" */

::class rectangle

::method area              /* defined for the RECTANGLE class */
  expose width height
  return width*height

::method init
  expose width height
  use arg width, height

::method perimeter
  expose width height
  return (width+height)*2

If you specify the ATTRIBUTE option, method variable accessor methods are created. In addition to generating a method named methodname, another method named methodname= is created. The first method returns the value of object instance variable that matches the method name. The second method assigns a new value to the object instance variable.

For example, the directive

::method name attribute

creates two methods, NAME and NAME=, equivalent to the following code sequences:

::method name         -- attribute get method
  expose name         -- establish direct access to object variable (attribute)
  use strict arg      -- enforce zero parameters
  return name         -- return object variable's current value

::method "NAME="      -- attribute set method
  expose name         -- establish direct access to object variable (attribute)
  use strict arg name -- retrieve argument and assign it to the object variable

Using the ATTRIBUTE option is equivalent to using the ::ATTRIBUTE directive.

If you specify the ABSTRACT option, the method creates an ABSTRACT method placeholder. ABSTRACT methods define a method that an implementing subclass is expected to provide a concrete implementation for. Any attempt to invoke an ABSTRACT method directly will raise a SYNTAX condition.

If DELEGATE is specified, execution of method name is delegated to object delegatename. It is a common design pattern to delegate method execution to an embedded object. The directive for such a delegation

::method name delegate delegateName

is equivalent to the following code sequence:

Example 3.11. DELEGATE subkeyword equivalent code

::method name
expose delegateName
forward to(delegateName)

If the EXTERNAL option is specified, then spec identifies a method in an external native library that will be invoked as the named method. The spec is a literal string containing a series of whitespace delimited tokens defining the external method. The first token must be LIBRARY, which indicates the method resides in a native library of the type allowed on a ::REQUIRES directive. The second token must identify the name of the external library. The external library is located using platform-specific mechanisms for loading libraries. For Unix-like systems, the library name is case-sensitive. The third token is optional and specifies the name of the method within the library package. If not specified, the ::METHOD name is used. The target package method name is case insensitive.

Example 3.12. METHOD EXTERNAL examples

-- creates method INIT from method RegExp_Init in library rxregexp
::METHOD INIT EXTERNAL "LIBRARY rxregexp RegExp_Init"

-- creates method RegExp_Parse from library rxregexp
::METHOD RegExp_Parse EXTERNAL "LIBRARY rxregexp"

If the ATTRIBUTE option is specified with the EXTERNAL option, then two method objects need to be created. The target method name is appended to the string "GET" to derive the name of the getter attribute method. To generate the setter attribute method, the name is appended to the string "SET".

Example 3.13. METHOD EXTERNAL examples

-- maps "NAME" method to "GETNAME and
-- "NAME=" to "SETNAME"
::METHOD name ATTRIBUTE EXTERNAL "LIBRARY mylib"

-- maps "ADDRESS" method to "GETMyAddress and
-- "ADDRESS=" to "SETMyAddress"
::METHOD address ATTRIBUTE EXTERNAL "LIBRARY mylib MyAddress"

Notes:

You can specify all options in any order.
If you specify the PACKAGE option, the method is created with a package-scope, if you specify the PRIVATE option, the created method is a private method. Package-scope and private methods have restricted access rules on how they can be invoked. See Section 4.2.8, “Public, Package-Scope, and Private Methods” for details of how these methods can be used. If you omit the PACKAGE or PRIVATE option, or specify PUBLIC, the method is a public method that any sender can activate.
If you specify the UNGUARDED option, the method can be called while other methods are active on the same object. If you do not specify UNGUARDED, the method requires exclusive use of the object variable pool; it can run only if no other method that requires exclusive use of the object variable pool is active on the same object.
If you specify the PROTECTED option, the method is a protected method. (See Chapter 13, The Security Manager for more information.) If you omit the PROTECTED option or specify UNPROTECTED, the method is not protected.
If you specify ATTRIBUTE, ABSTRACT, or EXTERNAL, another directive (or the end of the program) must follow the ::METHOD directive.
It is an error to specify ::METHOD more than once within the same class and use the same methodname.