require

declaration/definition

Syntax
require (function function-signature)
        | (global name)
        | (constant name)
        | (catch catch-declaration)
        | (opaque type-name)


Purpose

You can use require within a module to specify a function, variable, constant, catch, opaque data types, or record type that must be provided by the program that imports the module.

The importing program must supply the required item using a supply statement as part of the import declaration. The module may then use the name specified in the require statement to access the item in the main program.

Requiring a function

To require a function, specify the function definition without a function body or an as or elsewhere and with the word require in place of the word define: 

  require integer function add
   (value integer x,
    value integer y)

You cannot require an overloaded or dynamic function.

The program or module that imports this module must supply a function in the import statement. The supplied function must match the required function in all respects except its name and the name of its arguments (though the return type of the supplied function may be an extension of the return type of the required function): 

  define integer function sum
   (value integer a,
    value integer b)
   as
     return a+b
  
  import "test.xmd" unprefixed
   supply sum as add

Requiring a variable or constant

To require a variable or constant, provide a variable or constant declaration preceded by require: 

  require global integer foo
  require constant stream bar

The program or module that imports this module must supply the required variable or constant in the import statement. The supplied variable or constant must match the type required, but the supply statement can specify a different name: 

  global integer x
  constant stream y initial {"Hello World"}
  
  import "test.xmd" unprefixed
   supply x as foo
   supply y as bar

Requiring a catch

To require a catch, provide a catch declaration with the word declare replaced by the word require: 

  require catch rats
   value string curses

The program or module that imports this module must supply the required catch in the import statement. As with a required function, the supplied catch must match the type required, except for its name and the names of its arguments: 

  declare catch oh-dear
   value string tale-of-woe
  
  import "test.xmd" unprefixed
   supply oh-dear as rats

Requiring a type

To require a type, provide a type name preceded by the words require opaque. Note that the type name you specify is not the name of an existing type, but the name by which the type supplied by the importing program will be known in your module: 

  require opaque storage

The program or module that imports this module must supply the required type in the import statement: 

  declare record container
   field stream name
   field stream address
   field stream contents
  
  import "test.xmd" unprefixed
   supply container as storage

When you supply a type to a module it must be supplied as opaque. This means that the module can create instances of the type, can accept shelves of that type as function arguments, and can return the type from functions, but it cannot access the fields of variables of that type or discover any information about the type or variables of that type.

You can also supply an OMX type to a required opaque using the same mechanism.

Related Syntax
Related Concepts