#include

A User Language Program can reuse code in other ULP files through the #include directive. The syntax is

#include "filename"

The file filename is first looked for in the same directory as the current source file (that is the file that contains the #include directive). If it is not found there, it is searched for in the directories contained in the ULP directory path.

The maximum include depth is 10.

Each #include directive is processed only once. This makes sure that there are no multiple definitions of the same variables or functions, which would cause errors.

Portability note

If filename contains a directory path, it is best to always use the forward slash as directory separator (even under Windows!). Windows drive letters should be avoided. This way a User Language Program will run on all platforms.

#require

Over time it may happen that newer versions of EAGLE implement new or modified User Language features, which can cause error messages when such a ULP is run from an older version of EAGLE. In order to give the user a dedicated message that this ULP requires at least a certain version of EAGLE, a ULP can contain the #require directive. The syntax is

#require version

The version must be given as a real constant of the form

V.RRrr

where V is the version number, RR is the release number and rr is the (optional) revision number (both padded with leading zeros if they are less than 10). For example, if a ULP requires at least EAGLE version 4.11r06 (which is the beta version that first implemented the #require directive), it could use

#require 4.1106

The proper directive for version 5.1.2 would be

#require 5.0102

#usage

Every User Language Program should contain information about its function, how to use it and maybe who wrote it. The directive

#usage text [, text...]

implements a standard way to make this information available. If the #usage directive is present, its text (which has to be a string constant) will be used in the Control Panel to display a description of the program.

In case the ULP needs to use this information in, for example, a dlgMessageBox(), the text is available to the program through the builtin constant usage.

Only the #usage directive of the main program file (that is the one started with the RUN command) will take effect. Therefore pure include files can (and should!) also have #usage directives of their own.

It is best to have the #usage directive at the beginning of the file, so that the Control Panel doesn't have to parse all the rest of the text when looking for the information to display.

If the usage information shall be made available in several langauges, the texts of the individual languages have to be separated by commas. Each of these texts has to start with the two letter code of the respective language (as delivered by the language() function), followed by a colon and any number of blanks. If no suitable text is found for the language used on the actual system, the first given text will be used (this one should generally be English in order to make the program accessible to the largest number of users).

Example

#usage "en: A sample ULP\n"
           "Implements an example that shows how to use the EAGLE User Language\n"
           "Usage: RUN sample.ulp\n"
           "Author: john@home.org",
       "de: Beispiel eines ULPs\n"
           "Implementiert ein Beispiel das zeigt, wie man die EAGLE User Language benutzt\n"
           "Aufruf: RUN sample.ulp\n"
           "Author: john@home.org"