Depot4 User Manual(5)

    previous         next         contents

The runtime support comprises the common base functionality for all the translators. Furthermore, there is a number of stubs for later enhancement. The modules of the runtime support belong into several groups:

Kernel:
contain the basic functionality of the parser and basic text handling
Dp4Base, Dp4Chars
Technical support:
runtime loading, global variable management, FLEX implementation
Dp4Tools, Dp4Translator
Logging:
error messages, warnings, other output
Dp4OP, Dp4Messages
Abstract input/output
definition of a basic class for stream source resp. target objects
Dp4Streams
Concrete input/output
this may vary with respect to the implementation platform
to expect at least: Dp4DocFiles (in essence, a simple wrapper), Dp4StrBuf (internal character stream buffer)
Other
defining an own configuration, symbol management
Dp4Config, Dp4AccTab, Dp4List
Extensions
useful functions but not essential for the principal application
Dp4xTrace, Dp4xCheck, Dp4xCount, Dp4xSTree

(Read "Dp4Xyz" as "Dp4.Xyz" for the Java version.)

5.2. User Interface

The application of language processor generators always knows to kinds of operation:

Generate the processor from a description, which will be referenced in the sequel as translation
Apply the generated processor on a stretch of the special language, referenced as use

Technically, there is no real difference between translation and use except, that in the translation step the generated target text, i.e. a program in the host language is immediately compiled.

In principle, Depot4 is a software very similar to an ordinary compiler. And as any compiler it can be used in different ways:

Development environment
Command line interface

5.2.1 Default development environment

There are the two modes of operation: translate and use. (In case of a compiler they are usually called compile and run.)

Translate is applied at Ml4 productions. It produces a host language program unit and, subsequentially, invokes the host language compiler on it. That's why error messages may be originate from different sources: the Ml4 translator and the host language compiler. The big number of possible faults is already caught by the translator. The most likely reasons for errors reported by the compiler are the use of host language keywords (such as do) as identifiers (may be caught in a future version) and parameter/type mismatch with imported objects.

Use is intended for application of generated translators. It expects a source (file, marked text, etc.) to process and the name of a production, which will be called first (root production).
There are some possibilities to influence such runs. Dp4Base offers a set of 16 flags that control how much information will be sent to the log. Further, significance of letter case may be switched on or off. There is also support for tracing, the invocation of productions, and checking against unbounded (left) recursion.

Module Dp4Config contains the code for a default configuration and users are explicitly invited to establish their own favorite settings there.

5.2.2 Direct use

In detail, every translation is composed from three parts:

Create a source object
Call the translator
Interpret the internal representation of the target

Step three may be omitted, if the language is to be interpreted only, i.e. the wanted actions are already embedded in the parsing code.

Step 1: Depot4 is designed as an extensible program without restricting its input. That's achieved by several mapping layers. Every source consists of a sequence of objects of (abstract) type Dp4Base.Token. So it is possible to combine different types of input objects (mostly but not restricted to different document files or defined parts of them) into one source. By default, there is one standard subtype StreamToken, which is in turn the parent type for all stream-like types, e.g., files, text areas, etc.
The default implementation modules for stream tokens (Dp4Files etc.) offer convenient procedures for the construction of appropriate objects.

Step 2: The core action is the calling of the translator. This is done by calling the translate procedure from Dp4Tools. It takes the source object as first parameter and the name of the root (string!) as second one. The result is a status (TRUE= input accepted vs. FALSE= parse failed) and (in the case of success) an internal representation of the generated target.
In more detail, a translation's runtime environment (e.g. the local substitution stacks) is contained in a Dp4Translator object. The runtime handles an implicit default translator object so there is no need to bother about this as long as there is no threading involved. In case of (possibly) more than one active translation thread it is recommended to have a dedicated translator object for each thread.

Step 3: The generated target is represented as an acyclic directed graph (ADG). Interpretation is a left-right, depth-first walk through this graph. Thereby the interpreter decides how to handle the different node types. By default there are only string nodes (containing a string of ASCII characters) and source nodes (containing the source and the start and end position of the source stretch to copy). The default interpreter just combines them into a stream of characters.

Example:

Java:

Dp4.trgts myTarget= Dp4.Tools.translate(Dp4.Files.IFile("Source.Ml4"), "MyRoot");
if (Dp4.Tools.isOk()) {
  Dp4.Streams.Tar2Strm(myTarget.trg1, Dp4.FileTrg.New("TARGET.T1")); // store it to a file
} else {
  // report an error
}

5.3. Input/output

Depot4 was designed as an extensible language processor. That's why input and output are (multiple) mapped. So, it should be easy to determine an appropriate level for new input/output types.

5.3.1 Source input

For the language processor a source is a sequence of objects (of type Dp4Base.Token). They offer just the minimal functionality, which is needed by the parser, i.e., a sequential reader can be reset to the beginning, save and reestablish its position, write its position, and be closed.
The most important sources are of stream type, i.e., sequences of characters. Dp4Stream.Token is derived from Dp4Base.Token for this purpose. Streams are abstract, they must be implemented by specialization. There is at least an implementation of Dp4DocFiles for ASCII file input/output. For further stream definitions consult the host language related documentation.

These are the important types and procedures:

Dp4Base.Source: Base source type
Dp4Base.concTkn: Appends an object of type Dp4Base.Token on a source
Dp4Streams.StrmSrc: Constructs a source from a stream
Dp4Streams.New: Constructs a Dp4Base.Token object from a stream

Commonly, a source consists of one token of type Dp4Stream.Token. Module Dp4Files has already a constructor IFile, which builds a source object from a file name string.

5.3.2 Target output

Target output can be directed to different carriers. There is, again, a standard stream carrier supported. The procedure Dp4Streams.Tar2Strm(TAR, Dp4Streams.OutStream) writes a target onto the desired stream. (see 5.2.2)

    previous         next         contents

5. Runtime support