2.6. Importing Resources

While the Orc language itself is expressive, and the Standard Library offers a number of useful sites and functions, it is often necessary to extend the capabilities of a program by writing new sites, using existing Java or Scala code, or making use of Orc code written by other programmers. Orc has three declarations, one corresponding to each of these three use cases.

2.6.1. Writing Custom Sites

The import site declaration allows a custom site to be imported and used in an Orc program. There are specific requirements that must be met by such sites; these are described in detail in the reference manual.

Suppose one had written a custom site, implemented in the Java class my.example.site.ExampleSite. The following code would make it available as a site named Example in an Orc program:

import site Example = "my.example.site.ExampleSite"

2.6.2. Using Java Classes

The import class declaration allows a Java class to be used as if it were an Orc site. The class constructor is imported as a site, and calls to that site return new Java objects whose methods and fields may be accessed using the dot notation. The specific details of this conversion are documented in the reference manual.

The following code imports and uses Java's File, FileReader, and BufferedReader classes to read the first line of a text file.

import class File = "java.io.File"
import class FileReader = "java.io.FileReader"
import class BufferedReader = "java.io.BufferedReader"
val f = File("example.txt")
val reader = BufferedReader(FileReader(f))
reader.readLine()

2.6.3. Including Source Files

The include declaration reads a text file containing Orc declarations and includes those declarations in the program as if they had occurred at the point where the include declaration occurred. Any declarations may be included: val, def, import, or even other include declarations. This provides a primitive form of modularity, where Orc code shared by many programs may be centralized in one or more include files.

An include declaration may name any URL, not just a local file. Thus, useful include files can be shared over the Internet directly.

{- Retrieve an include file from the Orc website and print the example message declared there -}

include "http://orc.csres.utexas.edu/documentation/example.inc"
Println(example_message)