EAGLE

EASILY APPLICABLE GRAPHICAL LAYOUT EDITOR

User Language
Version 5.7

Copyright 2010 CadSoft All rights reserved

EAGLEUserLanguage Version5.7

TableOfContents
UserLanguage.........................................................................................................13
WritingaULP..........................................................................................................13
ExecutingaULP.......................................................................................................14
Syntax......................................................................................................................14
Whitespace..............................................................................................................14
Comments................................................................................................................15
Directives.................................................................................................................15
#include..................................................................................................................15
Portabilitynote..................................................................................................16
#require...................................................................................................................16
#usage.....................................................................................................................16
Example.............................................................................................................17
Keywords.................................................................................................................17
Identifiers................................................................................................................17
Constants.................................................................................................................18
CharacterConstants.................................................................................................18
IntegerConstants.....................................................................................................18
Examples...........................................................................................................18
RealConstants.........................................................................................................18
Examples...........................................................................................................19
StringConstants......................................................................................................19
EscapeSequences....................................................................................................19
Examples...........................................................................................................20
Punctuators..............................................................................................................20
Brackets...................................................................................................................20
Parentheses..............................................................................................................21
Braces......................................................................................................................21
Comma....................................................................................................................21
Semicolon................................................................................................................21
Colon.......................................................................................................................22
EqualSign................................................................................................................22
DataTypes...............................................................................................................22
char..........................................................................................................................22
int............................................................................................................................22
real...........................................................................................................................23
string........................................................................................................................23
Implementationdetails......................................................................................23
TypeConversions.....................................................................................................24

Page2of136
EAGLEUserLanguage Version5.7

Typecast...................................................................................................................24
ObjectTypes.............................................................................................................24
UL_ARC...................................................................................................................27
Constants...........................................................................................................27
Note...................................................................................................................27
Example.............................................................................................................27
UL_AREA.................................................................................................................27
Example.............................................................................................................28
UL_ATTRIBUTE........................................................................................................28
Constants...........................................................................................................28
Note...................................................................................................................28
Example.............................................................................................................29
UL_BOARD..............................................................................................................29
Note...................................................................................................................29
Example.............................................................................................................30
UL_BUS....................................................................................................................30
Constants...........................................................................................................30
Example.............................................................................................................30
UL_CIRCLE..............................................................................................................30
Example.............................................................................................................30
UL_CLASS................................................................................................................30
Note...................................................................................................................31
Example.............................................................................................................31
UL_CONTACT..........................................................................................................31
Constants...........................................................................................................31
Note...................................................................................................................31
Example.............................................................................................................32
UL_CONTACTREF....................................................................................................32
Example.............................................................................................................32
UL_DEVICE..............................................................................................................32
Constants...........................................................................................................32
Note...................................................................................................................33
Examples...........................................................................................................33
UL_DEVICESET........................................................................................................34
Constants...........................................................................................................34
Note...................................................................................................................34
Example.............................................................................................................34
UL_ELEMENT..........................................................................................................34
Constants...........................................................................................................35
Note...................................................................................................................35
Examples...........................................................................................................35
UL_FRAME...............................................................................................................36
Constants...........................................................................................................36

Page3of136
EAGLEUserLanguage Version5.7

Note...................................................................................................................36
Example.............................................................................................................36
UL_GATE..................................................................................................................37
Constants...........................................................................................................37
Note...................................................................................................................37
Example.............................................................................................................37
UL_GRID..................................................................................................................37
Constants...........................................................................................................38
Note...................................................................................................................38
Example.............................................................................................................38
UL_HOLE.................................................................................................................38
Note...................................................................................................................38
Example.............................................................................................................38
UL_INSTANCE..........................................................................................................38
Constants...........................................................................................................39
Note...................................................................................................................39
Example.............................................................................................................40
UL_JUNCTION.........................................................................................................40
Example.............................................................................................................40
UL_LABEL................................................................................................................40
Note...................................................................................................................40
Example.............................................................................................................41
UL_LAYER................................................................................................................41
Constants...........................................................................................................41
Example.............................................................................................................42
UL_LIBRARY............................................................................................................42
Constants...........................................................................................................43
Note...................................................................................................................43
Example.............................................................................................................43
UL_NET....................................................................................................................43
Constants...........................................................................................................44
Note...................................................................................................................44
Example.............................................................................................................44
UL_PACKAGE...........................................................................................................44
Constants...........................................................................................................45
Note...................................................................................................................45
Example.............................................................................................................45
UL_PAD....................................................................................................................46
Constants...........................................................................................................46
Note...................................................................................................................46
Example.............................................................................................................47
UL_PART..................................................................................................................47
Constants...........................................................................................................47
Note...................................................................................................................48

Page4of136
EAGLEUserLanguage Version5.7

Example.............................................................................................................48
UL_PIN.....................................................................................................................48
Constants...........................................................................................................49
Note...................................................................................................................49
Example.............................................................................................................50
UL_PINREF..............................................................................................................50
Example.............................................................................................................50
UL_POLYGON..........................................................................................................50
Constants...........................................................................................................51
Note...................................................................................................................51
Polygonwidth....................................................................................................51
Partialpolygons.................................................................................................51
Example.............................................................................................................52
UL_RECTANGLE......................................................................................................53
Example.............................................................................................................53
UL_SCHEMATIC.......................................................................................................53
Note...................................................................................................................53
Example.............................................................................................................54
UL_SEGMENT..........................................................................................................54
Note...................................................................................................................54
Example.............................................................................................................54
UL_SHEET...............................................................................................................54
Example.............................................................................................................55
UL_SIGNAL..............................................................................................................55
Constants...........................................................................................................55
Example.............................................................................................................55
UL_SMD...................................................................................................................55
Constants...........................................................................................................56
Note...................................................................................................................56
Example.............................................................................................................56
UL_SYMBOL............................................................................................................57
Constants...........................................................................................................57
Note...................................................................................................................57
Example.............................................................................................................57
UL_TEXT..................................................................................................................57
Constants...........................................................................................................58
Note...................................................................................................................58
Example.............................................................................................................58
UL_VIA.....................................................................................................................58
Constants...........................................................................................................58
Note...................................................................................................................59
Example.............................................................................................................59
UL_WIRE.................................................................................................................59
Constants...........................................................................................................60

Page5of136
EAGLEUserLanguage Version5.7

WireStyle..........................................................................................................60
ArcsatWirelevel...............................................................................................60
Example.............................................................................................................60
Definitions...............................................................................................................61
ConstantDefinitions................................................................................................61
VariableDefinitions..................................................................................................61
Examples...........................................................................................................62
FunctionDefinitions................................................................................................62
Thespecialfunctionmain()...............................................................................63
Example.............................................................................................................63
Operators.................................................................................................................63
BitwiseOperators....................................................................................................64
LogicalOperators.....................................................................................................64
ComparisonOperators.............................................................................................64
EvaluationOperators...............................................................................................64
ArithmeticOperators...............................................................................................65
StringOperators......................................................................................................66
Expressions..............................................................................................................66
ArithmeticExpression..............................................................................................66
Examples...........................................................................................................66
AssignmentExpression............................................................................................66
Examples...........................................................................................................66
StringExpression.....................................................................................................67
Examples...........................................................................................................67
CommaExpression..................................................................................................67
Example.............................................................................................................67
ConditionalExpression............................................................................................67
Example.............................................................................................................67
FunctionCall...........................................................................................................67
Example.............................................................................................................67
Statements...............................................................................................................67
CompoundStatement..............................................................................................68
ExpressionStatement..............................................................................................68
ControlStatements..................................................................................................68
break........................................................................................................................69
continue...................................................................................................................69
do...while.................................................................................................................69
Example.............................................................................................................69
for............................................................................................................................69
Example.............................................................................................................70
if...else.....................................................................................................................70

Page6of136
EAGLEUserLanguage Version5.7

return.......................................................................................................................70
switch......................................................................................................................71
Example.............................................................................................................71
while........................................................................................................................72
Example.............................................................................................................72
Builtins.....................................................................................................................72
BuiltinConstants.....................................................................................................72
BuiltinVariables.......................................................................................................73
BuiltinFunctions......................................................................................................73
CharacterFunctions.................................................................................................75
is...()........................................................................................................................76
Charactercategories..........................................................................................76
Example.............................................................................................................76
to...().......................................................................................................................77
FileHandlingFunctions...........................................................................................77
fileerror().................................................................................................................77
Example.............................................................................................................78
fileglob()..................................................................................................................78
NoteforWindowsusers.....................................................................................78
Example.............................................................................................................79
FilenameFunctions..................................................................................................79
Example.............................................................................................................79
FiledataFunctions...................................................................................................79
Example.............................................................................................................79
FileInputFunctions.................................................................................................80
fileread()..................................................................................................................80
Example.............................................................................................................80
MathematicalFunctions...........................................................................................80
ErrorMessages...................................................................................................81
Absolute,MaximumandMinimumFunctions.........................................................81
Example.............................................................................................................82
RoundingFunctions.................................................................................................82
Example.............................................................................................................82
TrigonometricFunctions..........................................................................................82
Constants...........................................................................................................83
Example.............................................................................................................83
ExponentialFunctions.............................................................................................83
Note...................................................................................................................83
Example.............................................................................................................83
MiscellaneousFunctions..........................................................................................83
exit()........................................................................................................................84
Constants...........................................................................................................84

Page7of136
EAGLEUserLanguage Version5.7

language()...............................................................................................................84
Example.............................................................................................................85
lookup()...................................................................................................................85
Example.............................................................................................................86
palette()...................................................................................................................87
Constants...........................................................................................................87
sort()........................................................................................................................87
Sortingasinglearray.........................................................................................87
Sortingasetofarrays........................................................................................88
status()....................................................................................................................88
system()...................................................................................................................89
Input/Outputredirection...................................................................................89
Backgroundexecution.......................................................................................89
Example.............................................................................................................90
UnitConversions......................................................................................................90
Example.............................................................................................................90
PrintingFunctions...................................................................................................90
printf().....................................................................................................................91
Formatstring.....................................................................................................91
Formatspecifiers................................................................................................91
Conversiontypecharacters................................................................................91
Flagcharacters...................................................................................................92
Widthspecifiers.................................................................................................92
Precisionspecifiers.............................................................................................92
Defaultprecisionvalues.....................................................................................93
Howprecisionspecification(.n)affectsconversion...........................................93
Binaryzerocharacters.......................................................................................93
Example.............................................................................................................93
sprintf()...................................................................................................................93
Formatstring.....................................................................................................94
Binaryzerocharacters.......................................................................................94
Example.............................................................................................................94
StringFunctions.......................................................................................................94
strchr()....................................................................................................................94
Example.............................................................................................................95
strjoin()....................................................................................................................95
Example.............................................................................................................95
strlen().....................................................................................................................95
Example.............................................................................................................96
strlwr()....................................................................................................................96
Example.............................................................................................................96
strrchr()...................................................................................................................96
Example.............................................................................................................96

Page8of136
EAGLEUserLanguage Version5.7

strrstr()....................................................................................................................97
Example.............................................................................................................97
strsplit()...................................................................................................................97
Example.............................................................................................................97
strstr().....................................................................................................................98
Example.............................................................................................................98
strsub()....................................................................................................................98
Example.............................................................................................................98
strtod()....................................................................................................................98
Example.............................................................................................................99
strtol().....................................................................................................................99
Example.............................................................................................................99
strupr()....................................................................................................................99
Example...........................................................................................................100
strxstr()..................................................................................................................100
Example...........................................................................................................100
TimeFunctions......................................................................................................100
time()....................................................................................................................101
Example...........................................................................................................101
timems()................................................................................................................101
Example...........................................................................................................101
TimeConversions..................................................................................................101
Example...........................................................................................................102
ObjectFunctions....................................................................................................102
clrgroup()..............................................................................................................102
Example...........................................................................................................103
ingroup()...............................................................................................................103
Example...........................................................................................................103
setgroup()..............................................................................................................104
Example...........................................................................................................104
BuiltinStatements.................................................................................................104
board()..................................................................................................................105
Checkifthereisaboard..................................................................................105
Accessingboardfromaschematic...................................................................105
Example...........................................................................................................105
deviceset().............................................................................................................106
Checkifthereisadeviceset............................................................................106
Example...........................................................................................................106
library().................................................................................................................106
Checkifthereisalibrary.................................................................................107
Example...........................................................................................................107
output().................................................................................................................107

Page9of136
EAGLEUserLanguage Version5.7

FileModes.......................................................................................................107
NestedOutputstatements...............................................................................108
Example...........................................................................................................108
package()...............................................................................................................108
Checkifthereisapackage..............................................................................108
Example...........................................................................................................108
schematic()............................................................................................................109
Checkifthereisaschematic...........................................................................109
Accessingschematicfromaboard...................................................................109
AccessthecurrentSheet..................................................................................109
Example...........................................................................................................109
sheet()...................................................................................................................110
Checkifthereisasheet...................................................................................110
Example...........................................................................................................110
symbol()................................................................................................................110
Checkifthereisasymbol................................................................................111
Example...........................................................................................................111
Dialogs...................................................................................................................111
PredefinedDialogs.................................................................................................111
dlgDirectory()........................................................................................................111
Example...........................................................................................................112
dlgFileOpen(),dlgFileSave().................................................................................112
Example...........................................................................................................113
dlgMessageBox()...................................................................................................113
Example...........................................................................................................114
DialogObjects........................................................................................................114
dlgCell...................................................................................................................114
Example...........................................................................................................115
dlgCheckBox..........................................................................................................115
Example...........................................................................................................115
dlgComboBox........................................................................................................116
Example...........................................................................................................116
dlgDialog...............................................................................................................116
Examples.........................................................................................................117
dlgGridLayout........................................................................................................117
Example...........................................................................................................117
dlgGroup................................................................................................................118
Example...........................................................................................................118
dlgHBoxLayout......................................................................................................118
Example...........................................................................................................118
dlgIntEdit...............................................................................................................119
Example...........................................................................................................119

Page10of136
EAGLEUserLanguage Version5.7

dlgLabel.................................................................................................................119
Example...........................................................................................................119
dlgListBox..............................................................................................................120
Example...........................................................................................................120
dlgListView............................................................................................................120
Example...........................................................................................................121
dlgPushButton.......................................................................................................121
Example...........................................................................................................122
dlgRadioButton......................................................................................................122
Example...........................................................................................................123
dlgRealEdit............................................................................................................123
Example...........................................................................................................123
dlgSpacing.............................................................................................................123
Example...........................................................................................................124
dlgSpinBox.............................................................................................................124
Example...........................................................................................................124
dlgStretch..............................................................................................................124
Example...........................................................................................................125
dlgStringEdit..........................................................................................................125
Example...........................................................................................................125
dlgTabPage.............................................................................................................125
Example...........................................................................................................126
dlgTabWidget.........................................................................................................126
Example...........................................................................................................126
dlgTextEdit.............................................................................................................126
Example...........................................................................................................127
dlgTextView...........................................................................................................127
Example...........................................................................................................127
dlgVBoxLayout.......................................................................................................127
Example...........................................................................................................128
LayoutInformation................................................................................................128
GridLayoutContext........................................................................................128
HorizontalLayoutContext...............................................................................128
VerticalLayoutContext....................................................................................129
MixingLayoutContexts...................................................................................129
DialogFunctions....................................................................................................129
dlgAccept()............................................................................................................129
Example...........................................................................................................129
dlgRedisplay().......................................................................................................130
Example...........................................................................................................130
dlgReset()..............................................................................................................130
Example...........................................................................................................131

Page11of136
EAGLEUserLanguage Version5.7

dlgReject().............................................................................................................131
Example...........................................................................................................131
EscapeCharacter...................................................................................................131
ACompleteExample.............................................................................................132
SupportedHTMLtags............................................................................................133

Page12of136
EAGLEUserLanguage Version5.7

User Language
TheEAGLEUserLanguagecanbeusedtoaccesstheEAGLEdatastructuresandtocreatea
widevarietyofoutputfiles.
TousethisfeatureyouhavetowriteaUserLanguageProgram(ULP),andthenexecuteit.
ThefollowingsectionsdescribetheEAGLEUserLanguageindetail:
Syntax liststherulesaULPfilehastofollow
DataTypes definesthebasicdatatypes
ObjectTypes definestheEAGLEobjects
Definitions showshowtowriteadefinition
Operators liststhevalidoperators
Expressions showshowtowriteexpressions
Statements definesthevalidstatements
Builtins liststhebuiltinconstants,functionsetc.
showshowtoimplementagraphicalfrontenttoa
Dialogs
ULP

Writing a ULP
AUserLanguageProgramisaplaintextfilewhichiswritteninaClikesyntax.User
LanguageProgramsusetheextension.ulp.YoucancreateaULPfilewithanytexteditor
(provideditdoesnotinsertanyadditionalcontrolcharactersintothefile)oryoucanuse
thebuiltintexteditor.
AUserLanguageProgramconsistsoftwomajoritems,definitionsandstatements.
Definitionsareusedtodefineconstants,variablesandfunctionstobeusedbystatements.
AsimpleULPcouldlooklikethis:
#usage "Add the characters in the word 'Hello'\n"
"Usage: RUN sample.ulp"
// Definitions:
string hello = "Hello";
int count(string s)
{
int c = 0;
for (int i = 0; s[i]; ++i)
c += s[i];
return c;
}
// Statements:
output("sample") {
printf("Count is: %d\n", count(hello));
}

Ifthe#usagedirectiveispresent,itsvaluewillbeusedintheControlPaneltodisplaya
descriptionoftheprogram.
IftheresultoftheULPshallbeaspecificcommandthatshallbeexecutedintheeditor
window,theexit()functioncanbeusedtosendthatcommandtotheeditorwindow.

Page13of136
EAGLEUserLanguage Version5.7

Executing a ULP
UserLanguageProgramsareexecutedbytheRUNcommandfromaneditorwindow's
commandline.
AULPcanreturninformationonwhetherithasrunsuccessfullyornot.Youcanusethe
exit()functiontoterminatetheprogramandsetthereturnvalue.
Areturnvalueof0meanstheULPhasended"normally"(i.e.successfully),whileanyother
valueisconsideredasanabnormalprogramtermination.
ThedefaultreturnvalueofanyULPis0.
WhentheRUNcommandisexecutedaspartofascriptfile,thescriptisterminatedifthe
ULPhasexitedwithareturnvalueotherthan0.
Aspecialvariantoftheexit()functioncanbeusedtosendacommandtotheeditor
windowasaresultoftheULP.

Syntax
ThebasicbuildingblocksofaUserLanguageProgramare
Whitespace
Comments
Directives
Keywords
Identifiers
Constants
Punctuators
Allofthesehavetofollowcertainsyntacticalrules,whicharedescribedintheirrespective
sections.

Whitespace
BeforeaUserLanguageProgramcanbeexecuted,ithastobereadinfromafile.During
thisreadinprocess,thefilecontentsisparsedintotokensandwhitespace.
Anyspaces(blanks),tabs,newlinecharactersandcommentsareconsideredwhitespaceand
arediscarded.
TheonlyplacewhereASCIIcharactersrepresentingwhitespacearenotdiscardediswithin
literalstrings,likein
string s = "Hello World";

wheretheblankcharacterbetween'o'and'W'remainspartofthestring.
Ifthefinalnewlinecharacterofalineisprecededbyabackslash(\),thebackslashand
newlinecharacterarebothdiscarded,andthetwolinesaretreatedasoneline:
"Hello \
World"

Page14of136
EAGLEUserLanguage Version5.7

isparsedas"Hello World"

Comments
WhenwritingaUserLanguageProgramitisgoodpracticetoaddsomedescriptivetext,
givingthereaderanideaaboutwhatthisparticularULPdoes.Youmightalsowanttoadd
yourname(and,ifavailable,youremailaddress)totheULPfile,sothatotherpeoplewho
useyourprogramcouldcontactyouincasetheyhaveaproblemorwouldliketosuggest
animprovement.
Therearetwowaystodefineacomment.Thefirstoneusesthesyntax
/* some comment text */

whichmarksanycharactersbetween(andincluding)theopening/*andtheclosing*/as
comment.Suchcommentsmayexpandovermorethanonelines,asin
/* This is a
multi line comment
*/

buttheydonotnest.Thefirst*/thatfollowsany/*willendthecomment.
Thesecondwaytodefineacommentusesthesyntax
int i; // some comment text

whichmarksanycharactersafter(andincluding)the//andupto(butnotincluding)the
newlinecharacterattheendofthelineascomment.

Directives
Thefollowingdirectivesareavailable:
#include
#require
#usage

#include
AUserLanguageProgramcanreusecodeinotherULPfilesthroughthe#include
directive.Thesyntaxis
#include "filename"

Thefilefilenameisfirstlookedforinthesamedirectoryasthecurrentsourcefile(thatis
thefilethatcontainsthe#includedirective).Ifitisnotfoundthere,itissearchedforin
thedirectoriescontainedintheULPdirectorypath.
Themaximumincludedepthis10.
Each#includedirectiveisprocessedonlyonce.Thismakessurethatthereareno
multipledefinitionsofthesamevariablesorfunctions,whichwouldcauseerrors.

Page15of136
EAGLEUserLanguage Version5.7

Portability note
Iffilenamecontainsadirectorypath,itisbesttoalwaysusetheforwardslashas
directoryseparator(evenunderWindows!).Windowsdrivelettersshouldbe
avoided.ThiswayaUserLanguageProgramwillrunonallplatforms.

#require
OvertimeitmayhappenthatnewerversionsofEAGLEimplementnewormodifiedUser
Languagefeatures,whichcancauseerrormessageswhensuchaULPisrunfromanolder
versionofEAGLE.InordertogivetheuseradedicatedmessagethatthisULPrequiresat
leastacertainversionofEAGLE,aULPcancontainthe#requiredirective.Thesyntaxis
#require version

Theversionmustbegivenasarealconstantoftheform
V.RRrr

whereVistheversionnumber,RRisthereleasenumberandrristhe(optional)revision
number(bothpaddedwithleadingzeroesiftheyarelessthan10).Forexample,ifaULP
requiresatleastEAGLEversion4.11r06(whichisthebetaversionthatfirstimplemented
the#requiredirective),itcoulduse
#require 4.1106

Theproperdirectiveforversion5.1.2wouldbe
#require 5.0102

#usage
EveryUserLanguageProgramshouldcontaininformationaboutitsfunction,howtouseit
andmaybewhowroteit.
Thedirective
#usage text [, text...]

implementsastandardwaytomakethisinformationavailable.
Ifthe#usagedirectiveispresent,itstext(whichhastobeastringconstant)willbeused
intheControlPaneltodisplayadescriptionoftheprogram.
IncasetheULPneedstousethisinformationin,forexample,adlgMessageBox(),thetext
isavailabletotheprogramthroughthebuiltinconstantusage.
Onlythe#usagedirectiveofthemainprogramfile(thatistheonestartedwiththeRUN
command)willtakeeffect.Thereforepureincludefilescan(andshould!)alsohave
#usagedirectivesoftheirown.
Itisbesttohavethe#usagedirectiveatthebeginningofthefile,sothattheControlPanel
doesn'thavetoparsealltherestofthetextwhenlookingfortheinformationtodisplay.

Page16of136
EAGLEUserLanguage Version5.7

Iftheusageinformationshallbemadeavailableinseverallangauges,thetextsofthe
individuallanguageshavetobeseparatedbycommas.Eachofthesetextshastostartwith
thetwolettercodeoftherespectivelanguage(asdeliveredbythelanguage()function),
followedbyacolonandanynumberofblanks.Ifnosuitabletextisfoundforthelanguage
usedontheactualsystem,thefirstgiventextwillbeused(thisoneshouldgenerallybe
Englishinordertomaketheprogramaccessibletothelargestnumberofusers).

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"

Keywords
Thefollowingkeywordsarereservedforspecialpurposesandmustnotbeusedasnormal
identifiernames:
break
case
char
continue
default
do
else
enum
for
if
int
numeric
real
return
string
switch
void
while

Inaddition,thenamesofbuiltinsandobjecttypesarealsoreservedandmustnotbeused
asidentifiernames.

Identifiers
Anidentifierisanamethatisusedtointroduceauserdefinedconstant,variableor
function.
Identifiersconsistofasequenceofletters(a b c...,A B C...),digits(1 2 3...)and
underscores(_).Thefirstcharacterofanidentifiermustbealetteroranunderscore.

Page17of136
EAGLEUserLanguage Version5.7

Identifiersarecasesensitive,whichmeansthat
int Number, number;

woulddefinetwodifferentintegervariables.
Themaximumlengthofanidentifieris100characters,andallofthesearesignificant.

Constants
ConstantsareliteraldataitemswrittenintoaUserLanguageProgram.Accordingtothe
differentdatatypes,therearealsodifferenttypesofconstants.
Characterconstants
Integerconstants
Realconstants
Stringconstants

Character Constants
Acharacterconstantconsistsofasinglecharacteroranescapesequenceenclosedinsingle
quotes,like
'a'
'='
'\n'

Thetypeofacharacterconstantischar.

Integer Constants
Dependingonthefirst(andpossiblythesecond)character,anintegerconstantisassumed
tobeexpressedindifferentbasevalues:
constantinterpreted
first second
as
0 1-7 octal(base8)
0 x,X hexadecimal(base16)
1-9 decimal(base10)
Thetypeofanintegerconstantisint.

Examples
16 decimal
020 octal
0x10 hexadecimal

Real Constants
Arealconstantfollowsthegeneralpattern
[-]int.frac[e|E[]exp]

Page18of136
EAGLEUserLanguage Version5.7

whichstandsfor
optionalsign
decimalinteger
decimalpoint
decimalfraction
eorEandasignedintegerexponent
Youcanomiteitherthedecimalintegerorthedecimalfraction(butnotboth).Youcanomit
eitherthedecimalpointorthelettereorEandthesignedintegerexponent(butnotboth).
Thetypeofanrealconstantisreal.

Examples
Constant Value
23.45e6 23.45x10^6
.0 0.0
0. 0.0
1. 1.0
-1.23 1.23
2e-5 2.0x10^5
3E+10 3.0x10^10
.09E34 0.09x10^34

String Constants
Astringconstantconsistsofasequenceofcharactersorescapesequencesenclosedin
doublequotes,like
"Hello world\n"

Thetypeofastringconstantisstring.
Stringconstantscanbeofanylength(providedthereisenoughfreememoryavailable).
Stringconstantscanbeconcatenatedbysimplywritingthemnexttoeachothertoform
largerstrings:
string s = "Hello" " world\n";

Itisalsopossibletoextendastringconstantovermorethanonelinebyescapingthe
newlinecharacterwithabackslash(\):
string s = "Hello \
world\n";

Escape Sequences
Anescapesequenceconsistsofabackslash(\),followedbyoneormorespecialcharacters:
Sequence Value

Page19of136
EAGLEUserLanguage Version5.7

\a audiblebell
\b backspace
\f formfeed
\n newline
\r carriagereturn
\t horizontaltab
\v verticaltab
\\ backslash
\' singlequote
\" doublequote
O=upto3octal
\O
digits
\xH H=upto2hexdigits
Anycharacterfollowingtheinitialbackslashthatisnotmentionedinthislistwillbetreated
asthatcharacter(withoutthebackslash).
Escapesequencescanbeusedincharacterconstantsandstringconstants.

Examples
'\n'
"A tab\tinside a text\n"
"Ring the bell\a\n"

Punctuators
ThepunctuatorsusedinaUserLanguageProgramare
[] Brackets
() Parentheses
{} Braces
, Comma
; Semicolon
: Colon
= Equalsign
OtherspecialcharactersareusedasoperatorsinaULP.

Brackets
Bracketsareusedinarraydefinitions
int ai[];

inarraysubscripts
n = ai[2];

andinstringsubscriptstoaccesstheindividualcharactersofastring
string s = "Hello world";

Page20of136
EAGLEUserLanguage Version5.7

char c = s[2];

Parentheses
Parenthesesgroupexpressions(possiblyalteringnormaloperatorprecedence),isolate
conditionalexpressions,andindicatefunctioncallsandfunctionparameters:
d = c * (a + b);
if (d == z) ++x;
func();
void func2(int n) { ... }

Braces
Bracesindicatethestartandendofacompoundstatement:
if (d == z) {
++x;
func();
}

andarealsousedtogroupthevaluesofanarrayinitializer:
int ai[] = { 1, 2, 3 };

Comma
Thecommaseparatestheelementsofafunctionargumentlistortheparametersofa
functioncall:
int func(int n, real r, string s) { ... }
int i = func(1, 3.14, "abc");

Italsodelimitsthevaluesofanarrayinitializer:
int ai[] = { 1, 2, 3 };

anditseparatestheelementsofavariabledefinition:
int i, j, k;

Semicolon
Thesemicolonterminatesastatement,asin
i = a + b;

anditalsodelimitstheinit,testandincrementexpressionsofaforstatement:
for (int n = 0; n < 3; ++n) {
func(n);
}

Page21of136
EAGLEUserLanguage Version5.7

Colon
Thecolonindicatestheendofalabelinaswitchstatement:
switch (c) {
case 'a': printf("It was an 'a'\n"); break;
case 'b': printf("It was a 'b'\n"); break;
default: printf("none of them\n");
}

Equal Sign
Theequalsignseparatesvariabledefinitionsfrominitializationlists:
int i = 10;
char c[] = { 'a', 'b', 'c' };

Itisalsousedasanassignmentoperator.

Data Types
AUserLanguageProgramcandefinevariablesofdifferenttypes,representingthedifferent
kindsofinformationavailableintheEAGLEdatastructures.
Thefourbasicdatatypesare
char forsinglecharacters
int forintegralvalues
forfloatingpoint
real
values
string fortextualinformation
BesidesthesebasicdatatypestherearealsohighlevelObjectTypes,whichrepresentthe
datastructuresstoredintheEAGLEdatafiles.
Thespecialdatatypevoidisusedonlyasareturntypeofafunction,indicatingthatthis
functiondoesnotreturnanyvalue.

char
Thedatatypecharisusedtostoresinglecharacters,likethelettersofthealphabet,or
smallunsignednumbers.
Avariableoftypecharhasasizeof8bit(onebyte),andcanstoreanyvalueintherange
0..255.
SeealsoOperators,CharacterConstants

int
Thedatatypeintisusedtostoresignedintegralvalues,likethecoordinatesofanobject.
Avariableoftypeinthasasizeof32bit(fourbyte),andcanstoreanyvalueintherange
-2147483648..2147483647.

Page22of136
EAGLEUserLanguage Version5.7

SeealsoIntegerConstants

real
Thedatatyperealisusedtostoresignedfloatingpointvalues,likethegriddistance.
Avariableoftyperealhasasizeof64bit(eightbyte),andcanstoreanyvalueinthe
range2.2e-308..1.7e+308withaprecisionof15digits.
SeealsoRealConstants

string
Thedatatypestringisusedtostoretextualinformation,likethenameofapartornet.
Avariableoftypestringisnotlimitedinit'ssize(providedthereisenoughmemory
available).
Variablesoftypestringaredefinedwithoutanexplicitsize.Theygrowautomaticallyas
necessaryduringprogramexecution.
Theelementsofastringvariableareoftypecharandcanbeaccessedindividuallyby
using[index].Thefirstcharacterofastringhastheindex0:
string s = "Layout";
printf("Third char is: %c\n", s[2]);

Thiswouldprintthecharacter'y'.Notethats[2]returnsthethirdcharacterofs!
SeealsoOperators,BuiltinFunctions,StringConstants

Implementation details
ThedatatypestringisactuallyimplementedlikenativeCtypezeroterminatedstrings
(i.e.char[]).Lookingatthefollowingvariabledefinition
string s = "abcde";

s[4]isthecharacter'e',ands[5]isthecharacter'\0',ortheintegervalue0x00.This
factmaybeusedtodeterminetheendofastringwithoutusingthestrlen()function,as
in
for (int i = 0; s[i]; ++i) {
// do something with s[i]
}

Itisalsoperfectlyokto"cutoff"partofastringby"punching"azerocharacterintoit:
string s = "abcde";
s[3] = 0;

Thiswillresultinshavingthevalue"abc".Notethateverythingfollowingthezero
characterwillactuallybegone,anditwon'tcomebackbyrestoringtheoriginalcharacter.
Thesameappliestoanyotheroperationthatsetsacharacterto0,forinstances[3].

Page23of136
EAGLEUserLanguage Version5.7

Type Conversions
Theresulttypeofanarithmeticexpression,suchasa + b,whereaandbaredifferent
arithmetictypes,isequaltothe"larger"ofthetwooperandtypes.
Arithmetictypesarechar,intandreal(inthatorder).Soif,e.g.aisoftypeintandb
isoftypereal,theresultoftheexpressiona + bwouldbereal.
SeealsoTypecast

Typecast
Theresulttypeofanarithmeticexpressioncanbeexplicitlyconvertedtoadifferent
arithmetictypebyapplyingatypecasttoit.
Thegeneralsyntaxofatypecastis
type(expression)

wheretypeisoneofchar,intorreal,andexpressionisanyarithmeticexpression.
Whentypecastingarealexpressiontoint,thefractionalpartofthevalueistruncated!
SeealsoTypeConversions

Object Types
TheEAGLEdatastructuresarestoredinthreebinaryfiletypes:
Library(*.lbr)
Schematic(*.sch)
Board(*.brd)
Thesedatafilescontainahierarchyofobjects.InaUserLanguageProgramyoucanaccess
thesehierarchiesthroughtheirrespectivebuiltinaccessstatements:
library(L) { ... }
schematic(S) { ... }
board(B) { ... }

Theseaccessstatementssetupacontextwithinwhichyoucanaccessalloftheobjects
containedinthelibrary,schematicorboard.
Thepropertiesoftheseobjectscanbeaccessedthroughmembers.
Therearetwokindsofmembers:
Datamembers
Loopmembers
Datamembersimmediatelyreturntherequesteddatafromanobject.Forexample,in
board(B) {
printf("%s\n", B.name);
}

Page24of136
EAGLEUserLanguage Version5.7

thedatamembernameoftheboardobjectBreturnstheboard'sname.
Datamemberscanalsoreturnotherobjects,asin
board(B) {
printf("%f\n", B.grid.size);
}

wheretheboard'sgriddatamemberreturnsagridobject,ofwhichthesizedatamember
thenreturnsthegrid'ssize.
Loopmembersareusedtoaccessmultipleobjectsofthesamekind,whicharecontained
inahigherlevelobject:
board(B) {
B.elements(E) {
printf("%-8s %-8s\n", E.name, E.value);
}
}

Thisexampleusestheboard'selements()loopmemberfunctiontosetupaloopthroughall
oftheboard'selements.TheblockfollowingtheB.elements(E)statementisexecutedin
turnforeachelement,andthecurrentelementcanbereferencedinsidetheblockthrough
thenameE.
Loopmembersprocessobjectsinalphanumericalorder,providedtheyhaveaname.
Aloopmemberfunctioncreatesavariableofthetypenecessarytoholdtherequested
objects.Youarefreetouseanyvalidnameforsuchavariable,sotheaboveexamplemight
alsobewrittenas
board(MyBoard) {
MyBoard.elements(TheCurrentElement) {
printf("%-8s %-8s\n", TheCurrentElement.name, TheCurrentElement.value);
}
}

andwoulddotheexactsamething.Thescopeofthevariablecreatedbyaloopmember
functionislimitedtothestatement(orblock)immediatelyfollowingtheloopfunctioncall.
ObjecthierarchyofaLibrary:
LIBRARY
GRID
LAYER
DEVICESET
DEVICE
GATE
PACKAGE
CONTACT
PAD
SMD
CIRCLE
HOLE
RECTANGLE
FRAME
TEXT
WIRE

Page25of136
EAGLEUserLanguage Version5.7

POLYGON
WIRE
SYMBOL
PIN
CIRCLE
RECTANGLE
FRAME
TEXT
WIRE
POLYGON
WIRE

ObjecthierarchyofaSchematic:
SCHEMATIC
GRID
LAYER
LIBRARY
SHEET
CIRCLE
RECTANGLE
FRAME
TEXT
WIRE
POLYGON
WIRE
PART
INSTANCE
ATTRIBUTE
BUS
SEGMENT
LABEL
TEXT
WIRE
WIRE
NET
SEGMENT
JUNCTION
PINREF
TEXT
WIRE

ObjecthierarchyofaBoard:
BOARD
GRID
LAYER
LIBRARY
CIRCLE
HOLE
RECTANGLE
FRAME
TEXT
WIRE
POLYGON
WIRE
ELEMENT
ATTRIBUTE
SIGNAL

Page26of136
EAGLEUserLanguage Version5.7

CONTACTREF
POLYGON
WIRE
VIA
WIRE

UL_ARC
Datamembers
angle1 real(startangle,0.0...359.9)
angle2 real(endangle,0.0...719.9)
cap int(CAP_...)
layer int
radius int
width int
x1, y1 int(startingpoint)
x2, y2 int(endpoint)
xc, yc int(centerpoint)
SeealsoUL_WIRE

Constants
CAP_FLAT flatarcends
roundarc
CAP_ROUND
ends

Note
Startandendanglesaredefinedmathematicallypositive(i.e.counterclockwise),with
angle1<angle2.Inordertoassurethiscondition,thestartandendpointofanUL_ARC
maybeexchangedwithrespecttotheUL_WIREthearchasbeenderivedfrom.

Example
board(B) {
B.wires(W) {
if (W.arc)
printf("Arc: (%d %d), (%d %d), (%d %d)\n",
W.arc.x1, W.arc.y1, W.arc.x2, W.arc.y2, W.arc.xc, W.arc.yc);
}
}

UL_AREA
Datamembers
x1, y1 int(lowerleftcorner)
int(upperright
x2, y2
corner)
SeealsoUL_BOARD,UL_DEVICE,UL_PACKAGE,UL_SHEET,UL_SYMBOL

Page27of136
EAGLEUserLanguage Version5.7

AUL_AREAisanabstractobjectwhichgivesinformationabouttheareacoveredbyan
object.ForaUL_DEVICE,UL_PACKAGEandUL_SYMBOLtheareaisdefinedasthe
surroundingrectangleoftheobjectdefinitioninthelibrary,soevenife.g.aUL_PACKAGE
isderivedfromaUL_ELEMENT,thepackage'sareawillnotreflecttheelementsoffset
withintheboard.

Example
board(B) {
printf("Area: (%d %d), (%d %d)\n",
B.area.x1, B.area.y1, B.area.x2, B.area.y2);
}

UL_ATTRIBUTE
Datamembers
int(0=variable,i.e.allowsoverwriting,1=constantsee
constant
note)
defaultvalue string(seenote)
display int(ATTRIBUTE_DISPLAY_FLAG_...)
name string
text UL_TEXT(seenote)
value string
SeealsoUL_DEVICE,UL_PART,UL_INSTANCE,UL_ELEMENT

Constants
nothingis
ATTRIBUTE_DISPLAY_FLAG_OFF
displayed
ATTRIBUTE_DISPLAY_FLAG_VALUE valueisdisplayed
ATTRIBUTE_DISPLAY_FLAG_NAME nameisdisplayed
AUL_ATTRIBUTEcanbeusedtoaccesstheattributesthathavebeendefinedinthelibrary
foradevice,orassignedtoapartintheschematicorboard.

Note
displaycontainsabitwiseor'edvalueconsistingofATTRIBUTE_DISPLAY_FLAG_...
anddefineswhichpartsoftheattributeareactuallydrawn.Thisvalueisonlyvalidif
displayisusedinaUL_INSTANCEorUL_ELEMENTcontext.
InaUL_ELEMENTcontextconstantonlyreturnsanactualvalueiff/bannotationis
active,otherwiseitreturns0.
Thedefaultvaluememberreturnsthevalueasdefinedinthelibrary(ifdifferentfrom
theactualvalue,otherwisethesameasvalue).InaUL_ELEMENTcontext
defaultvalueonlyreturnsanactualvalueiff/bannotationisactive,otherwiseanempty
stringisreturned.
ThetextmemberisonlyavailableinaUL_INSTANCEorUL_ELEMENTcontextand

Page28of136
EAGLEUserLanguage Version5.7

returnsaUL_TEXTobjectthatcontainsallthetextparameters.Thevalueofthistextobject
isthestringasitwillbedisplayedaccordingtotheUL_ATTRIBUTE's'display'parameter.If
calledfromadifferentcontext,thedataofthereturnedUL_TEXTobjectisundefined.
Forglobalattributesonlynameandvaluearedefined.

Example
schematic(SCH) {
SCH.parts(P) {
P.attributes(A) {
printf("%s = %s\n", A.name, A.value);
}
}
}
schematic(SCH) {
SCH.attributes(A) { // global attributes
printf("%s = %s\n", A.name, A.value);
}
}

UL_BOARD
Datamembers
area UL_AREA
grid UL_GRID
name string(seenote)
Loopmembers
attributes() UL_ATTRIBUTE(seenote)
circles() UL_CIRCLE
classes() UL_CLASS
elements() UL_ELEMENT
frames() UL_FRAME
holes() UL_HOLE
layers() UL_LAYER
libraries() UL_LIBRARY
polygons() UL_POLYGON
rectangles() UL_RECTANGLE
signals() UL_SIGNAL
texts() UL_TEXT
wires() UL_WIRE
SeealsoUL_LIBRARY,UL_SCHEMATIC

Note
Thenamememberreturnsthefullfilename,includingthedirectory.
Theattributes()loopmemberloopsthroughtheglobalattributes.

Page29of136
EAGLEUserLanguage Version5.7

Example
board(B) {
B.elements(E) printf("Element: %s\n", E.name);
B.signals(S) printf("Signal: %s\n", S.name);
}

UL_BUS
Datamembers
name string(BUS_NAME_LENGTH)
Loopmembers
segments() UL_SEGMENT
SeealsoUL_SHEET

Constants
BUS_NAME_LENG max.lengthofabusname(obsoleteasfromversion4busnames
TH canhaveanylength)

Example
schematic(SCH) {
SCH.sheets(SH) {
SH.busses(B) printf("Bus: %s\n", B.name);
}
}

UL_CIRCLE
Datamembers
layer int
radius int
width int
x, y int(centerpoint)
SeealsoUL_BOARD,UL_PACKAGE,UL_SHEET,UL_SYMBOL

Example
board(B) {
B.circles(C) {
printf("Circle: (%d %d), r=%d, w=%d\n",
C.x, C.y, C.radius, C.width);
}
}

UL_CLASS
Datamembers
clearance[number] int(seenote)

Page30of136
EAGLEUserLanguage Version5.7

drill int
name string(seenote)
number int
width int
SeealsoDesignRules,UL_NET,UL_SIGNAL,UL_SCHEMATIC,UL_BOARD

Note
Theclearancememberreturnstheclearancevaluebetweenthisnetclassandthenet
classwiththegivennumber.Ifthenumber(andthesquarebrackets)isommitted,thenet
class'sownclearancevalueisreturned.Ifanumberisgiven,itmustbebetween0andthe
numberofthisnetclass.
Ifthenamememberreturnsanemptystring,thenetclassisnotdefinedandthereforenot
inusebyanysignalornet.

Example
board(B) {
B.signals(S) {
printf("%-10s %d %s\n", S.name, S.class.number, S.class.name);
}
}

UL_CONTACT
Datamembers
name string(CONTACT_NAME_LENGTH)
pad UL_PAD
signal string
smd UL_SMD
x, y int(centerpoint,seenote)
SeealsoUL_PACKAGE,UL_PAD,UL_SMD,UL_CONTACTREF,UL_PINREF

Constants
CONTACT_NAME_LENG max.recommendedlengthofacontactname(usedinformatted
TH outputonly)

Note
Thesignaldatamemberreturnsthesignalthiscontactisconnectedto(onlyavailablein
aboardcontext).
Thecoordinates(x, y)ofthecontactdependonthecontextinwhichitiscalled:
ifthecontactisderivedfromaUL_LIBRARYcontext,thecoordinatesofthecontact
willbethesameasdefinedinthepackagedrawing
inallothercases,theywillhavetheactualvaluesfromtheboard

Page31of136
EAGLEUserLanguage Version5.7

Example
library(L) {
L.packages(PAC) {
PAC.contacts(C) {
printf("Contact: '%s', (%d %d)\n",
C.name, C.x, C.y);
}
}
}

UL_CONTACTREF
Datamembers
contact UL_CONTACT
element UL_ELEMENT
SeealsoUL_SIGNAL,UL_PINREF

Example
board(B) {
B.signals(S) {
printf("Signal '%s'\n", S.name);
S.contactrefs(C) {
printf("\t%s, %s\n", C.element.name, C.contact.name);
}
}
}

UL_DEVICE
Datamembers
area UL_AREA
description string
headline string
library string
name string(DEVICE_NAME_LENGTH)
package UL_PACKAGE(seenote)
prefix string(DEVICE_PREFIX_LENGTH)
technologies string(seenote)
value string("On"or"Off")
Loopmembers
attributes() UL_ATTRIBUTE(seenote)
gates() UL_GATE
SeealsoUL_DEVICESET,UL_LIBRARY,UL_PART

Constants
max.recommendedlengthofadevicename(usedinformatted
DEVICE_NAME_LENGTH
outputonly)

Page32of136
EAGLEUserLanguage Version5.7

DEVICE_PREFIX_LENG max.recommendedlengthofadeviceprefix(usedinformatted
TH outputonly)
AllmembersofUL_DEVICE,exceptfornameandtechnologies,returnthesamevalues
astherespectivemembersoftheUL_DEVICESETinwhichtheUL_DEVICEhasbeen
defined.Thenamememberreturnsthenameofthepackagevariantthisdevicehasbeen
createdforusingthePACKAGEcommand.Whenusingthedescriptiontextkeepin
mindthatitmaycontainnewlinecharacters('\n').

Note
Thepackagedatamemberreturnsthepackagethathasbeenassignedtothedevice
throughaPACKAGEcommand.Itcanbeusedasabooleanfunctiontocheckwhethera
packagehasbeenassignedtoadevice(seeexamplebelow).
Thevaluereturnedbythetechnologiesmemberdependsonthecontextinwhichitis
called:
ifthedeviceisderivedfromaUL_DEVICESET,technologieswillreturnastring
containingallofthedevice'stechnologies,separatedbyblanks
ifthedeviceisderivedfromaUL_PART,onlytheactualtechnologyusedbythepart
willbereturned.
Theattributes()loopmembertakesanadditionalparameterthatspecifiesforwhich
technologytheattributesshallbedelivered(seethesecondexamplebelow).

Examples
library(L) {
L.devicesets(S) {
S.devices(D) {
if (D.package)
printf("Device: %s, Package: %s\n", D.name, D.package.name);
D.gates(G) {
printf("\t%s\n", G.name);
}
}
}
}

library(L) {
L.devicesets(DS) {
DS.devices(D) {
string t[];
int n = strsplit(t, D.technologies, ' ');
for (int i = 0; i < n; i++) {
D.attributes(A, t[i]) {
printf("%s = %s\n", A.name, A.value);
}
}
}
}
}

Page33of136
EAGLEUserLanguage Version5.7

UL_DEVICESET
Datamembers
area UL_AREA
description string
headline string(seenote)
library string
name string(DEVICE_NAME_LENGTH)
prefix string(DEVICE_PREFIX_LENGTH)
value string("On"or"Off")
Loopmembers
devices() UL_DEVICE
gates() UL_GATE
SeealsoUL_DEVICE,UL_LIBRARY,UL_PART

Constants
max.recommendedlengthofadevicename(usedinformatted
DEVICE_NAME_LENGTH
outputonly)
DEVICE_PREFIX_LENG max.recommendedlengthofadeviceprefix(usedinformatted
TH outputonly)

Note
Thedescriptionmemberreturnsthecompletedescriptivetextasdefinedwiththe
DESCRIPTIONcommand,whiletheheadlinememberreturnsonlythefirstlineofthe
description,withoutanyHTMLtags.Whenusingthedescriptiontextkeepinmindthat
itmaycontainnewlinecharacters('\n').

Example
library(L) {
L.devicesets(D) {
printf("Device set: %s, Description: %s\n", D.name, D.description);
D.gates(G) {
printf("\t%s\n", G.name);
}
}
}

UL_ELEMENT
Datamembers
angle real(0.0...359.9)
attribute[] string(seenote)
column string(seenote)
locked int
mirror int

Page34of136
EAGLEUserLanguage Version5.7

name string(ELEMENT_NAME_LENGTH)
package UL_PACKAGE
row string(seenote)
smashed int(seenote)
spin int
value string(ELEMENT_VALUE_LENGTH)
x, y int(originpoint)
Loopmembers
attributes() UL_ATTRIBUTE
texts() UL_TEXT(seenote)
SeealsoUL_BOARD,UL_CONTACTREF

Constants
ELEMENT_NAME_LENGT max.recommendedlengthofanelementname(usedin
H formattedoutputonly)
ELEMENT_VALUE_LENG max.recommendedlengthofanelementvalue(usedin
TH formattedoutputonly)

Note
Theattribute[]membercanbeusedtoqueryaUL_ELEMENTforthevalueofagiven
attribute(seethesecondexamplebelow).Thereturnedstringisemptyifthereisno
attributebythegivenname,orifthisattributeisexplicitlyempty.
Thetexts()memberonlyloopsthroughthosetextsoftheelementthathavebeen
detachedusingSMASH,andthroughthevisibletextsofanyattributesassignedtothis
element.Toprocessalltextsofanelement(e.g.whendrawingit),youhavetoloop
throughtheelement'sowntexts()memberaswellasthetexts()memberofthe
element'spackage.
angledefineshowmanydegreestheelementisrotatedcounterclockwisearoundits
origin.
Thecolumn()androw()membersreturnthecolumnandrowlocationwithintheframe
intheboarddrawing.Ifthereisnoframeinthedrawing,ortheelementisplacedoutside
theframe,a'?'(questionmark)isreturned.
Thesmashedmembertellswhethertheelementissmashed.Thisfunctioncanalsobeused
tofindoutwhetherthereisadetachedtextparameterbygivingthenameofthat
parameterinsquarebrackets,asinsmashed["VALUE"].Thisisusefulincaseyouwantto
selectsuchatextwiththeMOVEcommandbydoingMOVE R5>VALUE.Validparameter
namesare"NAME"and"VALUE",aswellasthenamesofanyuserdefinedattributes.They
aretreatedcaseinsensitive,andtheymaybeprecededbya'>'character.

Examples
board(B) {
B.elements(E) {
printf("Element: %s, (%d %d), Package=%s\n",

Page35of136
EAGLEUserLanguage Version5.7

E.name, E.x, E.y, E.package.name);

}
}

board(B) {
B.elements(E) {
if (E.attribute["REMARK"])
printf("%s: %s\n", E.name, E.attribute("REMARK"));
}
}

UL_FRAME
Datamembers
columns int(-127...127)
rows int(-26...26)
border int(FRAME_BORDER_...)
layer int
x1, y1 int(lowerleftcorner)
x2, y2 int(upperrightcorner)
Loopmembers
texts() UL_TEXT
wires() UL_WIRE
SeealsoUL_BOARD,UL_PACKAGE,UL_SHEET,UL_SYMBOL

Constants
bottomborderis
FRAME_BORDER_BOTTOM
drawn
FRAME_BORDER_RIGHT rightborderisdrawn
FRAME_BORDER_TOP topborderisdrawn
FRAME_BORDER_LEFT leftborderisdrawn

Note
bordercontainsabitwiseor'edvalueconsistingofFRAME_BORDER_...anddefines
whichofthefourbordersareactuallydrawn.
Thetexts()andwires()loopmembersloopthroughallthetextsandwirestheframe
consistsof.

Example
board(B) {
B.frames(F) {
printf("Frame: (%d %d), (%d %d)\n",
F.x1, F.y1, F.x2, F.y2);
}
}

Page36of136
EAGLEUserLanguage Version5.7

UL_GATE
Datamembers
addlevel int(GATE_ADDLEVEL_...)
name string(GATE_NAME_LENGTH)
swaplevel int
symbol UL_SYMBOL
x, y int(originpoint,seenote)
SeealsoUL_DEVICE

Constants
GATE_ADDLEVEL_MUST must
GATE_ADDLEVEL_CAN can
GATE_ADDLEVEL_NEXT next
GATE_ADDLEVEL_REQUEST request
GATE_ADDLEVEL_ALWAYS always
GATE_NAME_LENGT max.recommendedlengthofagatename(usedinformatted
H outputonly)

Note
Thecoordinatesoftheoriginpoint(x,y)arealwaysthoseofthegate'spositionwithinthe
device,eveniftheUL_GATEhasbeenderivedfromaUL_INSTANCE.

Example
library(L) {
L.devices(D) {
printf("Device: %s, Package: %s\n", D.name, D.package.name);
D.gates(G) {
printf("\t%s, swaplevel=%d, symbol=%s\n",
G.name, G.swaplevel, G.symbol.name);
}
}
}

UL_GRID
Datamembers
distance real
dots int(0=lines,1=dots)
multiple int
on int(0=off,1=on)
unit int(GRID_UNIT_...)
unitdist int(GRID_UNIT_...)
SeealsoUL_BOARD,UL_LIBRARY,UL_SCHEMATIC,UnitConversions

Page37of136
EAGLEUserLanguage Version5.7

Constants
GRID_UNIT_MIC microns
GRID_UNIT_MM millimeter
GRID_UNIT_MIL mil
GRID_UNIT_INCH inch

Note
unitdistreturnsthegridunitthatwassettodefinetheactualgridsize(returnedby
distance),whileunitreturnsthegridunitthatisusedtodisplayvaluesorinterpret
userinput.

Example
board(B) {
printf("Gridsize=%f\n", B.grid.distance);
}

UL_HOLE
Datamembers
diameter[layer] int(seenote)
drill int
drillsymbol int
x, y int(centerpoint)
SeealsoUL_BOARD,UL_PACKAGE

Note
diameter[]isonlydefinedvorlayersLAYER_TSTOPandLAYER_BSTOPandreturnsthe
diameterofthesolderstopmaskinthegivenlayer.
drillsymbolreturnsthenumberofthedrillsymbolthathasbeenassignedtothisdrill
diameter(seethemanualforalistofdefineddrillsymbols).Avalueof0meansthatno
symbolhasbeenassignedtothisdrilldiameter.

Example
board(B) {
B.holes(H) {
printf("Hole: (%d %d), drill=%d\n",
H.x, H.y, H.drill);
}
}

UL_INSTANCE
Datamembers
angle real(0,90,180and270)

Page38of136
EAGLEUserLanguage Version5.7

column string(seenote)
gate UL_GATE
mirror int
name string(INSTANCE_NAME_LENGTH)
row string(seenote)
sheet int(0=unused,>0=sheetnumber)
smashed int(seenote)
value string(PART_VALUE_LENGTH)
x, y int(originpoint)
Loopmembers
attributes() UL_ATTRIBUTE(seenote)
texts() UL_TEXT(seenote)
xrefs() UL_GATE(seenote)
SeealsoUL_PART,UL_PINREF

Constants
INSTANCE_NAME_LEN max.recommendedlengthofaninstancename(usedin
GTH formattedoutputonly)
max.recommendedlengthofapartvalue(instancesdonothave
PART_VALUE_LENGTH
avalueoftheirown!)

Note
Theattributes()memberonlyloopsthroughthoseattributesthathavebeenexplicitly
assignedtothisinstance(includingsmashedattributes).
Thetexts()memberonlyloopsthroughthosetextsoftheinstancethathavebeen
detachedusingSMASH,andthroughthevisibletextsofanyattributesassignedtothis
instance.Toprocessalltextsofaninstance,youhavetoloopthroughtheinstance'sown
texts()memberaswellasthetexts()memberoftheinstance'sgate'ssymbol.If
attributeshavebeenassignedtoaninstance,texts()deliverstheirtextsintheformas
theyarecurrentlyvisible.
Thecolumn()androw()membersreturnthecolumnandrowlocationwithintheframe
onthesheetonwhichthisinstanceisinvoked.Ifthereisnoframeonthatsheet,orthe
instanceisplacedoutsidetheframe,a'?'(questionmark)isreturned.Thesemembers
canonlybeusedinasheetcontext.
Thesmashedmembertellswhethertheinstanceissmashed.Thisfunctioncanalsobe
usedtofindoutwhetherthereisadetachedtextparameterbygivingthenameofthat
parameterinsquarebrackets,asinsmashed["VALUE"].Thisisusefulincaseyouwantto
selectsuchatextwiththeMOVEcommandbydoingMOVE R5>VALUE.Validparameter
namesare"NAME","VALUE","PART"and"GATE",aswellasthenamesofanyuserdefined
attributes.Theyaretreatedcaseinsensitive,andtheymaybeprecededbya'>'character.
Thexrefs()memberloopsthroughthecontactcrossreferencegatesofthisinstance.
TheseareonlyofimportanceiftheULPisgoingtocreateadrawingofsomesort(for
instanceaDXFfile).

Page39of136
EAGLEUserLanguage Version5.7

Example
schematic(S) {
S.parts(P) {
printf("Part: %s\n", P.name);
P.instances(I) {
if (I.sheet != 0)
printf("\t%s used on sheet %d\n", I.name, I.sheet);
}
}
}

UL_JUNCTION
Datamembers
diameter int
x, y int(centerpoint)
SeealsoUL_SEGMENT

Example
schematic(SCH) {
SCH.sheets(SH) {
SH.nets(N) {
N.segments(SEG) {
SEG.junctions(J) {
printf("Junction: (%d %d)\n", J.x, J.y);
}
}
}
}
}

UL_LABEL
Datamembers
angle real(0.0...359.9)
layer int
mirror int
spin int
text UL_TEXT
x, y int(originpoint)
int(0=plain,1=cross
xref
reference)
Loopmembers
wires() UL_WIRE(seenote)
SeealsoUL_SEGMENT

Note
Ifxrefreturnsanonzerovalue,thewires()loopmemberloopsthroughthewiresthat

Page40of136
EAGLEUserLanguage Version5.7

formtheflagofacrossreferencelabel.Otherwiseitisanemptyloop.
Theangle,layer,mirrorandspinmembersalwaysreturnthesamevaluesasthoseof
theUL_TEXTobjectreturnedbythetextmember.Thexandymembersofthetextreturn
slightlyoffsetvaluesforcrossreferencelabels(nonzeroxref),otherwisetheyalsoreturn
thesamevaluesastheUL_LABEL.
xrefisonlymeaningfulfornetlabels.Forbuslabelsitalwaysreturns0.

Example
sheet(SH) {
SH.nets(N) {
N.segments(S) {
S.labels(L) {
printf("Label: %d %d '%s'\n", L.x, L.y, L.text.value);
}
}
}
}

UL_LAYER
Datamembers
color int
fill int
name string(LAYER_NAME_LENGTH)
number int
used int(0=unused,1=used)
visible int(0=off,1=on)
SeealsoUL_BOARD,UL_LIBRARY,UL_SCHEMATIC

Constants
LAYER_NAME_LENGT max.recommendedlengthofalayername(usedinformatted
H outputonly)
LAYER_TOP layernumbers
LAYER_BOTTOM
LAYER_PADS
LAYER_VIAS
LAYER_UNROUTED
LAYER_DIMENSION
LAYER_TPLACE
LAYER_BPLACE
LAYER_TORIGINS
LAYER_BORIGINS
LAYER_TNAMES
LAYER_BNAMES
LAYER_TVALUES

Page41of136
EAGLEUserLanguage Version5.7

LAYER_BVALUES
LAYER_TSTOP
LAYER_BSTOP
LAYER_TCREAM
LAYER_BCREAM
LAYER_TFINISH
LAYER_BFINISH
LAYER_TGLUE
LAYER_BGLUE
LAYER_TTEST
LAYER_BTEST
LAYER_TKEEPOUT
LAYER_BKEEPOUT
LAYER_TRESTRICT
LAYER_BRESTRICT
LAYER_VRESTRICT
LAYER_DRILLS
LAYER_HOLES
LAYER_MILLING
LAYER_MEASURES
LAYER_DOCUMENT
LAYER_REFERENCE
LAYER_TDOCU
LAYER_BDOCU
LAYER_NETS
LAYER_BUSSES
LAYER_PINS
LAYER_SYMBOLS
LAYER_NAMES
LAYER_VALUES
LAYER_INFO
LAYER_GUIDE
LAYER_USER lowestnumberforuserdefinedlayers(100)

Example
board(B) {
B.layers(L) printf("Layer %3d %s\n", L.number, L.name);
}

UL_LIBRARY
Datamembers
description string(seenote)
grid UL_GRID

Page42of136
EAGLEUserLanguage Version5.7

headline string
name string(LIBRARY_NAME_LENGTH,seenote)
Loopmembers
devices() UL_DEVICE
devicesets() UL_DEVICESET
layers() UL_LAYER
packages() UL_PACKAGE
symbols() UL_SYMBOL
SeealsoUL_BOARD,UL_SCHEMATIC

Constants
LIBRARY_NAME_LENG max.recommendedlengthofalibraryname(usedinformatted
TH outputonly)
Thedevices()memberloopsthroughallthepackagevariantsandtechnologiesofall
UL_DEVICESETsinthelibrary,thusresultinginalltheactualdevicevariationsavailable.
Thedevicesets()memberonlyloopsthroughtheUL_DEVICESETs,whichinturncan
bequeriedfortheirUL_DEVICEmembers.

Note
Thedescriptionmemberreturnsthecompletedescriptivetextasdefinedwiththe
DESCRIPTIONcommand,whiletheheadlinememberreturnsonlythefirstlineofthe
description,withoutanyHTMLtags.Whenusingthedescriptiontextkeepinmindthat
itmaycontainnewlinecharacters('\n').Thedescriptionandheadlineinformation
isonlyavailablewithinalibrarydrawing,notifthelibraryisderivedformaUL_BOARDor
UL_SCHEMATICcontext.
IfthelibraryisderivedformaUL_BOARDorUL_SCHEMATICcontext,namereturnsthe
purelibraryname(withoutpathorextension).Otherwiseitreturnsthefulllibraryfile
name.

Example
library(L) {
L.devices(D) printf("Dev: %s\n", D.name);
L.devicesets(D) printf("Dev: %s\n", D.name);
L.packages(P) printf("Pac: %s\n", P.name);
L.symbols(S) printf("Sym: %s\n", S.name);
}
schematic(S) {
S.libraries(L) printf("Library: %s\n", L.name);
}

UL_NET
Datamembers
class UL_CLASS
column string(seenote)

Page43of136
EAGLEUserLanguage Version5.7

name string(NET_NAME_LENGTH)
row string(seenote)
Loopmembers
pinrefs() UL_PINREF(seenote)
segments() UL_SEGMENT(seenote)
SeealsoUL_SHEET,UL_SCHEMATIC

Constants
max.recommendedlengthofanetname(usedinformattedoutput
NET_NAME_LENGTH
only)

Note
Thepinrefs()loopmembercanonlybeusedifthenetisinaschematiccontext.
Thesegments()loopmembercanonlybeusedifthenetisinasheetcontext.
Thecolumn()androw()membersreturnthecolumnandrowlocationswithintheframe
onthesheetonwhichthisnetisdrawn.Sinceanetcanextendoveracertainarea,eachof
thesefunctionsreturnstwovalues,separatedbyablank.Incaseofcolumn()theseare
theleftandrightmostcolumnstouchedbythenet,andincaseofrow()it'sthetopand
bottommostrow.Ifthereisnoframeonthatsheet,"? ?"(twoquestionmarks)is
returned.Ifanypartofthenetisplacedoutsidetheframe,eitherofthevaluesmaybe'?'
(questionmark).Thesememberscanonlybeusedinasheetcontext.

Example
schematic(S) {
S.nets(N) {
printf("Net: %s\n", N.name);
// N.segments(SEG) will NOT work here!
}
}
schematic(S) {
S.sheets(SH) {
SH.nets(N) {
printf("Net: %s\n", N.name);
N.segments(SEG) {
SEG.wires(W) {
printf("\tWire: (%d %d) (%d %d)\n",
W.x1, W.y1, W.x2, W.y2);
}
}
}
}
}

UL_PACKAGE
Datamembers
area UL_AREA

Page44of136
EAGLEUserLanguage Version5.7

description string
headline string
library string
name string(PACKAGE_NAME_LENGTH)
Loopmembers
circles() UL_CIRCLE
contacts() UL_CONTACT
frames() UL_FRAME
holes() UL_HOLE
polygons() UL_POLYGON
rectangles() UL_RECTANGLE
texts() UL_TEXT(seenote)
wires() UL_WIRE
SeealsoUL_DEVICE,UL_ELEMENT,UL_LIBRARY

Constants
PACKAGE_NAME_LENG max.recommendedlengthofapackagename(usedinformatted
TH outputonly)

Note
Thedescriptionmemberreturnsthecompletedescriptivetextasdefinedwiththe
DESCRIPTIONcommand,whiletheheadlinememberreturnsonlythefirstlineofthe
description,withoutanyHTMLtags.Whenusingthedescriptiontextkeepinmindthat
itmaycontainnewlinecharacters('\n').
IftheUL_PACKAGEisderivedfromaUL_ELEMENT,thetexts()memberonlyloops
throughthenondetachedtextsofthatelement.

Example
library(L) {
L.packages(PAC) {
printf("Package: %s\n", PAC.name);
PAC.contacts(C) {
if (C.pad)
printf("\tPad: %s, (%d %d)\n",
C.name, C.pad.x, C.pad.y);
else if (C.smd)
printf("\tSmd: %s, (%d %d)\n",
C.name, C.smd.x, C.smd.y);
}
}
}
board(B) {
B.elements(E) {
printf("Element: %s, Package: %s\n", E.name, E.package.name);
}
}

Page45of136
EAGLEUserLanguage Version5.7

UL_PAD
Datamembers
angle real(0.0...359.9)
diameter[layer] int
drill int
drillsymbol int
elongation int
flags int(PAD_FLAG_...)
name string(PAD_NAME_LENGTH)
shape[layer] int(PAD_SHAPE_...)
signal string
x, y int(centerpoint,seenote)
SeealsoUL_PACKAGE,UL_CONTACT,UL_SMD

Constants
PAD_FLAG_STOP generatestopmask
PAD_FLAG_THERMALS generatethermals
usespecial"firstpad"
PAD_FLAG_FIRST
shape
PAD_SHAPE_SQUARE square
PAD_SHAPE_ROUND round
PAD_SHAPE_OCTAGON octagon
PAD_SHAPE_LONG long
PAD_SHAPE_OFFSET offset
annulus(onlyifsupplylayersare
PAD_SHAPE_ANNULUS
used)
thermal(onlyifsupplylayersare
PAD_SHAPE_THERMAL
used)
PAD_NAME_LENGT max.recommendedlengthofapadname(sameas
H CONTACT_NAME_LENGTH)

Note
Theparametersofthepaddependonthecontextinwhichitisaccessed:
ifthepadisderivedfromaUL_LIBRARYcontext,thecoordinates(x, y)andangle
willbethesameasdefinedinthepackagedrawing
inallothercases,theywillhavetheactualvaluesfromtheboard
Thediameterandshapeofthepaddependonthelayerforwhichtheyshallberetrieved,
becausetheymaybedifferentineachlayerdependingontheDesignRules.Ifoneofthe
layersLAYER_TOP...LAYER_BOTTOM,LAYER_TSTOPorLAYER_BSTOPisgivenasthe
indextothediameterorshapedatamember,theresultingvaluewillbecalculated
accordingtotheDesignRules.IfLAYER_PADSisgiven,therawvalueasdefinedinthe
librarywillbereturned.

Page46of136
EAGLEUserLanguage Version5.7

drillsymbolreturnsthenumberofthedrillsymbolthathasbeenassignedtothisdrill
diameter(seethemanualforalistofdefineddrillsymbols).Avalueof0meansthatno
symbolhasbeenassignedtothisdrilldiameter.
angledefineshowmanydegreesthepadisrotatedcounterclockwisearounditscenter.
elongationisonlyvalidforshapesPAD_SHAPE_LONGandPAD_SHAPE_OFFSETand
defineshowmanypercentthelongsideofsuchapadislongerthanitssmallside.This
memberreturns0foranyotherpadshapes.
ThevaluereturnedbyflagsmustbemaskedwiththePAD_FLAG_...constantsto
determinetheindividualflagsettings,asin
if (pad.flags & PAD_FLAG_STOP) {
...
}

NotethatifyourULPjustwantstodrawtheobjects,youdon'tneedtochecktheseflags
explicitly.Thediameter[]andshape[]memberswillreturntheproperdata;for
instance,ifPAD_FLAG_STOPisset,diameter[LAYER_TSTOP]willreturn0,which
shouldresultinnothingbeingdrawninthatlayer.TheflagsmemberismainlyforULPs
thatwanttocreatescriptfilesthatcreatelibraryobjects.

Example
library(L) {
L.packages(PAC) {
PAC.contacts(C) {
if (C.pad)
printf("Pad: '%s', (%d %d), d=%d\n",
C.name, C.pad.x, C.pad.y, C.pad.diameter[LAYER_BOTTOM]);
}
}
}

UL_PART
Datamembers
attribute[] string(seenote)
device UL_DEVICE
deviceset UL_DEVICESET
name string(PART_NAME_LENGTH)
value string(PART_VALUE_LENGTH)
Loopmembers
attributes() UL_ATTRIBUTE(seenote)
instances() UL_INSTANCE(seenote)
SeealsoUL_SCHEMATIC,UL_SHEET

Constants
PART_NAME_LENGTH max.recommendedlengthofapartname(usedinformatted

Page47of136
EAGLEUserLanguage Version5.7

outputonly)
PART_VALUE_LENGT max.recommendedlengthofapartvalue(usedinformatted
H outputonly)

Note
Theattribute[]membercanbeusedtoqueryaUL_PARTforthevalueofagiven
attribute(seethesecondexamplebelow).Thereturnedstringisemptyifthereisno
attributebythegivenname,orifthisattributeisexplicitlyempty.
Whenloopingthroughtheattributes()ofaUL_PART,onlythename,value,
defaultvalueandconstantmembersoftheresultingUL_ATTRIBUTEobjectsare
valid.
Ifthepartisinasheetcontext,theinstances()loopmemberloopsonlythroughthose
instancesthatareactuallyusedonthatsheet.Ifthepartisinaschematiccontext,all
instancesareloopedthrough.

Example
schematic(S) {
S.parts(P) printf("Part: %s\n", P.name);
}

schematic(SCH) {
SCH.parts(P) {
if (P.attribute["REMARK"])
printf("%s: %s\n", P.name, P.attribute["REMARK"]);
}
}

UL_PIN
Datamembers
angle real(0,90,180and270)
contact UL_CONTACT(seenote)
direction int(PIN_DIRECTION_...)
function int(PIN_FUNCTION_FLAG_...)
length int(PIN_LENGTH_...)
name string(PIN_NAME_LENGTH)
net string(seenote)
swaplevel int
visible int(PIN_VISIBLE_FLAG_...)
x, y int(connectionpoint)
Loopmembers
circles() UL_CIRCLE
texts() UL_TEXT
wires() UL_WIRE
SeealsoUL_SYMBOL,UL_PINREF,UL_CONTACTREF

Page48of136
EAGLEUserLanguage Version5.7

Constants
PIN_DIRECTION_NC notconnected
PIN_DIRECTION_IN input
PIN_DIRECTION_OUT output(totempole)
PIN_DIRECTION_IO in/output(bidirectional)
PIN_DIRECTION_OC opencollector
PIN_DIRECTION_PWR powerinputpin
PIN_DIRECTION_PAS passive
PIN_DIRECTION_HIZ highimpedanceoutput
PIN_DIRECTION_SUP supplypin
PIN_FUNCTION_FLAG_NONE nosymbol
PIN_FUNCTION_FLAG_DOT invertersymbol
PIN_FUNCTION_FLAG_CLK clocksymbol
PIN_LENGTH_POINT nowire
PIN_LENGTH_SHORT 0.1inchwire
PIN_LENGTH_MIDDLE 0.2inchwire
PIN_LENGTH_LONG 0.3inchwire
max.recommendedlengthofapinname(usedinformattedoutput
PIN_NAME_LENGTH
only)
PIN_VISIBLE_FLAG_OFF nonamedrawn
PIN_VISIBLE_FLAG_PAD padnamedrawn
PIN_VISIBLE_FLAG_PIN pinnamedrawn

Note
Thecontactdatamemberreturnsthecontactthathasbeenassignedtothepinthrougha
CONNECTcommand.Itcanbeusedasabooleanfunctiontocheckwhetheracontacthas
beenassignedtoapin(seeexamplebelow).
Thecoordinates(andlayer,incaseofanSMD)ofthecontactreturnedbythecontact
datamemberdependonthecontextinwhichitiscalled:
ifthepinisderivedfromaUL_PARTthatisusedonasheet,andifthereisa
correspondingelementontheboard,theresultingcontactwillhavethecoordinates
asusedontheboard
inallothercases,thecoordinatesofthecontactwillbethesameasdefinedinthe
packagedrawing
Thenamedatamemberalwaysreturnsthenameofthepinasitwasdefinedinthelibrary,
withany'@'characterforpinswiththesamenameleftintact(seethePINcommandfor
details).
Thetextsloopmember,ontheotherhand,returnsthepinname(ifitisvisible)inthe
samewayasitisdisplayedinthecurrentdrawingtype.
Thenetdatamemberreturnsthenameofthenettowhichthispinisconnected(only
availableinaschematiccontext).

Page49of136
EAGLEUserLanguage Version5.7

Example
library(L) {
L.symbols(S) {
printf("Symbol: %s\n", S.name);
S.pins(P) {
printf("\tPin: %s, (%d %d)", P.name, P.x, P.y);
if (P.direction == PIN_DIRECTION_IN)
printf(" input");
if ((P.function & PIN_FUNCTION_FLAG_DOT) != 0)
printf(" inverted");
printf("\n");
}
}
L.devices(D) {
D.gates(G) {
G.symbol.pins(P) {
if (!P.contact)
printf("Unconnected pin: %s/%s/%s\n", D.name, G.name, P.name);
}
}
}
}

UL_PINREF
Datamembers
instance UL_INSTANCE
part UL_PART
pin UL_PIN
SeealsoUL_SEGMENT,UL_CONTACTREF

Example
schematic(SCH) {
SCH.sheets(SH) {
printf("Sheet: %d\n", SH.number);
SH.nets(N) {
printf("\tNet: %s\n", N.name);
N.segments(SEG) {
SEG.pinrefs(P) {
printf("connected to: %s, %s, %s\n",
P.part.name, P.instance.name, P.pin.name);
}
}
}
}
}

UL_POLYGON
Datamembers
isolate int
layer int

Page50of136
EAGLEUserLanguage Version5.7

orphans int(0=off,1=on)
pour int(POLYGON_POUR_...)
rank int
spacing int
thermals int(0=off,1=on)
width int
Loopmembers
contours() UL_WIRE(seenote)
fillings() UL_WIRE
wires() UL_WIRE
SeealsoUL_BOARD,UL_PACKAGE,UL_SHEET,UL_SIGNAL,UL_SYMBOL

Constants
POLYGON_POUR_SOLID solid
POLYGON_POUR_HATCH hatch

Note
Thecontours()andfillings()loopmembersloopthroughthewiresthatareusedto
drawthecalculatedpolygonifitispartofasignalandthepolygonhasbeencalculatedby
theRATSNESTcommand.Thewires()loopmemberalwaysloopsthroughthepolygon
wiresastheyweredrawnbytheuser.Foranuncalculatedsignalpolygoncontours()
doesthesameaswires(),andfillings()doesnothing.
Ifthecontours()loopmemberiscalledwithoutasecondparameter,itloopsthroughall
ofthecontourwires,regardlesswhethertheybelongtoapositiveoranegativepolygon.If
youareinterestedingettingthepositiveandnegativecontourwiresseparately,youcancall
contours()withanadditionalintegerparameter(seethesecondexamplebelow).The
signofthatparameterdetermineswhetherapositiveoranegativepolygonwillbehandled,
andthevalueindicatestheindexofthatpolygon.Ifthereisnopolygonwiththegiven
index,thestatementwillnotbeexecuted.Anotheradvantageofthismethodisthatyou
don'tneedtodeterminethebeginningandendofaparticularpolygonyourself(by
comparingcoordinates).Foranygivenindex,thestatementwillbeexecutedforallthe
wiresofthatpolygon.Withthesecondparameter0thebehavioristhesameaswithouta
secondparameter.

Polygon width
Whenusingthefillings()loopmembertogetthefillwiresofasolidpolygon,make
surethewidthofthepolygonisnotzero(actuallyitshouldbequiteabitlargerthanzero,
forexampleatleastthehardwareresolutionoftheoutputdeviceyouaregoingtodraw
on).Fillingapolygonwithzerowidthmayresultinenormousamountsofdata,since
itwillbecalculatedwiththesmallesteditorresolutionof1/10000mm!

Partial polygons
Acalculatedsignalpolygonmayconsistofseveraldistinctparts(calledpositivepolygons),

Page51of136
EAGLEUserLanguage Version5.7

eachofwhichcancontainextrusions(negativepolygons)resultingfromotherobjectsbeing
subtractedfromthepolygon.Negativepolygonscanagaincontainotherpositivepolygons
andsoon.
Thewiresloopedthroughbycontours()alwaysstartwithapositivepolygon.Tofindout
whereonepartialpolygonendsandthenextonebegins,simplystorethe(x1,y1)
coordinatesofthefirstwireandcheckthemagainst(x2,y2)ofeveryfollowingwire.As
soonastheseareequal,thelastwireofapartialpolygonhasbeenfound.Itisalso
guaranteedthatthesecondpoint(x2,y2)ofonewireisidenticaltothefirstpoint(x1,y1)of
thenextwireinthatpartialpolygon.
Tofindoutwherethe"inside"andthe"outside"ofthepolygonlays,takeanycontourwire
andimaginelookingfromitspoint(x1,y1)to(x2,y2).The"inside"ofthepolygonisalways
ontherightsideofthewire.Notethatifyousimplywanttodrawthepolygonyouwon't
needallthesedetails.

Example
board(B) {
B.signals(S) {
S.polygons(P) {
int x0, y0, first = 1;
P.contours(W) {
if (first) {
// a new partial polygon is starting
x0 = W.x1;
y0 = W.y1;
}
// ...
// do something with the wire
// ...
if (first)
first = 0;
else if (W.x2 == x0 && W.y2 == y0) {
// this was the last wire of the partial polygon,
// so the next wire (if any) will be the first wire
// of the next partial polygon
first = 1;
}
}
}
}
}

board(B) {
B.signals(S) {
S.polygons(P) {
// handle only the "positive" polygons:
int i = 1;
int active;
do {
active = 0;
P.contours(W, i) {
active = 1;
// do something with the wire

Page52of136
EAGLEUserLanguage Version5.7

}
i++;
} while (active);
}
}
}

UL_RECTANGLE
Datamembers
angle real(0.0...359.9)
layer int
x1, y1 int(lowerleftcorner)
int(upperright
x2, y2
corner)
SeealsoUL_BOARD,UL_PACKAGE,UL_SHEET,UL_SYMBOL
angledefineshowmanydegreestherectangleisrotatedcounterclockwisearoundits
center.Thecentercoordinatesaregivenby(x1+x2)/2and(y1+y2)/2.

Example
board(B) {
B.rectangles(R) {
printf("Rectangle: (%d %d), (%d %d)\n",
R.x1, R.y1, R.x2, R.y2);
}
}

UL_SCHEMATIC
Datamembers
grid UL_GRID
name string(seenote)
xreflabel string
Loopmembers
attributes() UL_ATTRIBUTE(seenote)
classes() UL_CLASS
layers() UL_LAYER
libraries() UL_LIBRARY
nets() UL_NET
parts() UL_PART
sheets() UL_SHEET
SeealsoUL_BOARD,UL_LIBRARY

Note
Thenamememberreturnsthefullfilename,includingthedirectory.

Page53of136
EAGLEUserLanguage Version5.7

Thexreflabelmemberreturnstheformatstringusedtodisplaycrossreferencelabels.
Theattributes()loopmemberloopsthroughtheglobalattributes.

Example
schematic(S) {
S.parts(P) printf("Part: %s\n", P.name);
}

UL_SEGMENT
Loopmembers
junctions() UL_JUNCTION(seenote)
labels() UL_LABEL
pinrefs() UL_PINREF(seenote)
texts() UL_TEXT(deprecated,seenote)
wires() UL_WIRE
SeealsoUL_BUS,UL_NET

Note
Thejunctions()andpinrefs()loopmembersareonlyavailablefornetsegments.
Thetexts()loopmemberwasusedinolderEAGLEversionstoloopthroughthelabelsof
asegment,andisonlypresentforcompatibility.Itwillnotdeliverthetextofcross
referencelabelsatthecorrectposition.Usethelabels()loopmembertoaccessa
segment'slabels.

Example
schematic(SCH) {
SCH.sheets(SH) {
printf("Sheet: %d\n", SH.number);
SH.nets(N) {
printf("\tNet: %s\n", N.name);
N.segments(SEG) {
SEG.pinrefs(P) {
printf("connected to: %s, %s, %s\n",
P.part.name, P.instance.name, P.pin.name);
}
}
}
}
}

UL_SHEET
Datamembers
area UL_AREA
number int

Page54of136
EAGLEUserLanguage Version5.7

Loopmembers
busses() UL_BUS
circles() UL_CIRCLE
frames() UL_FRAME
nets() UL_NET
parts() UL_PART
polygons() UL_POLYGON
rectangles() UL_RECTANGLE
texts() UL_TEXT
wires() UL_WIRE
SeealsoUL_SCHEMATIC

Example
schematic(SCH) {
SCH.sheets(S) {
printf("Sheet: %d\n", S.number);
}
}

UL_SIGNAL
Datamembers
airwireshidden int
class UL_CLASS
name string(SIGNAL_NAME_LENGTH)
Loopmembers
contactrefs() UL_CONTACTREF
polygons() UL_POLYGON
vias() UL_VIA
wires() UL_WIRE
SeealsoUL_BOARD

Constants
SIGNAL_NAME_LENG max.recommendedlengthofasignalname(usedinformatted
TH outputonly)

Example
board(B) {
B.signals(S) printf("Signal: %s\n", S.name);
}

UL_SMD
Datamembers
angle real(0.0...359.9)

Page55of136
EAGLEUserLanguage Version5.7

dx[layer], dy[layer] int(size)

flags int(SMD_FLAG_...)
layer int(seenote)
name string(SMD_NAME_LENGTH)
roundness int(seenote)
signal string
x, y int(centerpoint,seenote)
SeealsoUL_PACKAGE,UL_CONTACT,UL_PAD

Constants
SMD_FLAG_STOP generatestopmask
SMD_FLAG_THERMALS generatethermals
generatecream
SMD_FLAG_CREAM
mask
SMD_NAME_LENGT max.recommendedlengthofansmdname(sameas
H CONTACT_NAME_LENGTH)

Note
Theparametersofthesmddependonthecontextinwhichitisaccessed:
ifthesmdisderivedfromaUL_LIBRARYcontext,thecoordinates(x, y),angle,
layerandroundnessofthesmdwillbethesameasdefinedinthepackage
drawing
inallothercases,theywillhavetheactualvaluesfromtheboard
Ifthedxanddydatamembersarecalledwithanoptionallayerindex,thedataforthat
layerisreturnedaccordingtotheDesignRules.ValidlayersareLAYER_TOP,LAYER_TSTOP
andLAYER_TCREAMforaviaintheToplayer,andLAYER_BOTTOM,LAYER_BSTOPand
LAYER_BCREAMforaviaintheBottomlayer,respectively.
angledefineshowmanydegreesthesmdisrotatedcounterclockwisearounditscenter.
ThevaluereturnedbyflagsmustbemaskedwiththeSMD_FLAG_...constantsto
determinetheindividualflagsettings,asin
if (smd.flags & SMD_FLAG_STOP) {
...
}

NotethatifyourULPjustwantstodrawtheobjects,youdon'tneedtochecktheseflags
explicitly.Thedx[]anddy[]memberswillreturntheproperdata;forinstance,if
SMD_FLAG_STOPisset,dx[LAYER_TSTOP]willreturn0,whichshouldresultinnothing
beingdrawninthatlayer.TheflagsmemberismainlyforULPsthatwanttocreatescript
filesthatcreatelibraryobjects.

Example
library(L) {
L.packages(PAC) {

Page56of136
EAGLEUserLanguage Version5.7

PAC.contacts(C) {
if (C.smd)
printf("Smd: '%s', (%d %d), dx=%d, dy=%d\n",
C.name, C.smd.x, C.smd.y, C.smd.dx, C.smd.dy);
}
}
}

UL_SYMBOL
Datamembers
area UL_AREA
library string
name string(SYMBOL_NAME_LENGTH)
Loopmembers
circles() UL_CIRCLE
frames() UL_FRAME
rectangles() UL_RECTANGLE
pins() UL_PIN
polygons() UL_POLYGON
texts() UL_TEXT(seenote)
wires() UL_WIRE
SeealsoUL_GATE,UL_LIBRARY

Constants
SYMBOL_NAME_LENG max.recommendedlengthofasymbolname(usedinformatted
TH outputonly)

Note
IftheUL_SYMBOLisderivedfromaUL_INSTANCE,thetexts()memberonlyloops
throughthenondetachedtextsofthatinstance.

Example
library(L) {
L.symbols(S) printf("Sym: %s\n", S.name);
}

UL_TEXT
Datamembers
angle real(0.0...359.9)
font int(FONT_...)
layer int
mirror int
ratio int
size int

Page57of136
EAGLEUserLanguage Version5.7

spin int
value string
x, y int(originpoint)
Loopmembers
wires() UL_WIRE(seenote)
SeealsoUL_BOARD,UL_PACKAGE,UL_SHEET,UL_SYMBOL

Constants
FONT_VECTOR vectorfont
FONT_PROPORTIONAL proportionalfont
FONT_FIXED fixedfont

Note
Thewires()loopmemberalwaysaccessestheindividualwiresthetextiscomposedof
whenusingthevectorfont,eveniftheactualfontisnotFONT_VECTOR.
IftheUL_TEXTisderivedfromaUL_ELEMENTorUL_INSTANCEcontext,themember
valueswillbethoseoftheactualtextaslocatedintheboardorsheetdrawing.

Example
board(B) {
B.texts(T) {
printf("Text: %s\n", T.value);
}
}

UL_VIA
Datamembers
diameter[layer] int
drill int
drillsymbol int
end int
flags int(VIA_FLAG_...)
shape[layer] int(VIA_SHAPE_...)
start int
x, y int(centerpoint)
SeealsoUL_SIGNAL

Constants
alwaysgeneratestop
VIA_FLAG_STOP
mask
VIA_SHAPE_SQUARE square
VIA_SHAPE_ROUND round
VIA_SHAPE_OCTAGON octagon

Page58of136
EAGLEUserLanguage Version5.7

VIA_SHAPE_ANNULUS annulus
VIA_SHAPE_THERMAL thermal

Note
Thediameterandshapeoftheviadependonthelayerforwhichtheyshallberetrieved,
becausetheymaybedifferentineachlayerdependingontheDesignRules.Ifoneofthe
layersLAYER_TOP...LAYER_BOTTOM,LAYER_TSTOPorLAYER_BSTOPisgivenasthe
indextothediameterorshapedatamember,theresultingvaluewillbecalculated
accordingtotheDesignRules.IfLAYER_VIASisgiven,therawvalueasdefinedinthevia
willbereturned.
Notethatdiameterandshapewillalwaysreturnthediameterorshapethataviawould
haveinthegivenlayer,evenifthatparticularviadoesn'tcoverthatlayer(orifthatlayer
isn'tusedinthelayersetupatall).
startandendreturnthelayernumbersinwhichthatviastartsandends.Thevalueof
startwillalwaysbelessthanthatofend.
drillsymbolreturnsthenumberofthedrillsymbolthathasbeenassignedtothisdrill
diameter(seethemanualforalistofdefineddrillsymbols).Avalueof0meansthatno
symbolhasbeenassignedtothisdrilldiameter.

Example
board(B) {
B.signals(S) {
S.vias(V) {
printf("Via: (%d %d)\n", V.x, V.y);
}
}
}

UL_WIRE
Datamembers
arc UL_ARC
cap int(CAP_...)
curve real
layer int
style int(WIRE_STYLE_...)
width int
x1, y1 int(startingpoint)
x2, y2 int(endpoint)
Loopmembers
pieces() UL_WIRE(seenote)
SeealsoUL_BOARD,UL_PACKAGE,UL_SEGMENT,UL_SHEET,UL_SIGNAL,UL_SYMBOL,
UL_ARC

Page59of136
EAGLEUserLanguage Version5.7

Constants
CAP_FLAT flatarcends
roundarc
CAP_ROUND
ends
WIRE_STYLE_CONTINUOUS continuous
WIRE_STYLE_LONGDASH longdash
WIRE_STYLE_SHORTDASH shortdash
WIRE_STYLE_DASHDOT dashdot

Wire Style
AUL_WIREthathasastyleotherthanWIRE_STYLE_CONTINUOUScanusethepieces()
loopmembertoaccesstheindividualsegmentsthatconstituteforexampleadashedwire.
Ifpieces()iscalledforaUL_WIREwithWIRE_STYLE_CONTINUOUS,asinglesegment
willbeaccessiblewhichisjustthesameastheoriginalUL_WIRE.Thepieces()loop
membercan'tbecalledfromaUL_WIREthatitselfhasbeenreturnedbyacallto
pieces()(thiswouldcauseaninfiniterecursion).

Arcs at Wire level

Arcsarebasicallywires,withafewadditionalproperties.Atthefirstlevelarcsaretreated
exactlythesameaswires,meaningtheyhaveastartandanendpoint,awidth,layerand
wirestyle.Inadditiontotheseanarc,atthewirelevel,hasacapandacurveparameter.
capdefineswhetherthearcendingsareroundorflat,andcurvedefinesthe"curvature"of
thearc.Thevalidrangeforcurveis-360..+360,anditsvaluemeanswhatpartofafull
circlethearcconsistsof.Avalueof90,forinstance,wouldresultina90arc,while180
wouldgiveyouasemicircle.Themaximumvalueof360canonlybereachedtheoretically,
sincethiswouldmeanthatthearcconsistsofafullcircle,which,becausethestartandend
pointshavetolieonthecircle,wouldhavetohaveaninfinitelylargediameter.Positive
valuesforcurvemeanthatthearcisdrawninamathematicallypositivesense(i.e.
counterclockwise).Ifcurveis0,thearcisastraightline("nocurvature"),whichisactually
awire.
Thecapparameteronlyhasameaningforactualarcs,andwillalwaysreturnCAP_ROUND
forastraightwire.
WhetherornotanUL_WIREisanarccanbedeterminedbycheckingthebooleanreturn
valueofthearcdatamember.Ifitreturns0,wehaveastraightwire,otherwiseanarc.If
arcreturnsanonzerovalueitmaybefurtherdereferencedtoaccesstheUL_ARCspecific
parametersstartandendangle,radiusandcenterpoint.Notethatyoumayonlyneedthese
additionalparametersifyouaregoingtodrawthearcorprocessitinotherwayswherethe
actualshapeisimportant.

Example
board(B) {
B.wires(W) {
printf("Wire: (%d %d) (%d %d)\n",

Page60of136
EAGLEUserLanguage Version5.7

W.x1, W.y1, W.x2, W.y2);

}
}

Definitions
ThedataitemstobeusedinaUserLanguageProgrammustbedefinedbeforetheycanbe
used.
Therearethreekindsofdefinitions:
ConstantDefinitions
VariableDefinitions
FunctionDefinitions
Thescopeofaconstantorvariabledefinitiongoesfromthelineinwhichithasbeen
definedtotheendofthecurrentblock,ortotheendoftheUserLanguageProgram,ifthe
definitionappearedoutsideanyblock.
Thescopeofafunctiondefinitiongoesfromtheclosingbrace(})ofthefunctionbodyto
theendoftheUserLanguageProgram.

Constant Definitions
Constantsaredefinedusingthekeywordenum,asin
enum { a, b, c };

whichwoulddefinethethreeconstantsa,bandc,givingthemthevalues0,1and2,
respectively.
Constantsmayalsobeinitializedtospecificvalues,like
enum { a, b = 5, c };

whereawouldbe0,bwouldbe5andcwouldbe6.

Variable Definitions
Thegeneralsyntaxofavariabledefinitionis
[numeric] type identifier [= initializer][, ...];

wheretypeisoneofthedataorobjecttypes,identifieristhenameofthevariable,
andinitializerisaoptionalinitialvalue.
Multiplevariabledefinitionsofthesametypeareseparatedbycommas(,).
Ifidentifierisfollowedbyapairofbrackets([]),thisdefinesanarrayofvariablesof
thegiventype.Thesizeofanarrayisautomaticallyadjustedatruntime.
Theoptionalkeywordnumericcanbeusedwithstringarraystohavethemsorted
alphanumericallybythesort()function.

Page61of136
EAGLEUserLanguage Version5.7

Bydefault(ifnoinitializerispresent),datavariablesaresetto0(or"",incaseofa
string),andobjectvariablesare"invalid".

Examples
int i; definesanintvariablenamedi
definesastringvariablenamedsandinitializesitto
string s = "Hello";
"Hello"
definesthreerealvariablesnameda,bandc,initializingbto
real a, b = 1.0, c;
thevalue1.0
int n[] = { 1, 2, definesanarrayofint,initializingthefirstthreeelementsto
3 }; 1,2and3
numeric string
definesastringarraythatcanbesortedalphanumerically
names[];
UL_WIRE w; definesaUL_WIREobjectnamedw
Themembersofarrayelementsofobjecttypescan'tbeaccesseddirectly:
UL_SIGNAL signals[];
...
UL_SIGNAL s = signals[0];
printf("%s", s.name);

Function Definitions
YoucanwriteyourownUserLanguagefunctionsandcallthemjustliketheBuiltin
Functions.
Thegeneralsyntaxofafunctiondefinitionis
type identifier(parameters)
{
statements
}

wheretypeisoneofthedataorobjecttypes,identifieristhenameofthefunction,
parametersisalistofcommaseparatedparameterdefinitions,andstatementsisa
sequenceofstatements.
Functionsthatdonotreturnavaluehavethetypevoid.
Afunctionmustbedefinedbeforeitcanbecalled,andfunctioncallscannotberecursive
(afunctioncannotcallitself).
Thestatementsinthefunctionbodymaymodifythevaluesoftheparameters,butthiswill
nothaveanyeffectontheargumentsofthefunctioncall.
Executionofafunctioncanbeterminatedbythereturnstatement.Withoutanyreturn
statementthefunctionbodyisexecuteduntilit'sclosingbrace(}).
Acalltotheexit()functionwillterminatetheentireUserLanguageProgram.

Page62of136
EAGLEUserLanguage Version5.7

The special function main()

IfyourUserLanguageProgramcontainsafunctioncalledmain(),thatfunctionwillbe
explicitlycalledasthemainfunction,andit'sreturnvaluewillbethereturnvalueofthe
program.
CommandlineargumentsareavailabletotheprogramthroughtheglobalBuiltinVariables
argcandargv.

Example
int CountDots(string s)
{
int dots = 0;
for (int i = 0; s[i]; ++i)
if (s[i] == '.')
++dots;
return dots;
}
string dotted = "This.has.dots...";
output("test") {
printf("Number of dots: %d\n",
CountDots(dotted));
}

Operators
ThefollowingtablelistsalloftheUserLanguageoperators,inorderoftheirprecedence
(Unaryhavingthehighestprecedence,Commathelowest):
Unary ! ~ + - ++ --
Multiplicative * / %
Additive + -
Shift << >>
Relational < <= > >=
Equality == !=
BitwiseAND &
BitwiseXOR ^
BitwiseOR |
LogicalAND &&
LogicalOR ||
Conditional ?:
Assignment = *= /= %= += -= &= ^= |= <<= >>=
Comma ,
Associativityislefttorightforalloperators,exceptforUnary,ConditionalandAssignment,
whicharerighttoleftassociative.
Thenormaloperatorprecedencecanbealteredbytheuseofparentheses.

Page63of136
EAGLEUserLanguage Version5.7

Bitwise Operators
Bitwiseoperatorsworkonlywithdatatypescharandint.
Unary
~ Bitwise(1's)complement
Binary
<< Shiftleft
>> Shiftright
& BitwiseAND
^ BitwiseXOR
| BitwiseOR
Assignment
&= AssignbitwiseAND
^= AssignbitwiseXOR
|= AssignbitwiseOR
<<= Assignleftshift
>>= Assignrightshift

Logical Operators
Logicaloperatorsworkwithexpressionsofanydatatype.
Unary
! LogicalNOT
Binary
&& LogicalAND
|| LogicalOR
Usingastringexpressionwithalogicaloperatorcheckswhetherthestringisempty.
UsinganObjectTypewithalogicaloperatorcheckswhetherthatobjectcontainsvaliddata.

Comparison Operators
Comparisonoperatorsworkwithexpressionsofanydatatype,exceptObjectTypes.
< Lessthan
<= Lessthanorequalto
> Greaterthan
Greaterthanorequal
>=
to
== Equalto
!= Notequalto

Evaluation Operators
Evaluationoperatorsareusedtoevaluateexpressionsbasedonacondition,ortogroupa
sequenceofexpressionsandhavethemevaluatedasoneexpression.
?: Conditional

Page64of136
EAGLEUserLanguage Version5.7

, Comma
TheConditionaloperatorisusedtomakeadecisionwithinanexpression,asin
int a;
// ...code that calculates 'a'
string s = a ? "True" : "False";

whichisbasicallythesameas
int a;
string s;
// ...code that calculates 'a'
if (a)
s = "True";
else
s = "False";

buttheadvantageoftheconditionaloperatoristhatitcanbeusedinanexpression.
TheCommaoperatorisusedtoevaluateasequenceofexpressionsfromlefttoright,using
thetypeandvalueoftherightoperandastheresult.
Notethatargumentsinafunctioncallaswellasmultiplevariabledeclarationsalsouse
commasasdelimiters,butinthatcasethisisnotacommaoperator!

Arithmetic Operators
Arithmeticoperatorsworkwithdatatypeschar,intandreal(exceptfor++,--,%and
%=).
Unary
+ Unaryplus
- Unaryminus
++ Preorpostincrement
-- Preorpostdecrement
Binary
* Multiply
/ Divide
% Remainder(modulus)
+ Binaryplus
- Binaryminus
Assignment
= Simpleassignment
*= Assignproduct
/= Assignquotient
%= Assignremainder(modulus)
+= Assignsum
-= Assigndifference
SeealsoStringOperators

Page65of136
EAGLEUserLanguage Version5.7

String Operators
Stringoperatorsworkwithdatatypeschar,intandstring.Theleftoperandmust
alwaysbeoftypestring.
Binary
+ Concatenation
Assignment
= Simpleassignment
+= Appendtostring
The+operatorconcatenatestwostrings,oraddsacharactertotheendofastringand
returnstheresultingstring.
The+=operatorappendsastringoracharactertotheendofagivenstring.
SeealsoArithmeticOperators

Expressions
Anexpressioncanbeoneofthefollowing:
ArithmeticExpression
AssignmentExpression
StringExpression
CommaExpression
ConditionalExpression
FunctionCall
Expressionscanbegroupedusingparentheses,andmayberecursive,meaningthatan
expressioncanconsistofsubexpressions.

Arithmetic Expression
Anarithmeticexpressionisanycombinationofnumericoperandsandanarithmetic
operatororabitwiseoperator.

Examples
a + b
c++
m << 1

Assignment Expression
Anassignmentexpressionconsistsofavariableontheleftsideofanassignmentoperator,
andanexpressionontherightside.

Examples
a = x + 42
b += c

Page66of136
EAGLEUserLanguage Version5.7

s = "Hello"

String Expression
Astringexpressionisanycombinationofstringandcharoperandsandastringoperator.

Examples
s + ".brd"
t + 'x'

Comma Expression
Acommaexpressionisasequenceofexpressions,delimitedbythecommaoperator
Commaexpressionsareevaluatedlefttoright,andtheresultofacommaexpressionisthe
typeandvalueoftherightmostexpression.

Example
i++, j++, k++

Conditional Expression
Aconditionalexpressionusestheconditionaloperatortomakeadecisionwithinan
expression.

Example
int a;
// ...code that calculates 'a'
string s = a ? "True" : "False";

Function Call
Afunctioncalltransferstheprogramflowtoauserdefinedfunctionorabuiltinfunction.
Theformalparametersdefinedinthefunctiondefinitionarereplacedwiththevaluesofthe
expressionsusedastheactualargumentsofthefunctioncall.

Example
int p = strchr(s, 'b');

Statements
Astatementcanbeoneofthefollowing:
CompoundStatement
ControlStatement

Page67of136
EAGLEUserLanguage Version5.7

ExpressionStatement
BuiltinStatement
ConstantDefinition
VariableDefinition
StatementsspecifytheflowofcontrolasaUserLanguageProgramexecutes.Inabsenceof
specificcontrolstatements,statementsareexecutedsequentiallyintheorderofappearance
intheULPfile.

Compound Statement
Acompoundstatement(alsoknownasblock)isalist(possiblyempty)ofstatements
enclosedinmatchingbraces({}).Syntactically,ablockcanbeconsideredtobeasingle
statement,butitalsocontrolsthescopingofidentifiers.Anidentifierdeclaredwithina
blockhasascopestartingatthepointofdeclarationandendingattheclosingbrace.
Compoundstatementscanbenestedtoanydepth.

Expression Statement
Anexpressionstatementisanyexpressionfollowedbyasemicolon.
Anexpressionstatementisexecutedbyevaluatingtheexpression.Allsideeffectsofthis
evaluationarecompletedbeforethenextstatementisexecuted.Mostexpression
statementsareassignmentsorfunctioncalls.
Aspecialcaseistheemptystatement,consistingofonlyasemicolon.Anemptystatement
doesnothing,butitmaybeusefulinsituationswheretheULPsyntaxexpectsastatement
butyourprogramdoesnotneedone.

Control Statements
Controlstatementsareusedtocontroltheprogramflow.
Iterationstatementsare
do...while
for
while

Selectionstatementsare
if...else
switch

Jumpstatementsare
break
continue
return

Page68of136
EAGLEUserLanguage Version5.7

break
Thebreakstatementhasthegeneralsyntax
break;

andimmediatelyterminatesthenearestenclosingdo...while,for,switchorwhile
statement.Thisalsoappliestoloopmembersofobjecttypes.
Sinceallofthesestatementscanbeintermixedandnestedtoanydepth,takecaretoensure
thatyourbreakexitsfromthecorrectstatement.

continue
Thecontinuestatementhasthegeneralsyntax
continue;

andimmediatelytransferscontroltothetestconditionofthenearestenclosingdo...while,
while,orforstatement,ortotheincrementexpressionofthenearestenclosingfor
statement.
Sinceallofthesestatementscanbeintermixedandnestedtoanydepth,takecaretoensure
thatyourcontinueaffectsthecorrectstatement.

do...while
Thedo...whilestatementhasthegeneralsyntax
do statement while (condition);

andexecutesthestatementuntiltheconditionexpressionbecomeszero.
Theconditionistestedafterthefirstexecutionofstatement,whichmeansthatthe
statementisalwaysexecutedatleastonetime.
Ifthereisnobreakorreturninsidethestatement,thestatementmustaffectthe
valueofthecondition,orconditionitselfmustchangeduringevaluationinorderto
avoidanendlessloop.

Example
string s = "Trust no one!";
int i = -1;
do {
++i;
} while (s[i]);

for
Theforstatementhasthegeneralsyntax
for ([init]; [test]; [inc]) statement

Page69of136
EAGLEUserLanguage Version5.7

andperformsthefollowingsteps:
1. Ifaninitializingexpressioninitispresent,itisexecuted.
2. Ifatestexpressionispresent,itisexecuted.Iftheresultisnonzero(orifthereis
notestexpressionatall),thestatementisexecuted.
3. Ifanincexpressionispresent,itisexecuted.
4. Finallycontrolreturnstostep2.
Ifthereisnobreakorreturninsidethestatement,theincexpression(orthe
statement)mustaffectthevalueofthetestexpression,ortestitselfmustchange
duringevaluationinordertoavoidanendlessloop.
Theinitializingexpressioninitnormallyinitializesoneormoreloopcounters.Itmayalso
defineanewvariableasaloopcounter.Thescopeofsuchavariableisvaliduntiltheend
oftheactiveblock.

Example
string s = "Trust no one!";
int sum = 0;
for (int i = 0; s[i]; ++i)
sum += s[i]; // sums up the characters in s

if...else
Theif...elsestatementhasthegeneralsyntax
if (expression)
t_statement
[else
f_statement]

Theconditionalexpressionisevaluated,andifitsvalueisnonzerothet_statementis
executed.Otherwisethef_statementisexecutedincasethereisanelseclause.
Anelseclauseisalwaysmatchedtothelastencounteredifwithoutanelse.Ifthisis
notwhatyouwant,youneedtousebracestogroupthestatements,asin
if (a == 1) {
if (b == 1)
printf("a == 1 and b == 1\n");
}
else
printf("a != 1\n");

return
Afunctionwithareturntypeotherthanvoidmustcontainatleastonereturnstatement
withthesyntax
return expression;

whereexpressionmustevaluatetoatypethatiscompatiblewiththefunction'sreturn

Page70of136
EAGLEUserLanguage Version5.7

type.Thevalueofexpressionisthevaluereturnedbythefunction.
Ifthefunctionisoftypevoid,areturnstatementwithoutanexpressioncanbeused
toreturnfromthefunctioncall.

switch
Theswitchstatementhasthegeneralsyntax
switch (sw_exp) {
case case_exp: case_statement
...
[default: def_statement]
}

andallowsforthetransferofcontroltooneofseveralcaselabeledstatements,depending
onthevalueofsw_exp(whichmustbeofintegraltype).
Anycase_statementcanbelabeledbyoneormorecaselabels.Thecase_expofeach
caselabelmustevaluatetoaconstantintegerwhichisuniquewithinit'senclosing
switchstatement.
Therecanalsobeatmostonedefaultlabel.
Afterevaluatingsw_exp,thecase_exparecheckedforamatch.Ifamatchisfound,
controlpassestothecase_statementwiththematchingcaselabel.
Ifnomatchisfoundandthereisadefaultlabel,controlpassestodef_statement.
Otherwisenoneofthestatementsintheswitchisexecuted.
Programexecutionisnotaffectedwhencaseanddefaultlabelsareencountered.
Controlsimplypassesthroughthelabelstothefollowingstatement.
Tostopexecutionattheendofagroupofstatementsforaparticularcase,usethebreak
statement.

Example
string s = "Hello World";
int vowels = 0, others = 0;
for (int i = 0; s[i]; ++i)
switch (toupper(s[i])) {
case 'A':
case 'E':
case 'I':
case 'O':
case 'U': ++vowels;
break;
default: ++others;
}
printf("There are %d vowels in '%s'\n", vowels, s);

Page71of136
EAGLEUserLanguage Version5.7

while
Thewhilestatementhasthegeneralsyntax
while (condition) statement

andexecutesthestatementaslongastheconditionexpressionisnotzero.
Theconditionistestedbeforethefirstpossibleexecutionofstatement,whichmeans
thatthestatementmayneverbeexecutedifconditionisinitiallyzero.
Ifthereisnobreakorreturninsidethestatement,thestatementmustaffectthe
valueofthecondition,orconditionitselfmustchangeduringevaluationinorderto
avoidanendlessloop.

Example
string s = "Trust no one!";
int i = 0;
while (s[i])
++i;

Builtins
BuiltinsareConstants,Variables,FunctionsandStatementsthatprovideadditional
informationandallowfordatamanipulations.
BuiltinConstants
BuiltinVariables
BuiltinFunctions
BuiltinStatements

Builtin Constants
Builtinconstantsareusedtoprovideinformationaboutobjectparameters,suchas
maximumrecommendednamelength,flagsetc.
ManyoftheobjecttypeshavetheirownConstantssectionwhichliststhebuiltinconstants
forthatparticularobject(seee.g.UL_PIN).
Thefollowingbuiltinconstantsaredefinedinadditiontotheoneslistedforthevarious
objecttypes:
EAGLE_VERSION EAGLEprogramversionnumber(int)
EAGLE_RELEASE EAGLEprogramreleasenumber(int)
EAGLE_SIGNATUR astringcontainingEAGLEprogramname,versionandcopyright
E information
theminimumpositiverealnumbersuchthat1.0 +
REAL_EPSILON
REAL_EPSILON != 1.0
REAL_MAX thelargestpossiblerealvalue
REAL_MIN thesmallestpossible(positive!)realvalue

Page72of136
EAGLEUserLanguage Version5.7

thesmallestrepresentablenumberis-REAL_MAX
INT_MAX thelargestpossibleintvalue
INT_MIN thesmallestpossibleintvalue
PI thevalueof"pi"(3.14...,real)
usage astringcontainingthetextfromthe#usagedirective
Thesebuiltinconstantscontainthedirectorypathsdefinedinthedirectoriesdialog,with
anyofthespecialvariables($HOMEand$EAGLEDIR)replacedbytheiractualvalues.Since
eachpathcanconsistofseveraldirectories,theseconstantsarestringarrayswithan
individualdirectoryineachmember.Thefirstemptymembermarkstheendofthepath:
path_lbr[] Libraries
path_dru[] DesignRules
UserLanguage
path_ulp[]
Programs
path_scr[] Scripts
path_cam[] CAMJobs
path_epf[] Projects
Whenusingtheseconstantstobuildafullfilename,youneedtouseadirectoryseparator,
asin
string s = path_lbr[0] + '/' + "mylib.lbr";

ThelibrariesthatarecurrentlyinusethroughtheUSEcommand:
used_libraries[]

Builtin Variables
Builtinvariablesareusedtoprovideinformationatruntime.
int argc numberofargumentsgiventotheRUNcommand
argumentsgiventotheRUNcommand(argv[0]isthefullULPfile
string argv[]
name)

Builtin Functions
Builtinfunctionsareusedtoperformspecifictasks,likeprintingformattedstrings,sorting
dataarraysorthelike.
YoumayalsowriteyourownfunctionsandusethemtostructureyourUserLanguage
Program.
Thebuiltinfunctionsaregroupedintothefollowingcategories:
CharacterFunctions
FileHandlingFunctions
MathematicalFunctions
MiscellaneousFunctions
PrintingFunctions
StringFunctions
TimeFunctions

Page73of136
EAGLEUserLanguage Version5.7

ObjectFunctions
Alphabeticalreferenceofallbuiltinfunctions:
abs()
acos()
asin()
atan()
ceil()
clrgroup()
cos()
exit()
exp()
filedir()
fileerror()
fileext()
fileglob()
filename()
fileread()
filesetext()
filesize()
filetime()
floor()
frac()
ingroup()
isalnum()
isalpha()
iscntrl()
isdigit()
isgraph()
islower()
isprint()
ispunct()
isspace()
isupper()
isxdigit()
language()
log()
log10()
lookup()
max()
min()
palette()
pow()
printf()
round()
setgroup()

Page74of136
EAGLEUserLanguage Version5.7

sin()
sort()
sprintf()
sqrt()
status()
strchr()
strjoin()
strlen()
strlwr()
strrchr()
strrstr()
strsplit()
strstr()
strsub()
strtod()
strtol()
strupr()
strxstr()
system()
t2day()
t2dayofweek()
t2hour()
t2minute()
t2month()
t2second()
t2string()
t2year()
tan()
time()
tolower()
toupper()
trunc()
u2inch()
u2mic()
u2mil()
u2mm()

Character Functions
Characterfunctionsareusedtomanipulatesinglecharacters.
Thefollowingcharacterfunctionsareavailable:
isalnum()
isalpha()
iscntrl()
isdigit()
isgraph()

Page75of136
EAGLEUserLanguage Version5.7

islower()
isprint()
ispunct()
isspace()
isupper()
isxdigit()
tolower()
toupper()

is...()
Function
Checkwhetheracharacterfallsintoagivencategory.
Syntax
int isalnum(char c);
int isalpha(char c);
int iscntrl(char c);
int isdigit(char c);
int isgraph(char c);
int islower(char c);
int isprint(char c);
int ispunct(char c);
int isspace(char c);
int isupper(char c);
int isxdigit(char c);
Returns
Theis...functionsreturnnonzeroifthegivencharacterfallsintothecategory,zero
otherwise.

Character categories
isalnum letters(AtoZoratoz)ordigits(0to9)
isalpha letters(AtoZoratoz)
iscntrl deletecharactersorordinarycontrolcharacters(0x7For0x00to0x1F)
isdigit digits(0to9)
isgraph printingcharacters(exceptspace)
islower lowercaseletters(atoz)
isprint printingcharacters(0x20to0x7E)
ispunct punctuationcharacters(iscntrlorisspace)
space,tab,carriagereturn,newline,verticaltab,orformfeed(0x09to
isspace
0x0D,0x20)
isupper uppercaseletters(AtoZ)
isxdigit hexdigits(0to9,AtoF,atof)

Example
char c = 'A';

Page76of136
EAGLEUserLanguage Version5.7

if (isxdigit(c))
printf("%c is hex\n", c);
else
printf("%c is not hex\n", c);

to...()
Function
Convertacharactertoupperorlowercase.
Syntax
char tolower(char c);
char toupper(char c);
Returns
Thetolowerfunctionreturnstheconvertedcharacterifcisuppercase.Allother
charactersarereturnedunchanged.
Thetoupperfunctionreturnstheconvertedcharacterifcislowercase.Allother
charactersarereturnedunchanged.

Seealsostrupr,strlwr

File Handling Functions

Filenamehandlingfunctionsareusedtoworkwithfilenames,sizesandtimestamps.
Thefollowingfilehandlingfunctionsareavailable:
fileerror()
fileglob()
filedir()
fileext()
filename()
fileread()
filesetext()
filesize()
filetime()
Seeoutput()forinformationabouthowtowriteintoafile.

fileerror()
Function
ReturnsthestatusofI/Ooperations.
Syntax
int fileerror();
Returns
Thefileerrorfunctionreturns0ifeverythingisok.

Seealsooutput,printf,fileread

Page77of136
EAGLEUserLanguage Version5.7

fileerrorchecksthestatusofanyI/Ooperationsthathavebeenperformedsincethe
lastcalltothisfunctionandreturns0ifeverythingwasok.IfanyoftheI/Ooperationshas
causedanerror,avalueotherthan0willbereturned.
YoushouldcallfileerrorbeforeanyI/Ooperationstoresetanypreviouserrorstate,
andcallitagainaftertheI/Ooperationstoseeiftheyweresuccessful.
Whenfileerrorreturnsavalueotherthan0(thusindicatinganerror)apropererror
messagehasalreadybeengiventotheuser.

Example
fileerror();
output("file.txt", "wt") {
printf("Test\n");
}
if (fileerror())
exit(1);

fileglob()
Function
Performadirectorysearch.
Syntax
int fileglob(string &array[], string pattern);
Returns
Thefileglobfunctionreturnsthenumberofentriescopiedintoarray.

SeealsodlgFileOpen(),dlgFileSave()
fileglobperformsadirectorysearchusingpattern.
patternmaycontain'*'and'?'aswildcardcharacters.Ifpatternendswitha'/',
thecontentsofthegivendirectorywillbereturned.
Namesintheresultingarraythatendwitha'/'aredirectorynames.
Thearrayissortedalphabetically,withthedirectoriescomingfirst.
Thespecialentries'.'and'..'(forthecurrentandparentdirectories)arenever
returnedinthearray.
Ifpatterndoesn'tmatch,orifyoudon'thavepermissiontosearchthegivendirectory,the
resultingarraywillbeempty.

Note for Windows users

Thedirectorydelimiterinthearrayisalwaysaforwardslash.Thismakessure
UserLanguageProgramswillworkplatformindependently.Inthepatternthe
backslash('\')isalsotreatedasadirectorydelimiter.

SortingfilenamesunderWindowsisdonecaseinsensitively.

Page78of136
EAGLEUserLanguage Version5.7

Example
string a[];
int n = fileglob(a, "*.brd");

Filename Functions
Function
Splitafilenameintoitsseparateparts.
Syntax
string filedir(string file);
string fileext(string file);
string filename(string file);
string filesetext(string file, string newext);
Returns
filedir returnsthedirectoryoffile(includingthedriveletterunderWindows).
fileext returnstheextensionoffile.
filename returnsthefilenameoffile(includingtheextension).
filesetextreturnsfilewiththeextensionsettonewext.

SeealsoFiledataFunctions

Example
if (board) board(B) {
output(filesetext(B.name, ".out")) {
...
}
}

Filedata Functions
Function
Getsthetimestampandsizeofafile.
Syntax
int filesize(string filename);
int filetime(string filename);
Returns
filesizereturnsthesize(inbyte)ofthegivenfile.
filetimereturnsthetimestampofthegivenfileinaformattobeusedwiththe
timefunctions.

Seealsotime,FilenameFunctions

Example
board(B)
printf("Board: %s\nSize: %d\nTime: %s\n",
B.name, filesize(B.name),

Page79of136
EAGLEUserLanguage Version5.7

t2string(filetime(B.name)));

File Input Functions

Fileinputfunctionsareusedtoreaddatafromfiles.
Thefollowingfileinputisavailable:
fileread()
Seeoutput()forinformationabouthowtowriteintoafile.

fileread()
Function
Readsdatafromafile.
Syntax
int fileread(dest, string file);
Returns
filereadreturnsthenumberofobjectsreadfromthefile.
Theactualmeaningofthereturnvaluedependsonthetypeofdest.

Seealsolookup,strsplit,fileerror
Ifdestisacharacterarray,thefilewillbereadasrawbinarydataandthereturnvalue
reflectsthenumberofbytesreadintothecharacterarray(whichisequaltothefilesize).
Ifdestisastringarray,thefilewillbereadasatextfile(onelineperarraymember)and
thereturnvaluewillbethenumberoflinesreadintothestringarray.Newlinecharacters
willbestripped.
Ifdestisastring,theentirefilewillbereadintothatstringandthereturnvaluewillbe
thelengthofthatstring(whichisnotnecessarilyequaltothefilesize,iftheoperating
systemstorestextfileswith"cr/lf"insteadofa"newline"character).

Example
char b[];
int nBytes = fileread(b, "data.bin");
string lines[];
int nLines = fileread(lines, "data.txt");
string text;
int nChars = fileread(text, "data.txt");

Mathematical Functions
Mathematicalfunctionsareusedtoperformmathematicaloperations.
Thefollowingmathematicalfunctionsareavailable:
abs()
acos()

Page80of136
EAGLEUserLanguage Version5.7

asin()
atan()
ceil()
cos()
exp()
floor()
frac()
log()
log10()
max()
min()
pow()
round()
sin()
sqrt()
trunc()
tan()

Error Messages
Iftheargumentsofamathematicalfunctioncallleadtoanerror,theerrormessagewill
showtheactualvaluesofthearguments.Thusthestatements
real x = -1.0;
real r = sqrt(2 * x);

willleadtotheerrormessage
Invalid argument in call to 'sqrt(-2)'

Absolute, Maximum and Minimum Functions

Function
Absolute,maximumandminimumfunctions.
Syntax
type abs(type x);
type max(type x, type y);
type min(type x, type y);
Returns
absreturnstheabsolutevalueofx.
maxreturnsthemaximumofxandy.
minreturnstheminimumofxandy.

Thereturntypeofthesefunctionsisthesameasthe(larger)typeofthearguments.
typemustbeoneofchar,intorreal.

Page81of136
EAGLEUserLanguage Version5.7

Example
real x = 2.567, y = 3.14;
printf("The maximum is %f\n", max(x, y));

Rounding Functions
Function
Roundingfunctions.
Syntax
real ceil(real x);
real floor(real x);
real frac(real x);
real round(real x);
real trunc(real x);
Returns
ceil returnsthesmallestintegernotlessthanx.
floorreturnsthelargestintegernotgreaterthanx.
frac returnsthefractionalpartofx.
roundreturnsxroundedtothenearestinteger.
truncreturnstheintegerpartofx.

Example
real x = 2.567;
printf("The rounded value of %f is %f\n", x, round(x));

Trigonometric Functions
Function
Trigonometricfunctions.
Syntax
real acos(real x);
real asin(real x);
real atan(real x);
real cos(real x);
real sin(real x);
real tan(real x);
Returns
acosreturnsthearccosineofx.
asinreturnsthearcsineofx.
atanreturnsthearctangentofx.
cos returnsthecosineofx.
sin returnsthesineofx.
tan returnsthetangentofx.

Page82of136
EAGLEUserLanguage Version5.7

Constants
thevalueof"pi"
PI
(3.14...)

Example
real x = PI / 2;
printf("The sine of %f is %f\n", x, sin(x));

Exponential Functions
Function
ExponentialFunctions.
Syntax
real exp(real x);
real log(real x);
real log10(real x);
real pow(real x, real y);
real sqrt(real x);
Returns
exp returnstheexponentialetothepowerofx.
log returnsthenaturallogarithmofx.
log10returnsthebase10logarithmofx.
pow returnsthevalueofxtothepowerofy.
sqrt returnsthesquarerootofx.

Note
The"nth"rootcanbecalculatedusingthepowfunctionwithanegativeexponent.

Example
real x = 2.1;
printf("The square root of %f is %f\n", x, sqrt(x));

Miscellaneous Functions
Miscellaneousfunctionsareusedtoperformvarioustasks.
Thefollowingmiscellaneousfunctionsareavailable:
exit()
language()
lookup()
palette()
sort()
status()
system()

Page83of136
EAGLEUserLanguage Version5.7

UnitConversions

exit()
Function
ExitsfromaUserLanguageProgram.
Syntax
void exit(int result);
void exit(string command);

SeealsoRUN
TheexitfunctionterminatesexecutionofaUserLanguageProgram.
Ifanintegerresultisgivenitwillbeusedasthereturnvalueoftheprogram.
Ifastringcommandisgiven,thatcommandwillbeexecutedasifitwereenteredintothe
commandlineimmediatelyaftertheRUNcommand.Inthatcasethereturnvalueofthe
ULPissettoEXIT_SUCCESS.

Constants
returnvalueforsuccessfulprogramexecution(value
EXIT_SUCCESS
0)
EXIT_FAILURE returnvalueforfailedprogramexecution(value-1)

language()
Function
Returnsthelanguagecodeofthesysteminuse.
Syntax
string language();
Returns
languagereturnsastringconsistingoftwolowercasecharactersthatidentifiesthe
languageusedonthecurrentsystem.Ifnosuchlanguagesettingcanbedetermined,
anemptystringwillbereturned.

ThelanguagefunctioncanbeusedtomakeaULPusedifferentmessagestring,
dependingonwhichlanguagethecurrentsystemisusing.
IntheexamplebelowallthestringsusedintheULParelistedinthestringarrayI18N[],
preceededbyastringcontainingthevariouslanguagecodessupportedbythisULP.Note
thevtabcharactersusedtoseparatetheindividualpartsofeachstring(theyareimportant
forthelookupfunction)andtheuseofthecommastoseparatethestrings.Theactual
workisdoneinthefunctiontr(),whichreturnsthetranslatedversionofthegivenstring.
Iftheoriginalstringcan'tbefoundintheI18Narray,orthereisnotranslationforthe
currentlanguage,theoriginalstringwillbeuseduntranslated.
ThefirstlanguagedefinedintheI18Narraymustbetheoneinwhichthestringsused
throughouttheULParewritten,andshouldgenerallybeEnglishinordertomakethe
programaccessibletothelargestnumberofusers.

Page84of136
EAGLEUserLanguage Version5.7

Example
string I18N[] = {
"en\v"
"de\v"
"it\v"
,
"I18N Demo\v"
"Beispiel fr Internationalisierung\v"
"Esempio per internazionalizzazione\v"
,
"Hello world!\v"
"Hallo Welt!\v"
"Ciao mondo!\v"
,
"+Ok\v"
"+Ok\v"
"+Approvazione\v"
,
"-Cancel\v"
"-Abbrechen\v"
"-Annullamento\v"
};
int Language = strstr(I18N[0], language()) / 3;
string tr(string s)
{
string t = lookup(I18N, s, Language, '\v');
return t ? t : s;
}
dlgDialog(tr("I18N Demo")) {
dlgHBoxLayout dlgSpacing(350);
dlgLabel(tr("Hello world!"));
dlgHBoxLayout {
dlgPushButton(tr("+Ok")) dlgAccept();
dlgPushButton(tr("-Cancel")) dlgReject();
}
};

lookup()
Function
Looksupdatainastringarray.
Syntax
string lookup(string array[], string key, int field_index[,
char separator]);
string lookup(string array[], string key, string field_name[,
char separator]);
Returns
lookupreturnsthevalueofthefieldidentifiedbyfield_indexorfield_name.
Ifthefielddoesn'texist,ornostringmatchingkeyisfound,anemptystringis
returned.

Seealsofileread,strsplit

Page85of136
EAGLEUserLanguage Version5.7

Anarraythatcanbeusedwithlookup()consistsofstringsoftext,eachstring
representingonedatarecord.
Eachdatarecordcontainsanarbitrarynumberoffields,whichareseparatedbythe
characterseparator(defaultis'\t',thetabulator).Thefirstfieldinarecordisusedas
thekeyandisnumbered0.
Allrecordsmusthaveuniquekeyfieldsandnoneofthekeyfieldsmaybeempty
otherwiseitisundefinedwhichrecordwillbefound.
Ifthefirststringinthearraycontainsa"Header"record(i.e.arecordwhereeachfield
describesitscontents),usinglookupwithafield_namestringautomaticallydetermines
theindexofthatfield.Thisallowsusingthelookupfunctionwithoutexactlyknowing
whichfieldindexcontainsthedesireddata.
Itisuptotheusertomakesurethatthefirstrecordactuallycontainsheaderinformation.
Ifthekeyparameterinthecalltolookup()isanemptystring,thefirststringofthe
arraywillbeused.Thisallowsaprogramtodeterminewhetherthereisaheaderrecord
withtherequiredfieldnames.
Ifafieldcontainstheseparatorcharacter,thatfieldmustbeenclosedindoublequotes
(asin"abc;def",assumingthesemicolon(';')isusedasseparator).Thesameapplies
ifthefieldcontainsdoublequotes("),inwhichcasethedoublequotesinsidethefieldhave
tobedoubled(asin"abc;""def"";ghi",whichwouldbeabc;"def";ghi).
Itisbesttousethedefault"tab"separator,whichdoesn'thavetheseproblems(no
fieldcancontainatabulator).
Here'sanexampledatafile(';'hasbeenusedasseparatorforbetterreadability):
Name;Manufacturer;Code;Price
7400;Intel;I-01-234-97;$0.10
68HC12;Motorola;M68HC1201234;$3.50

Example
string OrderCodes[];
if (fileread(OrderCodes, "ordercodes") > 0) {
if (lookup(OrderCodes, "", "Code", ';')) {
schematic(SCH) {
SCH.parts(P) {
string OrderCode;
// both following statements do exactly the same:
OrderCode = lookup(OrderCodes, P.device.name, "Code", ';');
OrderCode = lookup(OrderCodes, P.device.name, 2, ';');
}
}
}
else
dlgMessageBox("Missing 'Code' field in file 'ordercodes');
}

Page86of136
EAGLEUserLanguage Version5.7

palette()
Function
Returnscolorpaletteinformation.
Syntax
int palette(int index[, int type]);
Returns
ThepalettefunctionreturnsanintegerARGBvalueintheform0xaarrggbb,orthe
typeofthecurrentlyusedpalette(dependingonthevalueofindex).

ThepalettefunctionreturnstheARGBvalueofthecolorwiththegivenindex(which
maybeintherange0..PALETTE_ENTRIES1).Iftypeisnotgiven(oris-1)thepalette
assignedtothecurrenteditorwindowwillbeused.Otherwisetypespecifieswhichcolor
palettetouse(PALETTE_BLACK,PALETTE_WHITEorPALETTE_COLORED).
Thespecialvalue-1forindexmakesthefunctionreturnthetypeofthepalettethatis
currentlyinusebytheeditorwindow.
Ifeitherindexortypeisoutofrange,anerrormessagewillbegivenandtheULPwillbe
terminated.

Constants
PALETTE_TYPES thenumberofpalettetypes(3)
PALETTE_BLACK theblackbackgroundpalette(0)
PALETTE_WHITE thewhitebackgroundpalette(1)
PALETTE_COLORED thecoloredbackgroundpalette(2)
thenumberofcolorsperpalette
PALETTE_ENTRIES
(64)

sort()
Function
Sortsanarrayorasetofarrays.
Syntax
void sort(int number, array1[, array2,...]);

Thesortfunctioneitherdirectlysortsagivenarray1,oritsortsasetofarrays(starting
witharray2),inwhichcasearray1issupposedtobeanarrayofint,whichwillbeused
asapointerarray.
Inanycase,thenumberargumentdefinesthenumberofitemsinthearray(s).

Sorting a single array

Ifthesortfunctioniscalledwithonesinglearray,thatarraywillbesorteddirectly,asin
thefollowingexample:
string A[];
int n = 0;

Page87of136
EAGLEUserLanguage Version5.7

A[n++] = "World";
A[n++] = "Hello";
A[n++] = "The truth is out there...";
sort(n, A);
for (int i = 0; i < n; ++i)
printf(A[i]);

Sorting a set of arrays

Ifthesortfunctioniscalledwithmorethanonearray,thefirstarraymustbeanarrayof
int,whilealloftheotherarraysmaybeofanyarraytypeandholdthedatatobesorted.
Thefollowingexampleillustrateshowthefirstarraywillbeusedasapointer:
numeric string Nets[], Parts[], Instances[], Pins[];
int n = 0;
int index[];
schematic(S) {
S.nets(N) N.pinrefs(P) {
Nets[n] = N.name;
Parts[n] = P.part.name;
Instances[n] = P.instance.name;
Pins[n] = P.pin.name;
++n;
}
sort(n, index, Nets, Parts, Instances, Pins);
for (int i = 0; i < n; ++i)
printf("%-8s %-8s %-8s %-8s\n",
Nets[index[i]], Parts[index[i]],
Instances[index[i]], Pins[index[i]]);
}

Theideabehindthisisthatonenetcanhaveseveralpinsconnectedtoit,andinanetlist
youmightwanttohavethenetnamessorted,andwithinonenetyoualsowantthepart
namessortedandsoon.
Notetheuseofthekeywordnumericinthestringarrays.Thiscausesthestringstobe
sortedinawaythattakesintoaccountanumericpartattheendofthestrings,whichleads
toIC1,IC2,...IC9,IC10insteadofthealphabeticalorderIC1,IC10,IC2,...IC9.
Whensortingasetofarrays,thefirst(index)arraymustbeoftypeintandneednotbe
initialized.Anycontentstheindexarraymighthavebeforecallingthesortfunctionwill
beoverwrittenbytheresultingindexvalues.

status()
Function
Displaysastatusmessageinthestatusbar.
Syntax
void status(string message);

SeealsodlgMessageBox()
Thestatusfunctiondisplaysthegivenmessageinthestatusbaroftheeditorwindowin

Page88of136
EAGLEUserLanguage Version5.7

whichtheULPisrunning.

system()
Function
Executesanexternalprogram.
Syntax
int system(string command);
Returns
Thesystemfunctionreturnstheexitstatusofthecommand.Thisistypically0if
everythingwasok,andnonzeroincaseofanerror.

Thesystemfunctionexecutestheexternalprogramgivenbythecommandstring,and
waitsuntiltheprogramends.
Asasecurityprecaution,youwillbepromptedwiththecommandstringbeforethe
commandisexecuted,inordertomakesurethereisno"evil"ULPthatexecutesunwanted
externalcommands.Ifthisdialogiscanceled,thesystem()callwillreturn-1.Ifthe
dialogisconfirmed,anyfuturesystem()callsinthecurrentEAGLEsessionwithexactly
thesamecommandstringwillbeexecutedwithoutanyfurtherconfirmationdialog.

Input/Output redirection
Iftheexternalprogramshallreaditsstandardinputfrom(orwriteitsstandardoutputto)a
particularfile,input/outputneedstoberedirected.
OnLinuxandMacOSXthisisdonebysimplyaddinga'<'or'>'tothe
commandline,followedbythedesiredfilename,asin

system("program < infile > outfile");

whichrunsprogramandmakesitreadfrominfileandwritetooutfile.
OnWindowsyouhavetoexplicitlyrunacommandprocessortodothis,asin

system("cmd.exe /c program < infile > outfile");

(onDOSbasedWindowssystemsusecommand.cominsteadofcmd.exe).

Background execution
Thesystemfunctionwaitsuntilthegivenprogramhasended.Thisisusefulforprograms
thatonlyrunforafewseconds,orcompletelytakeovertheuser'sattention.
Ifanexternalprogramrunsforalongertime,andyouwantthesystemcalltoreturn
immediately,withoutwaitingfortheprogramtoend,youcansimplyaddan'&'to
thecommandstringunderLinuxandMacOSX,asin

system("program &");

Page89of136
EAGLEUserLanguage Version5.7

UnderWindowsyouneedtoexplicitlyrunacommandprocessortodothis,asin

system("cmd.exe /c start program");

(onDOSbasedWindowssystemsusecommand.cominsteadofcmd.exe).

Example
int result = system("simulate -f filename");

Thiswouldcallasimulationprogram,givingitafilewhichtheULPhasjustcreated.Note
thatsimulatehereisjustanexample,itisnotpartoftheEAGLEpackage!

Unit Conversions
Function
Convertsinternalunits.
Syntax
real u2inch(int n);
real u2mic(int n);
real u2mil(int n);
real u2mm(int n);
Returns
u2inchreturnsthevalueofnininch.
u2mic returnsthevalueofninmicrons(1/1000mm).
u2mil returnsthevalueofninmil(1/1000inch).
u2mm returnsthevalueofninmillimeters.

SeealsoUL_GRID
EAGLEstoresallcoordinateandsizevaluesasintvalueswitharesolutionof1/10000mm
(0.1).Theaboveunitconversionfunctionscanbeusedtoconverttheseinternalunitsto
thedesiredmeasurementunits.

Example
board(B) {
B.elements(E) {
printf("%s at (%f, %f)\n", E.name,
u2mm(E.x), u2mm(E.y));
}
}

Printing Functions
Printingfunctionsareusedtoprintformattedstrings.
Thefollowingprintingfunctionsareavailable:
printf()

Page90of136
EAGLEUserLanguage Version5.7

sprintf()

printf()
Function
Writesformattedoutputtoafile.
Syntax
int printf(string format[, argument, ...]);
Returns
Theprintffunctionreturnsthenumberofcharacterswrittentothefilethathas
beenopenedbythemostrecentoutputstatement.

Incaseofanerror,printfreturns-1.

Seealsosprintf,output,fileerror

Format string
Theformatstringcontrolshowtheargumentswillbeconverted,formattedandprinted.
Theremustbeexactlyasmanyargumentsasnecessaryfortheformat.Thenumberand
typeofargumentswillbecheckedagainsttheformat,andanymismatchwillleadtoan
errormessage.
Theformatstringcontainstwotypesofobjectsplaincharactersandformatspecifiers:
Plaincharactersaresimplycopiedverbatimtotheoutput
Formatspecifiersfetchargumentsfromtheargumentlistandapplyformattingto
them

Format specifiers
Aformatspecifierhasthefollowingform:
% [flags] [width] [.prec] type
Eachformatspecificationbeginswiththepercentcharacter(%).Afterthe%comesthe
following,inthisorder:
anoptionalsequenceofflagcharacters,[flags]
anoptionalwidthspecifier,[width]
anoptionalprecisionspecifier,[.prec]
theconversiontypecharacter,type

Conversion type characters

d signeddecimalint
o unsignedoctalint
u unsigneddecimalint
x unsignedhexadecimalint(witha,b,...)
X unsignedhexadecimalint(withA,B,...)

Page91of136
EAGLEUserLanguage Version5.7

f signedrealvalueoftheform[-]dddd.dddd
e signedrealvalueoftheform[-]d.dddde[]ddd
E samease,butwithEforexponent
signedrealvalueineithereorfform,basedongivenvalueand
g
precision
G sameasg,butwithEforexponentifeformatused
c singlecharacter
s characterstring
% the%characterisprinted

Flag characters
Thefollowingflagcharacterscanappearinanyorderandcombination.
"-
theformatteditemisleftjustifiedwithinthefield;normally,itemsarerightjustified
"
"+ asigned,positiveitemwillalwaysstartwithapluscharacter(+);normally,only
" negativeitemsbeginwithasign
" asigned,positiveitemwillalwaysstartwithaspacecharacter;ifboth"+"and" "
" arespecified,"+"overrides" "

Width specifiers
Thewidthspecifiersetstheminimumfieldwidthforanoutputvalue.
Widthisspecifiedeitherdirectly,throughadecimaldigitstring,orindirectly,throughan
asterisk(*).Ifyouuseanasteriskforthewidthspecifier,thenextargumentinthecall
(whichmustbeanint)specifiestheminimumoutputfieldwidth.
Innocasedoesanonexistentorsmallfieldwidthcausetruncationofafield.Iftheresultof
aconversioniswiderthanthefieldwidth,thefieldissimplyexpandedtocontainthe
conversionresult.
Atleastncharactersareprinted.Iftheoutputvaluehaslessthanncharacters,the
n
outputispaddedwithblanks(rightpaddedif"-"flaggiven,leftpaddedotherwise).
Atleastncharactersareprinted.Iftheoutputvaluehaslessthanncharacters,itis
0n
filledontheleftwithzeroes.
Theargumentlistsuppliesthewidthspecifier,whichmustprecedetheactual
*
argumentbeingformatted.

Precision specifiers
Aprecisionspecifieralwaysbeginswithaperiod(.)toseparateitfromanypreceding
widthspecifier.Then,likewidth,precisionisspecifiedeitherdirectlythroughadecimal
digitstring,orindirectly,throughanasterisk(*).Ifyouuseanasteriskfortheprecision
specifier,thenextargumentinthecall(whichmustbeanint)specifiestheprecision.
none Precisionsettodefault.
.0 Forinttypes,precisionissettodefault;forrealtypes,nodecimalpointisprinted.
.n ncharactersorndecimalplacesareprinted.Iftheoutputvaluehasmorethann
characterstheoutputmightbetruncatedorrounded(dependingonthetype

Page92of136
EAGLEUserLanguage Version5.7

character).
Theargumentlistsuppliestheprecisionspecifier,whichmustprecedetheactual
*
argumentbeingformatted.

Default precision values

douxX 1
eEf 6
gG allsignificantdigits
c noeffect
s printentirestring

How precision specification (.n) affects conversion

.nspecifiesthatatleastncharactersareprinted.Iftheinputargumenthasless
douxX thanndigits,theoutputvalueisleftpaddedwithzeros.Iftheinputargumenthas
morethanndigits,theoutputvalueisnottruncated.
.nspecifiesthatncharactersareprintedafterthedecimalpoint,andthelastdigit
eEf
printedisrounded.
gG .nspecifiesthatatmostnsignificantdigitsareprinted.
c .nhasnoeffectontheoutput.
s .nspecifiesthatnomorethanncharactersareprinted.

Binary zero characters

Unlikesprintf,theprintffunctioncanprintbinaryzerocharacters(0x00).
char c = 0x00;
printf("%c", c);

Example
int i = 42;
real r = 3.14;
char c = 'A';
string s = "Hello";
printf("Integer: %8d\n", i);
printf("Hex: %8X\n", i);
printf("Real: %8f\n", r);
printf("Char: %-8c\n", c);
printf("String: %-8s\n", s);

sprintf()
Function
Writesformattedoutputintoastring.
Syntax
int sprintf(string result, string format[, argument, ...]);
Returns
Thesprintffunctionreturnsthenumberofcharacterswrittenintotheresult

Page93of136
EAGLEUserLanguage Version5.7

string.

Incaseofanerror,sprintfreturns-1.

Seealsoprintf

Format string
Seeprintf.

Binary zero characters

Notethatsprintfcannotreturnstringswithembeddedbinaryzerocharacters(0x00).If
theresultingstringcontainsabinaryzerocharacter,anycharactersfollowingthatzero
characterwillbedropped.Useprintfifyouneedtooutputbinarydata.

Example
string result;
int number = 42;
sprintf(result, "The number is %d", number);

String Functions
Stringfunctionsareusedtomanipulatecharacterstrings.
Thefollowingstringfunctionsareavailable:
strchr()
strjoin()
strlen()
strlwr()
strrchr()
strrstr()
strsplit()
strstr()
strsub()
strtod()
strtol()
strupr()
strxstr()

strchr()
Function
Scansastringforthefirstoccurrenceofagivencharacter.
Syntax
int strchr(string s, char c[, int index]);
Returns

Page94of136
EAGLEUserLanguage Version5.7

Thestrchrfunctionreturnstheintegeroffsetofthecharacterinthestring,or-1if
thecharacterdoesnotoccurinthestring.

Seealsostrrchr,strstr
Ifindexisgiven,thesearchstartsatthatposition.Negativevaluesarecountedfromthe
endofthestring.

Example
string s = "This is a string";
char c = 'a';
int pos = strchr(s, c);
if (pos >= 0)
printf("The character %c is at position %d\n", c, pos);
else
printf("The character was not found\n");

strjoin()
Function
Joinsastringarraytoformasinglestring.
Syntax
string strjoin(string array[], char separator);
Returns
Thestrjoinfunctionreturnsthecombinedentriesofarray.

Seealsostrsplit,lookup,fileread
strjoinjoinsallentriesinarray,delimitedbythegivenseparatorandreturnsthe
resultingstring.
Ifseparatoristhenewlinecharacter("\n")theresultingstringwillbeterminatedwith
anewlinecharacter.ThisisdonetohaveatextfilethatconsistsofNlines(eachofwhichis
terminatedwithanewline)andisreadinwiththefileread()functionandsplitintoan
arrayofNstringstobejoinedtotheoriginalstringasreadfromthefile.

Example
string a[] = { "Field 1", "Field 2", "Field 3" };
string s = strjoin(a, ':');

strlen()
Function
Calculatesthelengthofastring.
Syntax
int strlen(string s);
Returns
Thestrlenfunctionreturnsthenumberofcharactersinthestring.

Page95of136
EAGLEUserLanguage Version5.7

Example
string s = "This is a string";
int l = strlen(s);
printf("The string is %d characters long\n", l);

strlwr()
Function
Convertsuppercaselettersinastringtolowercase.
Syntax
string strlwr(string s);
Returns
Thestrlwrfunctionreturnsthemodifiedstring.Theoriginalstring(givenas
parameter)isnotchanged.

Seealsostrupr,tolower

Example
string s = "This Is A String";
string r = strlwr(s);
printf("Prior to strlwr: %s - after strlwr: %s\n", s, r);

strrchr()
Function
Scansastringforthelastoccurrenceofagivencharacter.
Syntax
int strrchr(string s, char c[, int index]);
Returns
Thestrrchrfunctionreturnstheintegeroffsetofthecharacterinthestring,or-1if
thecharacterdoesnotoccurinthestring.

Seealsostrchr,strrstr
Ifindexisgiven,thesearchstartsatthatposition.Negativevaluesarecountedfromthe
endofthestring.

Example
string s = "This is a string";
char c = 'a';
int pos = strrchr(s, c);
if (pos >= 0)
printf("The character %c is at position %d\n", c, pos);
else
printf("The character was not found\n");

Page96of136
EAGLEUserLanguage Version5.7

strrstr()
Function
Scansastringforthelastoccurrenceofagivensubstring.
Syntax
int strrstr(string s1, string s2[, int index]);
Returns
Thestrrstrfunctionreturnstheintegeroffsetofthefirstcharacterofs2ins1,or
-1ifthesubstringdoesnotoccurinthestring.

Seealsostrstr,strrchr
Ifindexisgiven,thesearchstartsatthatposition.Negativevaluesarecountedfromthe
endofthestring.

Example
string s1 = "This is a string", s2 = "is a";
int pos = strrstr(s1, s2);
if (pos >= 0)
printf("The substring starts at %d\n", pos);
else
printf("The substring was not found\n");

strsplit()
Function
Splitsastringintoseparatefields.
Syntax
int strsplit(string &array[], string s, char separator);
Returns
Thestrsplitfunctionreturnsthenumberofentriescopiedintoarray.

Seealsostrjoin,lookup,fileread
strsplitsplitsthestringsatthegivenseparatorandstorestheresultingfieldsinthe
array.
Ifseparatoristhenewlinecharacter("\n")thelastfieldwillbesilentlydroppedifitis
empty.ThisisdonetohaveatextfilethatconsistsofNlines(eachofwhichisterminated
withanewline)andisreadinwiththefileread()functiontobesplitintoanarrayofN
strings.Withanyotherseparatoranemptyfieldattheendofthestringwillcount,so
"a:b:c:"willresultin4fields,thelastofwhichisempty.

Example
string a[];
int n = strsplit(a, "Field 1:Field 2:Field 3", ':');

Page97of136
EAGLEUserLanguage Version5.7

strstr()
Function
Scansastringforthefirstoccurrenceofagivensubstring.
Syntax
int strstr(string s1, string s2[, int index]);
Returns
Thestrstrfunctionreturnstheintegeroffsetofthefirstcharacterofs2ins1,or-1
ifthesubstringdoesnotoccurinthestring.

Seealsostrrstr,strchr,strxstr
Ifindexisgiven,thesearchstartsatthatposition.Negativevaluesarecountedfromthe
endofthestring.

Example
string s1 = "This is a string", s2 = "is a";
int pos = strstr(s1, s2);
if (pos >= 0)
printf("The substring starts at %d\n", pos);
else
printf("The substring was not found\n");

strsub()
Function
Extractsasubstringfromastring.
Syntax
string strsub(string s, int start[, int length]);
Returns
Thestrsubfunctionreturnsthesubstringindicatedbythestartandlength
value.

Thevalueforlengthmustbepositive,otherwiseanemptystringwillbereturned.If
lengthisommitted,therestofthestring(beginningatstart)isreturned.

Ifstartpointstoapositionoutsidethestring,anemptystringisreturned.

Example
string s = "This is a string";
string t = strsub(s, 4, 7);
printf("The extracted substring is: %s\n", t);

strtod()
Function

Page98of136
EAGLEUserLanguage Version5.7

Convertsastringtoarealvalue.
Syntax
real strtod(string s);
Returns
Thestrtodfunctionreturnsthenumericalrepresentationofthegivenstringasa
realvalue.Conversionendsatthefirstcharacterthatdoesnotfitintotheformatof
arealconstant.Ifanerroroccursduringconversionofthestring0.0willbe
returned.

Seealsostrtol

Example
string s = "3.1415";
real r = strtod(s);
printf("The value is %f\n", r);

strtol()
Function
Convertsastringtoanintegervalue.
Syntax
int strtol(string s);
Returns
Thestrtolfunctionreturnsthenumericalrepresentationofthegivenstringasan
intvalue.Conversionendsatthefirstcharacterthatdoesnotfitintotheformatof
anintegerconstant.Ifanerroroccursduringconversionofthestring0willbe
returned.

Seealsostrtod

Example
string s = "1234";
int i = strtol(s);
printf("The value is %d\n", i);

strupr()
Function
Convertslowercaselettersinastringtouppercase.
Syntax
string strupr(string s);
Returns
Thestruprfunctionreturnsthemodifiedstring.Theoriginalstring(givenas
parameter)isnotchanged.

Page99of136
EAGLEUserLanguage Version5.7

Seealsostrlwr,toupper

Example
string s = "This Is A String";
string r = strupr(s);
printf("Prior to strupr: %s - after strupr: %s\n", s, r);

strxstr()
Function
Scansastringforthefirstoccurrenceofagivenregularexpression.
Syntax
int strxstr(string s1, string s2[, int index[, int &length]]);
Returns
Thestrxstrfunctionreturnstheintegeroffsetofthesubstringins1thatmatches
theregularexpressionins2,or-1iftheregularexpressiondoesnotmatchinthe
string.

Seealsostrstr,strchr,strrstr
Ifindexisgiven,thesearchstartsatthatposition.Negativevaluesarecountedfromthe
endofthestring.
Iflengthisgiven,theactuallengthofthematchingsubstringisreturnedinthatvariable.
Regularexpressionsallowyoutofindapatternwithinatextstring.Forinstance,theregular
expression"i.*a"wouldfindasequenceofcharactersthatstartswithan'i',followedbyany
character('.')anynumberoftimes('*'),andendswithan'a'.Itwouldmatchon"isa"as
wellas"isthisa"or"ia".
Detailsonregularexpressionscanbefound,forinstance,inthebookMasteringRegular
ExpressionsbyJeffreyE.F.Friedl.

Example
string s1 = "This is a string", s2 = "i.*a";
int len = 0;
int pos = strxstr(s1, s2, 0, len);
if (pos >= 0)
printf("The substring starts at %d and is %d charcaters long\n", pos, len);
else
printf("The substring was not found\n");

Time Functions
Timefunctionsareusedtogetandprocesstimeanddateinformation.
Thefollowingtimefunctionsareavailable:
t2day()
t2dayofweek()

Page100of136
EAGLEUserLanguage Version5.7

t2hour()
t2minute()
t2month()
t2second()
t2string()
t2year()
time()
timems()

time()
Function
Getsthecurrentsystemtime.
Syntax
int time(void);
Returns
Thetimefunctionreturnsthecurrentsystemtimeasthenumberofsecondselapsed
sinceasystemdependentreferencedate.

SeealsoTimeConversions,filetime,timems()

Example
int CurrentTime = time();

timems()
Function
GetsthenumberofmillisecondssincethestartoftheULP.
Syntax
int timems(void);
Returns
ThetimemsfunctionreturnsthenumberofmillisecondssincethestartoftheULP.

After86400000milliseconds(i.e.every24hours),thevaluestartsat0again.

Seealsotime

Example
int elapsed = timems();

Time Conversions
Function
Convertatimevaluetoday,month,yearetc.
Syntax

Page101of136
EAGLEUserLanguage Version5.7

int t2day(int t);

int t2dayofweek(int t);
int t2hour(int t);
int t2minute(int t);
int t2month(int t);
int t2second(int t);
int t2year(int t);

string t2string(int t);

Returns
t2day returnsthedayofthemonth(1..31)
t2dayofweekreturnsthedayoftheweek(0=sunday..6)
t2hour returnsthehour(0..23)
t2minute returnstheminute(0..59)
t2month returnsthemonth(0..11)
t2second returnsthesecond(0..59)
t2year returnstheyear(includingcentury!)
t2string returnsaformattedstringcontainingdateandtime

Seealsotime

Example
int t = time();
printf("It is now %02d:%02d:%02d\n",
t2hour(t), t2minute(t), t2second(t));

Object Functions
Objectfunctionsareusedtoaccesscommoninformationaboutobjects.
Thefollowingobjectfunctionsareavailable:
clrgroup()
ingroup()
setgroup()

clrgroup()
Function
Clearsthegroupflagsofanobject.
Syntax
void clrgroup(object);

Seealsoingroup(),setgroup(),GROUPcommand
Theclrgroup()functionclearsthegroupflagsofthegivenobject,sothatitisnolonger
partofthepreviouslydefinedgroup.

Page102of136
EAGLEUserLanguage Version5.7

Whenappliedtoanobjectthatcontainsotherobjects(likeaUL_BOARDorUL_NET)the
groupflagsofallcontainedobjectsareclearedrecursively.

Example
board(B) {
B.elements(E)
clrgroup(E);
}

ingroup()
Function
Checkswhetheranobjectisinthegroup.
Syntax
int ingroup(object);
Returns
Theingroupfunctionreturnsanonzerovalueifthegivenobjectisinthegroup.

Seealsoclrgroup(),setgroup(),GROUPcommand
Ifagrouphasbeendefinedintheeditor,theingroup()functioncanbeusedtocheck
whetheraparticularobjectispartofthegroup.
Objectswithasinglecoordinatethatareindividuallyselectableinthecurrentdrawing(like
UL_TEXT,UL_VIA,UL_CIRCLEetc.)returnanonzerovalueinacalltoingroup()ifthat
coordinateiswithinthedefinedgroup.
AUL_WIREreturns0,1,2or3,dependingonwhethernone,thefirst,thesecondorboth
ofitsendpointsareinthegroup.
AUL_RECTANGLEandUL_FRAMEreturnsanonzerovalueifoneormoreofitscorners
areinthegroup.Thevaluehasbit0setfortheupperrightcorner,bit1fortheupperleft,
bit2forthebottomleft,andbit3forthebottomrightcorner.
Objectsthathavenocoordinates(likeUL_NET,UL_SEGMENT,UL_SIGNALetc.)returna
nonzerovalueifoneormoreoftheobjectswithinthemareinthegroup.
UL_CONTACTREFandUL_PINREF,thoughnothavingcoordinatesoftheirown,returna
nonzerovalueifthereferencedUL_CONTACTorUL_PIN,respectively,iswithinthegroup.

Example
output("group.txt") {
board(B) {
B.elements(E) {
if (ingroup(E))
printf("Element %s is in the group\n", E.name);
}
}
}

Page103of136
EAGLEUserLanguage Version5.7

setgroup()
Function
Setsthegroupflagsofanobject.
Syntax
void setgroup(object[, int flags]);

Seealsoclrgroup(),ingroup(),GROUPcommand
Thesetgroup()functionsetsthegroupflagsofthegivenobject,sothatitbecomespart
ofthegroup.
Ifnoflagsaregiven,theobjectisaddedtothegroupasawhole(i.e.allofitsselection
points,incaseithasmorethanone).
Ifflagshasanonzerovalue,onlythegroupflagsofthegivenpointsoftheobjectareset.
ForaUL_WIREthismeansthat'1'setsthegroupflagofthefirstpoint,'2'thatofthe
secondpoint,and'3'setsboth.Anypreviouslysetgroupflagsremainunchangedbyacall
tosetgroup().
Whenappliedtoanobjectthatcontainsotherobjects(likeaUL_BOARDorUL_NET)the
groupflagsofallcontainedobjectsaresetrecursively.

Example
board(B) {
B.elements(E)
setgroup(E);
}

Builtin Statements
Builtinstatementsaregenerallyusedtoopenacertaincontextinwhichdatastructuresof
filescanbeaccessed.
Thegeneralsyntaxofabuiltinstatementis
name(parameters) statement

wherenameisthenameofthebuiltinstatement,parametersstandsforoneormore
parameters,andstatementisthecodethatwillbeexecutedinsidethecontextopenedby
thebuiltinstatement.
Notethatstatementcanbeacompoundstatement,asin
board(B) {
B.elements(E) printf("Element: %s\n", E.name);
B.Signals(S) printf("Signal: %s\n", S.name);
}

Thefollowingbuiltinstatementsareavailable:
board()

Page104of136
EAGLEUserLanguage Version5.7

deviceset()
library()
output()
package()
schematic()
sheet()
symbol()

board()
Function
Opensaboardcontext.
Syntax
board(identifier) statement

Seealsoschematic,library
Theboardstatementopensaboardcontextifthecurrenteditorwindowcontainsaboard
drawing.AvariableoftypeUL_BOARDiscreatedandisgiventhenameindicatedby
identifier.
Oncetheboardcontextissuccessfullyopenedandaboardvariablehasbeencreated,the
statementisexecuted.Withinthescopeofthestatementtheboardvariablecanbe
accessedtoretrievefurtherdatafromtheboard.
Ifthecurrenteditorwindowdoesnotcontainaboarddrawing,anerrormessageisgiven
andtheULPisterminated.

Check if there is a board

Byusingtheboardstatementwithoutanargumentyoucancheckifthecurrenteditor
windowcontainsaboarddrawing.Inthatcase,boardbehaveslikeanintegerconstant,
returning1ifthereisaboarddrawinginthecurrenteditorwindow,and0otherwise.

Accessing board from a schematic

Ifthecurrenteditorwindowcontainsaschematicdrawing,youcanstillaccessthat
schematic'sboardbyprecedingtheboardstatementwiththeprefixproject,asin
project.board(B) { ... }

Thiswillopenaboardcontextregardlesswhetherthecurrenteditorwindowcontainsa
boardoraschematicdrawing.However,theremustbeaneditorwindowcontainingthat
boardsomewhereonthedesktop!

Example
if (board)
board(B) {
B.elements(E)
printf("Element: %s\n", E.name);

Page105of136
EAGLEUserLanguage Version5.7

deviceset()
Function
Opensadevicesetcontext.
Syntax
deviceset(identifier) statement

Seealsopackage,symbol,library
Thedevicesetstatementopensadevicesetcontextifthecurrenteditorwindowcontains
adevicedrawing.AvariableoftypeUL_DEVICESETiscreatedandisgiventhename
indicatedbyidentifier.
Oncethedevicesetcontextissuccessfullyopenedandadevicesetvariablehasbeen
created,thestatementisexecuted.Withinthescopeofthestatementthedeviceset
variablecanbeaccessedtoretrievefurtherdatafromthedeviceset.
Ifthecurrenteditorwindowdoesnotcontainadevicedrawing,anerrormessageisgiven
andtheULPisterminated.

Check if there is a device set

Byusingthedevicesetstatementwithoutanargumentyoucancheckifthecurrent
editorwindowcontainsadevicedrawing.Inthatcase,devicesetbehaveslikeaninteger
constant,returning1ifthereisadevicedrawinginthecurrenteditorwindow,and0
otherwise.

Example
if (deviceset)
deviceset(D) {
D.gates(G)
printf("Gate: %s\n", G.name);
}

library()
Function
Opensalibrarycontext.
Syntax
library(identifier) statement

Seealsoboard,schematic,deviceset,package,symbol
Thelibrarystatementopensalibrarycontextifthecurrenteditorwindowcontainsa
librarydrawing.AvariableoftypeUL_LIBRARYiscreatedandisgiventhenameindicated
byidentifier.

Page106of136
EAGLEUserLanguage Version5.7

Oncethelibrarycontextissuccessfullyopenedandalibraryvariablehasbeencreated,the
statementisexecuted.Withinthescopeofthestatementthelibraryvariablecanbe
accessedtoretrievefurtherdatafromthelibrary.
Ifthecurrenteditorwindowdoesnotcontainalibrarydrawing,anerrormessageisgiven
andtheULPisterminated.

Check if there is a library

Byusingthelibrarystatementwithoutanargumentyoucancheckifthecurrenteditor
windowcontainsalibrarydrawing.Inthatcase,librarybehaveslikeanintegerconstant,
returning1ifthereisalibrarydrawinginthecurrenteditorwindow,and0otherwise.

Example
if (library)
library(L) {
L.devices(D)
printf("Device: %s\n", D.name);
}

output()
Function
Opensanoutputfileforsubsequentprintf()calls.
Syntax
output(string filename[, string mode]) statement

Seealsoprintf,fileerror
Theoutputstatementopensafilewiththegivenfilenameandmodeforoutputthrough
subsequentprintf()calls.Ifthefilehasbeensuccessfullyopened,thestatementis
executed,andafterthatthefileisclosed.
Ifthefilecannotbeopened,anerrormessageisgivenandexecutionoftheULPis
terminated.
BydefaulttheoutputfileiswrittenintotheProjectdirectory.

File Modes
Themodeparameterdefineshowtheoutputfileistobeopened.Ifnomodeparameteris
given,thedefaultis"wt".
a appendtoanexistingfile,orcreateanewfileifitdoesnotexist
w createanewfile(overwritinganexistingfile)
t openfileintextmode
b openfileinbinarymode
deletethisfilewhenendingtheEAGLEsession(onlyworkstogetherwith
D
w)

Page107of136
EAGLEUserLanguage Version5.7

F forceusingthisfilename(normally*.brd,*.schand*.lbrarerejected)
Modecharactersmayappearinanyorderandcombination.However,onlythelastoneofa
andwortandb,respectively,issignificant.Forexampleamodeof"abtw"wouldopena
filefortextualwrite,whichwouldbethesameas"wt".

Nested Output statements

outputstatementscanbenested,aslongasthereareenoughfilehandlesavailable,and
providedthatnotwoactiveoutputstatementsaccessthesamefile.

Example
void PrintText(string s)
{
printf("This also goes into the file: %s\n", s);
}
output("file.txt", "wt") {
printf("Directly printed\n");
PrintText("via function call");
}

package()
Function
Opensapackagecontext.
Syntax
package(identifier) statement

Seealsolibrary,deviceset,symbol
Thepackagestatementopensapackagecontextifthecurrenteditorwindowcontainsa
packagedrawing.AvariableoftypeUL_PACKAGEiscreatedandisgiventhename
indicatedbyidentifier.
Oncethepackagecontextissuccessfullyopenedandapackagevariablehasbeencreated,
thestatementisexecuted.Withinthescopeofthestatementthepackagevariablecan
beaccessedtoretrievefurtherdatafromthepackage.
Ifthecurrenteditorwindowdoesnotcontainapackagedrawing,anerrormessageisgiven
andtheULPisterminated.

Check if there is a package

Byusingthepackagestatementwithoutanargumentyoucancheckifthecurrenteditor
windowcontainsapackagedrawing.Inthatcase,packagebehaveslikeaninteger
constant,returning1ifthereisapackagedrawinginthecurrenteditorwindow,and0
otherwise.

Example
if (package)

Page108of136
EAGLEUserLanguage Version5.7

package(P) {
P.contacts(C)
printf("Contact: %s\n", C.name);
}

schematic()
Function
Opensaschematiccontext.
Syntax
schematic(identifier) statement

Seealsoboard,library,sheet
Theschematicstatementopensaschematiccontextifthecurrenteditorwindowcontains
aschematicdrawing.AvariableoftypeUL_SCHEMATICiscreatedandisgiventhename
indicatedbyidentifier.
Oncetheschematiccontextissuccessfullyopenedandaschematicvariablehasbeen
created,thestatementisexecuted.Withinthescopeofthestatementtheschematic
variablecanbeaccessedtoretrievefurtherdatafromtheschematic.
Ifthecurrenteditorwindowdoesnotcontainaschematicdrawing,anerrormessageis
givenandtheULPisterminated.

Check if there is a schematic

Byusingtheschematicstatementwithoutanargumentyoucancheckifthecurrent
editorwindowcontainsaschematicdrawing.Inthatcase,schematicbehaveslikean
integerconstant,returning1ifthereisaschematicdrawinginthecurrenteditorwindow,
and0otherwise.

Accessing schematic from a board

Ifthecurrenteditorwindowcontainsaboarddrawing,youcanstillaccessthatboard's
schematicbyprecedingtheschematicstatementwiththeprefixproject,asin
project.schematic(S) { ... }

Thiswillopenaschematiccontextregardlesswhetherthecurrenteditorwindowcontainsa
schematicoraboarddrawing.However,theremustbeaneditorwindowcontainingthat
schematicsomewhereonthedesktop!

Access the current Sheet

Usethesheetstatementtodirectlyaccessthecurrentlyloadedsheet.

Example
if (schematic)
schematic(S) {

Page109of136
EAGLEUserLanguage Version5.7

S.parts(P)
printf("Part: %s\n", P.name);
}

sheet()
Function
Opensasheetcontext.
Syntax
sheet(identifier) statement

Seealsoschematic
Thesheetstatementopensasheetcontextifthecurrenteditorwindowcontainsasheet
drawing.AvariableoftypeUL_SHEETiscreatedandisgiventhenameindicatedby
identifier.
Oncethesheetcontextissuccessfullyopenedandasheetvariablehasbeencreated,the
statementisexecuted.Withinthescopeofthestatementthesheetvariablecanbe
accessedtoretrievefurtherdatafromthesheet.
Ifthecurrenteditorwindowdoesnotcontainasheetdrawing,anerrormessageisgiven
andtheULPisterminated.

Check if there is a sheet

Byusingthesheetstatementwithoutanargumentyoucancheckifthecurrenteditor
windowcontainsasheetdrawing.Inthatcase,sheetbehaveslikeanintegerconstant,
returning1ifthereisasheetdrawinginthecurrenteditorwindow,and0otherwise.

Example
if (sheet)
sheet(S) {
S.parts(P)
printf("Part: %s\n", P.name);
}

symbol()
Function
Opensasymbolcontext.
Syntax
symbol(identifier) statement

Seealsolibrary,deviceset,package
Thesymbolstatementopensasymbolcontextifthecurrenteditorwindowcontainsa
symboldrawing.AvariableoftypeUL_SYMBOLiscreatedandisgiventhenameindicated
byidentifier.

Page110of136
EAGLEUserLanguage Version5.7

Oncethesymbolcontextissuccessfullyopenedandasymbolvariablehasbeencreated,the
statementisexecuted.Withinthescopeofthestatementthesymbolvariablecanbe
accessedtoretrievefurtherdatafromthesymbol.
Ifthecurrenteditorwindowdoesnotcontainasymboldrawing,anerrormessageisgiven
andtheULPisterminated.

Check if there is a symbol

Byusingthesymbolstatementwithoutanargumentyoucancheckifthecurrenteditor
windowcontainsasymboldrawing.Inthatcase,symbolbehaveslikeanintegerconstant,
returning1ifthereisasymboldrawinginthecurrenteditorwindow,and0otherwise.

Example
if (symbol)
symbol(S) {
S.pins(P)
printf("Pin: %s\n", P.name);
}

Dialogs
UserLanguageDialogsallowyoutodefineyourownfrontendtoaUserLanguageProgram.
ThefollowingsectionsdescribeUserLanguageDialogsindetail:
PredefinedDialogs describesthereadytousestandarddialogs
DialogObjects definestheobjectsthatcanbeusedinadialog
explainshowtodefinethelocationofobjectswithina
LayoutInformation
dialog
DialogFunctions describesspecialfunctionsforusewithdialogs
ACompleteExample showsacompleteULPwithadataentrydialog

Predefined Dialogs
PredefinedDialogsimplementthetypicalstandarddialogsthatarefrequentlyusedfor
selectingfilenamesorissuingerrormessages.
Thefollowingpredefineddialogsareavailable:
dlgDirectory()
dlgFileOpen()
dlgFileSave()
dlgMessageBox()
SeeDialogObjectsforinformationonhowtodefineyourowncomplexuserdialogs.

dlgDirectory()
Function
Displaysadirectorydialog.

Page111of136
EAGLEUserLanguage Version5.7

Syntax
string dlgDirectory(string Title[, string Start])
Returns
ThedlgDirectoryfunctionreturnsthefullpathnameoftheselecteddirectory.
Iftheuserhascanceledthedialog,theresultwillbeanemptystring.

SeealsodlgFileOpen
ThedlgDirectoryfunctiondisplaysadirectorydialogfromwhichtheusercanselecta
directory.
Titlewillbeusedasthedialog'stitle.
IfStartisnotempty,itwillbeusedasthestartingpointforthedlgDirectory.

Example
string dirName;
dirName = dlgDirectory("Select a directory", "");

dlgFileOpen(), dlgFileSave()
Function
Displaysafiledialog.
Syntax
string dlgFileOpen(string Title[, string Start[, string
Filter]])
string dlgFileSave(string Title[, string Start[, string
Filter]])
Returns
ThedlgFileOpenanddlgFileSavefunctionsreturnthefullpathnameofthe
selectedfile.
Iftheuserhascanceledthedialog,theresultwillbeanemptystring.

SeealsodlgDirectory
ThedlgFileOpenanddlgFileSavefunctionsdisplayafiledialogfromwhichtheuser
canselectafile.
Titlewillbeusedasthedialog'stitle.
IfStartisnotempty,itwillbeusedasthestartingpointforthefiledialog.Otherwisethe
currentdirectorywillbeused.
OnlyfilesmatchingFilterwillbedisplayed.IfFilterisempty,allfileswillbe
displayed.
Filtercanbeeitherasimplewildcard(asin"*.brd"),alistofwildcards(asin
"*.bmp *.jpg")ormayevencontaindescriptivetext,asin
"Bitmap files (*.bmp)".Ifthe"Filetype"comboboxofthefiledialogshallcontain
severalentries,theyhavetobeseparatedbydoublesemicolons,asin

Page112of136
EAGLEUserLanguage Version5.7

"Bitmap files (*.bmp);;Other images (*.jpg *.png)".

Example
string fileName;
fileName = dlgFileOpen("Select a file", "", "*.brd");

dlgMessageBox()
Function
Displaysamessagebox.
Syntax
int dlgMessageBox(string Message[, button_list])
Returns
ThedlgMessageBoxfunctionreturnstheindexofthebuttontheuserhasselected.
Thefirstbuttoninbutton_listhasindex0.

Seealsostatus()
ThedlgMessageBoxfunctiondisplaysthegivenMessageinamodaldialogandwaits
untiltheuserselectsoneofthebuttonsdefinedinbutton_list.
IfMessagecontainsanyHTMLtags,thecharacters'<','>'and'&'mustbegivenas"&lt;",
"&gt;"and"&amp;",respectively,iftheyshallbedisplayedassuch.
button_listisanoptionallistofcommaseparatedstrings,whichdefinesthesetof
buttonsthatwillbedisplayedatthebottomofthemessagebox.
Amaximumofthreebuttonscanbedefined.Ifnobutton_listisgiven,itdefaultsto
"OK".
Thefirstbuttoninbutton_listwillbecomethedefaultbutton(whichwillbeselectedif
theuserhitsENTER),andthelastbuttoninthelistwillbecomethe"cancelbutton",which
isselectediftheuserhitsESCapeorclosesthemessagebox.Youcanmakeadifferent
buttonthedefaultbuttonbystartingitsnamewitha'+',andyoucanmakeadifferent
buttonthecancelbuttonbystartingitsnamewitha'-'.Tostartabuttontextwithan
actual'+'or'-'ithastobeescaped.
Ifabuttontextcontainsan'&',thecharacterfollowingtheampersandwillbecomea
hotkey,andwhentheuserhitsthecorrespondingkey,thatbuttonwillbeselected.Tohave
anactual'&'characterinthetextithastobeescaped.
ThemessageboxcanbegivenaniconbysettingthefirstcharacterofMessageto
';'foranInformation
'!'foraWarning
':'foranError
If,however,theMessageshallbeginwithoneofthesecharacters,ithastobeescaped.
OnMacOSXonlythecharacter':'willactuallyresultinshowinganicon.All
othersareignored.

Page113of136
EAGLEUserLanguage Version5.7

Example
if (dlgMessageBox("!Are you sure?", "&Yes", "&No") == 0) {
// let's do it!
}

Dialog Objects
AUserLanguageDialogisbuiltfromthefollowingDialogObjects:
dlgCell agridcellcontext
dlgCheckBox acheckbox
dlgComboBox acomboboxselectionfield
thebasiccontainerofany
dlgDialog
dialog
dlgGridLayout agridbasedlayoutcontext
dlgGroup agroupfield
dlgHBoxLayout ahorizontalboxlayoutcontext
dlgIntEdit anintegerentryfield
dlgLabel atextlabel
dlgListBox alistbox
dlgListView alistview
dlgPushButton apushbutton
dlgRadioButton aradiobutton
dlgRealEdit arealentryfield
dlgSpacing alayoutspacingobject
dlgSpinBox aspinboxselectionfield
dlgStretch alayoutstretchobject
dlgStringEdit astringentryfield
dlgTabPage atabpage
dlgTabWidget atabpagecontainer
dlgTextEdit atextentryfield
dlgTextView atextviewerfield
dlgVBoxLayout averticalboxlayoutcontext

dlgCell
Function
Definesacelllocationwithinagridlayoutcontext.
Syntax
dlgCell(int row, int column[, int row2, int column2])
statement

SeealsodlgGridLayout,dlgHBoxLayout,dlgVBoxLayout,LayoutInformation,AComplete
Example
ThedlgCellstatementdefinesthelocationofacellwithinagridlayoutcontext.
Therowandcolumnindexesstartat0,sotheupperleftcellhastheindex(0,0).

Page114of136
EAGLEUserLanguage Version5.7

Withtwoparametersthedialogobjectdefinedbystatementwillbeplacedinthesingle
celladdressesbyrowandcolumn.Withfourparametersthedialogobjectwillspanover
allcellsfromrow/columntorow2/column2.
BydefaultadlgCellcontainsadlgHBoxLayout,soifthecellcontainsmorethanone
dialogobject,theywillbeplacednexttoeachotherhorizontally.

Example
string Text;
dlgGridLayout {
dlgCell(0, 0) dlgLabel("Cell 0,0");
dlgCell(1, 2, 4, 7) dlgTextEdit(Text);
}

dlgCheckBox
Function
Definesacheckbox.
Syntax
dlgCheckBox(string Text, int &Checked) [ statement ]

SeealsodlgRadioButton,dlgGroup,LayoutInformation,ACompleteExample
ThedlgCheckBoxstatementdefinesacheckboxwiththegivenText.
IfTextcontainsan'&',thecharacterfollowingtheampersandwillbecomeahotkey,and
whentheuserhitsAlt+hotkey,thecheckboxwillbetoggled.Tohaveanactual'&'
characterinthetextithastobeescaped.
dlgCheckBoxismainlyusedwithinadlgGroup,butcanalsobeusedotherwise.
AllcheckboxeswithinthesamedialogmusthavedifferentCheckedvariables!
IftheuserchecksadlgCheckBox,theassociatedCheckedvariableissetto1,otherwise
itissetto0.TheinitialvalueofCheckeddefineswhetheracheckboxisinitiallychecked.
IfCheckedisnotequalto0,thecheckboxisinitiallychecked.
TheoptionalstatementisexecutedeverytimethedlgCheckBoxistoggled.

Example
int mirror = 0;
int rotate = 1;
int flip = 0;
dlgGroup("Orientation") {
dlgCheckBox("&Mirror", mirror);
dlgCheckBox("&Rotate", rotate);
dlgCheckBox("&Flip", flip);
}

Page115of136
EAGLEUserLanguage Version5.7

dlgComboBox
Function
Definesacomboboxselectionfield.
Syntax
dlgComboBox(string array[], int &Selected) [ statement ]

SeealsodlgListBox,dlgLabel,LayoutInformation,ACompleteExample
ThedlgComboBoxstatementdefinesacomboboxselectionfieldwiththecontentsofthe
givenarray.
Selectedreflectstheindexoftheselectedcomboboxentry.Thefirstentryhasindex0.
Eachelementofarraydefinesthecontentsofoneentryinthecombobox.Noneofthe
stringsinarraymaybeempty(ifthereisanemptystring,allstringsafterandincluding
thatonewillbedropped).
TheoptionalstatementisexecutedwhenevertheselectioninthedlgComboBox
changes.
Beforethestatementisexecuted,allvariablesthathavebeenusedwithdialogobjects
areupdatedtotheircurrentvalues,andanychangesmadetothesevariablesinsidethe
statementwillbereflectedinthedialogwhenthestatementreturns.
IftheinitialvalueofSelectedisoutsidetherangeofthearrayindexes,itissetto0.

Example
string Colors[] = { "red", "green", "blue", "yellow" };
int Selected = 2; // initially selects "blue"
dlgComboBox(Colors, Selected) dlgMessageBox("You have selected " +
Colors[Selected]);

dlgDialog
Function
ExecutesaUserLanguageDialog.
Syntax
int dlgDialog(string Title) block ;
Returns
ThedlgDialogfunctionreturnsanintegervaluethatcanbegivenauserdefined
meaningthroughacalltothedlgAccept()function.
Ifthedialogissimplyclosed,thereturnvaluewillbe0.

SeealsodlgGridLayout,dlgHBoxLayout,dlgVBoxLayout,dlgAccept,dlgReset,dlgReject,A
CompleteExample
ThedlgDialogfunctionexecutesthedialogdefinedbyblock.Thisistheonlydialog
objectthatactuallyisaUserLanguagebuiltinfunction.Thereforeitcanbeusedanywhere
whereafunctioncallisallowed.

Page116of136
EAGLEUserLanguage Version5.7

Theblocknormallycontainsonlyotherdialogobjects,butitisalsopossibletouseother
UserLanguagestatements,forexampletoconditionallyaddobjectstothedialog(seethe
secondexamplebelow).
BydefaultadlgDialogcontainsadlgVBoxLayout,soasimpledialogdoesn'thaveto
worryaboutthelayout.
AdlgDialogshouldatsomepointcontainacalltothedlgAccept()functioninorder
toallowtheusertoclosethedialogandacceptitscontents.
Ifallyouneedisasimplemessageboxorfiledialogyoumightwanttouseoneofthe
PredefinedDialogsinstead.

Examples
int Result = dlgDialog("Hello") {
dlgLabel("Hello world");
dlgPushButton("+OK") dlgAccept();
};
int haveButton = 1;
dlgDialog("Test") {
dlgLabel("Start");
if (haveButton)
dlgPushButton("Here") dlgAccept();
};

dlgGridLayout
Function
Opensagridlayoutcontext.
Syntax
dlgGridLayout statement

SeealsodlgCell,dlgHBoxLayout,dlgVBoxLayout,LayoutInformation,AComplete
Example
ThedlgGridLayoutstatementopensagridlayoutcontext.
TheonlydialogobjectthatcanbeuseddirectlyinstatementisdlgCell,whichdefinesthe
locationofaparticulardialogobjectwithinthegridlayout.
Therowandcolumnindexesstartat0,sotheupperleftcellhastheindex(0,0).
Thenumberofrowsandcolumnsisautomaticallyextendedaccordingtothelocationof
dialogobjectsthataredefinedwithinthegridlayoutcontext,soyoudon'thavetoexplicitly
definethenumberofrowsandcolumns.

Example
dlgGridLayout {
dlgCell(0, 0) dlgLabel("Row 0/Col 0");
dlgCell(1, 0) dlgLabel("Row 1/Col 0");
dlgCell(0, 1) dlgLabel("Row 0/Col 1");
dlgCell(1, 1) dlgLabel("Row 1/Col 1");

Page117of136
EAGLEUserLanguage Version5.7

dlgGroup
Function
Definesagroupfield.
Syntax
dlgGroup(string Title) statement

SeealsodlgCheckBox,dlgRadioButton,LayoutInformation,ACompleteExample
ThedlgGroupstatementdefinesagroupwiththegivenTitle.
BydefaultadlgGroupcontainsadlgVBoxLayout,soasimplegroupdoesn'thavetoworry
aboutthelayout.
dlgGroupismainlyusedtocontainasetofradiobuttonsorcheckboxes,butmayaswell
containanyotherobjectsinitsstatement.
RadiobuttonswithinadlgGrouparenumberedstartingwith0.

Example
int align = 1;
dlgGroup("Alignment") {
dlgRadioButton("&Top", align);
dlgRadioButton("&Center", align);
dlgRadioButton("&Bottom", align);
}

dlgHBoxLayout
Function
Opensahorizontalboxlayoutcontext.
Syntax
dlgHBoxLayout statement

SeealsodlgGridLayout,dlgVBoxLayout,LayoutInformation,ACompleteExample
ThedlgHBoxLayoutstatementopensahorizontalboxlayoutcontextforthegiven
statement.

Example
dlgHBoxLayout {
dlgLabel("Box 1");
dlgLabel("Box 2");
dlgLabel("Box 3");
}

Page118of136
EAGLEUserLanguage Version5.7

dlgIntEdit
Function
Definesanintegerentryfield.
Syntax
dlgIntEdit(int &Value, int Min, int Max)

SeealsodlgRealEdit,dlgStringEdit,dlgLabel,LayoutInformation,ACompleteExample
ThedlgIntEditstatementdefinesanintegerentryfieldwiththegivenValue.
IfValueisinitiallyoutsidetherangedefinedbyMinandMaxitwillbelimitedtothese
values.

Example
int Value = 42;
dlgHBoxLayout {
dlgLabel("Enter a &Number between 0 and 99");
dlgIntEdit(Value, 0, 99);
}

dlgLabel
Function
Definesatextlabel.
Syntax
dlgLabel(string Text [, int Update])

SeealsoLayoutInformation,ACompleteExample,dlgRedisplay()
ThedlgLabelstatementdefinesalabelwiththegivenText.
Textcanbeeitherastringliteral,asin"Hello",orastringvariable.
IfTextcontainsanyHTMLtags,thecharacters'<','>'and'&'mustbegivenas"&lt;",
"&gt;"and"&amp;",respectively,iftheyshallbedisplayedassuch.
IftheUpdateparameterisnot0andTextisastringvariable,itscontentscanbe
modifiedinthestatementof,e.g.,adlgPushButton,andthelabelwillbeautomatically
updated.This,ofcourse,isonlyusefulifTextisadedicatedstringvariable(not,e.g.,the
loopvariableofaforstatement).
IfTextcontainsan'&',andtheobjectfollowingthelabelcanhavethekeyboardfocus,
thecharacterfollowingtheampersandwillbecomeahotkey,andwhentheuserhits
Alt+hotkey,thefocuswillgototheobjectthatwasdefinedimmediatelyfollowingthe
dlgLabel.Tohaveanactual'&'characterinthetextithastobeescaped.

Example
string OS = "Windows";
dlgHBoxLayout {

Page119of136
EAGLEUserLanguage Version5.7

dlgLabel(OS, 1);
dlgPushButton("&Change OS") { OS = "Linux"; }
}

dlgListBox
Function
Definesalistboxselectionfield.
Syntax
dlgListBox(string array[], int &Selected) [ statement ]

SeealsodlgComboBox,dlgListView,dlgLabel,LayoutInformation,ACompleteExample
ThedlgListBoxstatementdefinesalistboxselectionfieldwiththecontentsofthegiven
array.
Selectedreflectstheindexoftheselectedlistboxentry.Thefirstentryhasindex0.
Eachelementofarraydefinesthecontentsofonelineinthelistbox.Noneofthestrings
inarraymaybeempty(ifthereisanemptystring,allstringsafterandincludingthatone
willbedropped).
Theoptionalstatementisexecutedwhenevertheuserdoubleclicksonanentryofthe
dlgListBox.
Beforethestatementisexecuted,allvariablesthathavebeenusedwithdialogobjects
areupdatedtotheircurrentvalues,andanychangesmadetothesevariablesinsidethe
statementwillbereflectedinthedialogwhenthestatementreturns.
IftheinitialvalueofSelectedisoutsidetherangeofthearrayindexes,noentrywillbe
selected.

Example
string Colors[] = { "red", "green", "blue", "yellow" };
int Selected = 2; // initially selects "blue"
dlgListBox(Colors, Selected) dlgMessageBox("You have selected " +
Colors[Selected]);

dlgListView
Function
Definesamulticolumnlistviewselectionfield.
Syntax
dlgListView(string Headers, string array[], int &Selected[,
int &Sort]) [ statement ]

SeealsodlgListBox,dlgLabel,LayoutInformation,ACompleteExample
ThedlgListViewstatementdefinesamulticolumnlistviewselectionfieldwiththe
contentsofthegivenarray.

Page120of136
EAGLEUserLanguage Version5.7

Headersisthetabseparatedlistofcolumnheaders.
Selectedreflectstheindexoftheselectedlistviewentryinthearray(thesequencein
whichtheentriesareactuallydisplayedmaybedifferent,becausethecontentsofa
dlgListViewcanbesortedbythevariouscolumns).Thefirstentryhasindex0.
Ifnoparticularentryshallbeinitiallyselected,Selectedshouldbeinitializedto-1.
Sortdefineswhichcolumnshouldbeusedtosortthelistview.Theleftmostcolumnis
numbered1.Thesignofthisparameterdefinesthedirectioninwhichtosort(positive
valuessortinascendingorder).IfSortis0oroutsidethevalidnumberofcolumns,no
sortingwillbedone.ThereturnedvalueofSortreflectsthecolumnandsortmode
selectedbytheuserbyclickingonthelistcolumnheaders.BydefaultdlgListViewsorts
bythefirstcolumn,inascendingorder.
Eachelementofarraydefinesthecontentsofonelineinthelistview,andmustcontain
tabseparatedvalues.Iftherearefewervaluesinanelementofarraythanthereare
entriesintheHeadersstringtheremainingfieldswillbeempty.Iftherearemorevaluesin
anelementofarraythanthereareentriesintheHeadersstringthesuperfluous
elementswillbesilentlydropped.Noneofthestringsinarraymaybeempty(ifthereis
anemptystring,allstringsafterandincludingthatonewillbedropped).
Alistentrythatcontainslinefeeds('\n')willbedisplayedinseverallinesaccordingly.
Theoptionalstatementisexecutedwhenevertheuserdoubleclicksonanentryofthe
dlgListView.
Beforethestatementisexecuted,allvariablesthathavebeenusedwithdialogobjects
areupdatedtotheircurrentvalues,andanychangesmadetothesevariablesinsidethe
statementwillbereflectedinthedialogwhenthestatementreturns.
IftheinitialvalueofSelectedisoutsidetherangeofthearrayindexes,noentrywillbe
selected.
IfHeadersisanemptystring,thefirstelementofthearrayisusedastheheaderstring.
Consequentlytheindexofthefirstentryisthen1.
ThecontentsofadlgListViewcanbesortedbyanycolumnbyclickingonthatcolumn's
header.Columnscanalsobeswappedby"click&dragging"acolumnheader.Notethatnone
ofthesechangeswillhaveanyeffectonthecontentsofthearray.Ifthecontentsshallbe
sortedalphanumericallyanumeric string[]arraycanbeused.

Example
string Colors[] = { "red\tThe color RED", "green\tThe color GREEN", "blue\tThe
color BLUE" };
int Selected = 0; // initially selects "red"
dlgListView("Name\tDescription", Colors, Selected) dlgMessageBox("You have
selected " + Colors[Selected]);

dlgPushButton
Function

Page121of136
EAGLEUserLanguage Version5.7

Definesapushbutton.
Syntax
dlgPushButton(string Text) statement

SeealsoLayoutInformation,DialogFunctions,ACompleteExample
ThedlgPushButtonstatementdefinesapushbuttonwiththegivenText.
IfTextcontainsan'&',thecharacterfollowingtheampersandwillbecomeahotkey,and
whentheuserhitsAlt+hotkey,thebuttonwillbeselected.Tohaveanactual'&'
characterinthetextithastobeescaped.
IfTextstartswitha'+'character,thisbuttonwillbecomethedefaultbutton,whichwill
beselectediftheuserhitsENTER.
IfTextstartswitha'-'character,thisbuttonwillbecomethecancelbutton,whichwill
beselectediftheuserclosesthedialog.
CAUTION:Makesurethatthestatementofsuchamarkedcancelbuttoncontainsa
calltodlgReject()!Otherwisetheusermaybeunabletoclosethedialogatall!
Tohaveanactual'+'or'-'characterasthefirstcharacterofthetextithastobe
escaped.
IftheuserselectsadlgPushButton,thegivenstatementisexecuted.
Beforethestatementisexecuted,allvariablesthathavebeenusedwithdialogobjects
areupdatedtotheircurrentvalues,andanychangesmadetothesevariablesinsidethe
statementwillbereflectedinthedialogwhenthestatementreturns.

Example
int defaultWidth = 10;
int defaultHeight = 20;
int width = 5;
int height = 7;
dlgPushButton("&Reset defaults") {
width = defaultWidth;
height = defaultHeight;
}
dlgPushButton("+&Accept") dlgAccept();
dlgPushButton("-Cancel") { if (dlgMessageBox("Are you sure?", "Yes", "No") == 0)
dlgReject(); }

dlgRadioButton
Function
Definesaradiobutton.
Syntax
dlgRadioButton(string Text, int &Selected) [ statement ]

SeealsodlgCheckBox,dlgGroup,LayoutInformation,ACompleteExample
ThedlgRadioButtonstatementdefinesaradiobuttonwiththegivenText.

Page122of136
EAGLEUserLanguage Version5.7

IfTextcontainsan'&',thecharacterfollowingtheampersandwillbecomeahotkey,and
whentheuserhitsAlt+hotkey,thebuttonwillbeselected.Tohaveanactual'&'
characterinthetextithastobeescaped.
dlgRadioButtoncanonlybeusedwithinadlgGroup.
AllradiobuttonswithinthesamegroupmustusethesameSelectedvariable!
IftheuserselectsadlgRadioButton,theindexofthatbuttonwithinthedlgGroupis
storedintheSelectedvariable.
TheinitialvalueofSelecteddefineswhichradiobuttonisinitiallyselected.IfSelected
isoutsidethevalidrangeforthisgroup,noradiobuttonwillbeselected.Inordertogetthe
correctradiobuttonselection,SelectedmustbesetbeforethefirstdlgRadioButtonis
defined,andmustnotbemodifiedbetweenaddingsubsequentradiobuttons.Otherwiseit
isundefinedwhich(ifany)radiobuttonwillbeselected.
TheoptionalstatementisexecutedeverytimethedlgRadioButtonisselected.

Example
int align = 1;
dlgGroup("Alignment") {
dlgRadioButton("&Top", align);
dlgRadioButton("&Center", align);
dlgRadioButton("&Bottom", align);
}

dlgRealEdit
Function
Definesarealentryfield.
Syntax
dlgRealEdit(real &Value, real Min, real Max)

SeealsodlgIntEdit,dlgStringEdit,dlgLabel,LayoutInformation,ACompleteExample
ThedlgRealEditstatementdefinesarealentryfieldwiththegivenValue.
IfValueisinitiallyoutsidetherangedefinedbyMinandMaxitwillbelimitedtothese
values.

Example
real Value = 1.4142;
dlgHBoxLayout {
dlgLabel("Enter a &Number between 0 and 99");
dlgRealEdit(Value, 0.0, 99.0);
}

dlgSpacing
Function

Page123of136
EAGLEUserLanguage Version5.7

Definesadditionalspaceinaboxlayoutcontext.
Syntax
dlgSpacing(int Size)

SeealsodlgHBoxLayout,dlgVBoxLayout,dlgStretch,LayoutInformation,AComplete
Example
ThedlgSpacingstatementdefinesadditionalspaceinaverticalorhorizontalboxlayout
context.
Sizedefinesthenumberofpixelsoftheadditionalspace.

Example
dlgVBoxLayout {
dlgLabel("Label 1");
dlgSpacing(40);
dlgLabel("Label 2");
}

dlgSpinBox
Function
Definesaspinboxselectionfield.
Syntax
dlgSpinBox(int &Value, int Min, int Max)

SeealsodlgIntEdit,dlgLabel,LayoutInformation,ACompleteExample
ThedlgSpinBoxstatementdefinesaspinboxentryfieldwiththegivenValue.
IfValueisinitiallyoutsidetherangedefinedbyMinandMaxitwillbelimitedtothese
values.

Example
int Value = 42;
dlgHBoxLayout {
dlgLabel("&Select value");
dlgSpinBox(Value, 0, 99);
}

dlgStretch
Function
Definesanemptystretchablespaceinaboxlayoutcontext.
Syntax
dlgStretch(int Factor)

SeealsodlgHBoxLayout,dlgVBoxLayout,dlgSpacing,LayoutInformation,AComplete
Example

Page124of136
EAGLEUserLanguage Version5.7

ThedlgStretchstatementdefinesanemptystretchablespaceinaverticalorhorizontal
boxlayoutcontext.
Factordefinesthestretchfactorofthespace.

Example
dlgHBoxLayout {
dlgStretch(1);
dlgPushButton("+OK") { dlgAccept(); };
dlgPushButton("Cancel") { dlgReject(); };
}

dlgStringEdit
Function
Definesastringentryfield.
Syntax
dlgStringEdit(string &Text)

SeealsodlgRealEdit,dlgIntEdit,dlgTextEdit,dlgLabel,LayoutInformation,AComplete
Example
ThedlgStringEditstatementdefinesatextentryfieldwiththegivenText.

Example
string Name = "Linus";
dlgHBoxLayout {
dlgLabel("Enter &Name");
dlgStringEdit(Name);
}

dlgTabPage
Function
Definesatabpage.
Syntax
dlgTabPage(string Title) statement

SeealsodlgTabWidget,LayoutInformation,ACompleteExample
ThedlgTabPagestatementdefinesatabpagewiththegivenTitlecontainingthegiven
statement.
IfTitlecontainsan'&',thecharacterfollowingtheampersandwillbecomeahotkey,
andwhentheuserhitsAlt+hotkey,thistabpagewillbeopened.Tohaveanactual'&'
characterinthetextithastobeescaped.
TabpagescanonlybeusedwithinadlgTabWidget.
BydefaultadlgTabPagecontainsadlgVBoxLayout,soasimpletabpagedoesn'thaveto

Page125of136
EAGLEUserLanguage Version5.7

worryaboutthelayout.

Example
dlgTabWidget {
dlgTabPage("Tab &1") {
dlgLabel("This is page 1");
}
dlgTabPage("Tab &2") {
dlgLabel("This is page 2");
}
}

dlgTabWidget
Function
Definesacontainerfortabpages.
Syntax
dlgTabWidget statement

SeealsodlgTabPage,LayoutInformation,ACompleteExample
ThedlgTabWidgetstatementdefinesacontainerforasetoftabpages.
statementmustbeasequenceofoneormoredlgTabPageobjects.Theremustbeno
otherdialogobjectsinthissequence.

Example
dlgTabWidget {
dlgTabPage("Tab &1") {
dlgLabel("This is page 1");
}
dlgTabPage("Tab &2") {
dlgLabel("This is page 2");
}
}

dlgTextEdit
Function
Definesamultilinetextentryfield.
Syntax
dlgTextEdit(string &Text)

SeealsodlgStringEdit,dlgTextView,dlgLabel,LayoutInformation,ACompleteExample
ThedlgTextEditstatementdefinesamultilinetextentryfieldwiththegivenText.
ThelinesintheTexthavetobedelimitedbyanewlinecharacter('\n').Anywhitespace
charactersattheendofthelinescontainedinTextwillberemoved,anduponreturnthere
willbenowhitespacecharactersattheendofthelines.Emptylinesattheendofthetext

Page126of136
EAGLEUserLanguage Version5.7

willberemovedentirely.

Example
string Text = "This is some text.\nLine 2\nLine 3";
dlgVBoxLayout {
dlgLabel("&Edit the text");
dlgTextEdit(Text);
}

dlgTextView
Function
Definesamultilinetextviewerfield.
Syntax
dlgTextView(string Text)
dlgTextView(string Text, string &Link) statement

SeealsodlgTextEdit,dlgLabel,LayoutInformation,ACompleteExample
ThedlgTextViewstatementdefinesamultilinetextviewerfieldwiththegivenText.
TheTextmaycontainHTMLtags.
IfLinkisgivenandtheTextcontainshyperlinks,statementwillbeexecutedeverytime
theuserclicksonahyperlink,withthevalueofLinksettowhateverthe<a href=...>
tagdefinesasthevalueofhref.If,aftertheexecutionofstatement,theLinkvariableis
notempty,thedefaulthandlingofhyperlinkswilltakeplace.ThisisalsothecaseifLink
containssometextbeforedlgTextViewisopened,whichallowsforaninitialscrollingtoa
givenposition.

Example
string Text = "This is some text.\nLine 2\nLine 3";
dlgVBoxLayout {
dlgLabel("&View the text");
dlgTextView(Text);
}

dlgVBoxLayout
Function
Opensaverticalboxlayoutcontext.
Syntax
dlgVBoxLayout statement

SeealsodlgGridLayout,dlgHBoxLayout,LayoutInformation,ACompleteExample
ThedlgVBoxLayoutstatementopensaverticalboxlayoutcontextforthegiven
statement.

Page127of136
EAGLEUserLanguage Version5.7

BydefaultadlgDialogcontainsadlgVBoxLayout,soasimpledialogdoesn'thaveto
worryaboutthelayout.

Example
dlgVBoxLayout {
dlgLabel("Box 1");
dlgLabel("Box 2");
dlgLabel("Box 3");
}

Layout Information
AllobjectswithinaUserLanguageDialogaplacedinsidealayoutcontext.
Layoutcontextscanbeeithergrid,horizontalorvertical.

Grid Layout Context

Objectsinagridlayoutcontextmustspecifythegridcoordinatesofthecellorcellsinto
whichtheyshallbeplaced.Toplaceatextlabelatrow5,column2,youwouldwrite
dlgGridLayout {
dlgCell(5, 2) dlgLabel("Text");
}

Iftheobjectshallspanovermorethanonecellyouneedtospecifythecoordinatesofthe
startingcellandtheendingcell.Toplaceagroupthatextendsfromrow1,column2upto
row3,column5,youwouldwrite
dlgGridLayout {
dlgCell(1, 2, 3, 5) dlgGroup("Title") {
//...
}
}

Horizontal Layout Context

Objectsinahorizontallayoutcontextareplacedlefttoright.
ThespecialobjectsdlgStretchanddlgSpacingcanbeusedtofurtherrefinethedistribution
oftheavailablespace.
Todefinetwobuttonsthatarepushedallthewaytotherightedgeofthedialog,youwould
write
dlgHBoxLayout {
dlgStretch(1);
dlgPushButton("+OK") dlgAccept();
dlgPushButton("Cancel") dlgReject();
}

Page128of136
EAGLEUserLanguage Version5.7

Vertical Layout Context

Objectsinaverticallayoutcontextfollowthesamerulesasthoseinahorizontallayout
context,exceptthattheyareplacedtoptobottom.

Mixing Layout Contexts

Vertical,horizontalandgridlayoutcontextscanbemixedtocreatethedesiredlayout
structureofadialog.SeetheCompleteExampleforademonstrationofthis.

Dialog Functions
ThefollowingfunctionscanbeusedwithUserLanguageDialogs:
dlgAccept() closesthedialogandacceptsitscontents
immediatelyredisplaysthedialogafterchangestoany
dlgRedisplay()
values
dlgReset() resetsalldialogobjectstotheirinitialvalues
dlgReject() closesthedialogandrejectsitscontents

dlgAccept()
Function
Closesthedialogandacceptsitscontents.
Syntax
void dlgAccept([ int Result ]);

SeealsodlgReject,dlgDialog,ACompleteExample
ThedlgAcceptfunctioncausesthedlgDialogtobeclosedandreturnafterthecurrent
statementsequencehasbeencompleted.
Anychangestheuserhasmadetothedialogvalueswillbeacceptedandarecopiedinto
thevariablesthathavebeengivenwhenthedialogobjectsweredefined.
TheoptionalResultisthevaluethatwillbereturnedbythedialog.Typicallythisshould
beapositiveintegervalue.Ifnovalueisgiven,itdefaultsto1.
NotethatdlgAccept()doesreturntothenormalprogramexecution,soinasequence
like
dlgPushButton("OK") {
dlgAccept();
dlgMessageBox("Accepting!");
}

thestatementafterdlgAccept()willstillbeexecuted!

Example
int Result = dlgDialog("Test") {
dlgPushButton("+OK") dlgAccept(42);
dlgPushButton("Cancel") dlgReject();

Page129of136
EAGLEUserLanguage Version5.7

};

dlgRedisplay()
Function
Redisplaysthedialogafterchangingvalues.
Syntax
void dlgRedisplay(void);

SeealsodlgReset,dlgDialog,ACompleteExample
ThedlgRedisplayfunctioncanbecalledtoimmediatelyrefreshthedlgDialogafter
changeshavebeenmadetothevariablesusedwhendefiningthedialogobjects.
YouonlyneedtocalldlgRedisplay()ifyouwantthedialogtoberefreshedwhilestill
executingprogramcode.Intheexamplebelowthestatusischangedto"Running..."and
dlgRedisplay()hastobecalledtomakethischangetakeeffectbeforethe"program
action"isperformed.Afterthefinalstatuschangeto"Finished."thereisnoneedtocall
dlgRedisplay(),sincealldialogobjectsareautomaticallyupdatedafterleavingthe
statement.

Example
string Status = "Idle";
int Result = dlgDialog("Test") {
dlgLabel(Status, 1); // note the '1' to tell the label to be
updated!
dlgPushButton("+OK") dlgAccept(42);
dlgPushButton("Cancel") dlgReject();
dlgPushButton("Run") {
Status = "Running...";
dlgRedisplay();
// some program action here...
Status = "Finished.";
}
};

dlgReset()
Function
Resetsalldialogobjectstotheirinitialvalues.
Syntax
void dlgReset(void);

SeealsodlgReject,dlgDialog,ACompleteExample
ThedlgResetfunctioncopiestheinitialvaluesbackintoalldialogobjectsofthecurrent
dlgDialog.
Anychangestheuserhasmadetothedialogvalueswillbediscarded.
CallingdlgReject()impliesacalltodlgReset().

Page130of136
EAGLEUserLanguage Version5.7

Example
int Number = 1;
int Result = dlgDialog("Test") {
dlgIntEdit(Number);
dlgPushButton("+OK") dlgAccept(42);
dlgPushButton("Cancel") dlgReject();
dlgPushButton("Reset") dlgReset();
};

dlgReject()
Function
Closesthedialogandrejectsitscontents.
Syntax
void dlgReject([ int Result ]);

SeealsodlgAccept,dlgReset,dlgDialog,ACompleteExample
ThedlgRejectfunctioncausesthedlgDialogtobeclosedandreturnafterthecurrent
statementsequencehasbeencompleted.
Anychangestheuserhasmadetothedialogvalueswillbediscarded.Thevariablesthat
havebeengivenwhenthedialogobjectsweredefinedwillberesettotheiroriginalvalues
whenthedialogreturns.
TheoptionalResultisthevaluethatwillbereturnedbythedialog.Typicallythisshould
be0oranegativeintegervalue.Ifnovalueisgiven,itdefaultsto0.
NotethatdlgReject()doesreturntothenormalprogramexecution,soinasequence
like
dlgPushButton("Cancel") {
dlgReject();
dlgMessageBox("Rejecting!");
}

thestatementafterdlgReject()willstillbeexecuted!
CallingdlgReject()impliesacalltodlgReset().

Example
int Result = dlgDialog("Test") {
dlgPushButton("+OK") dlgAccept(42);
dlgPushButton("Cancel") dlgReject();
};

Escape Character
Somecharactershavespecialmeaningsinbuttonorlabeltexts,sotheyneedtobeescaped
iftheyshallappearliterally.

Page131of136
EAGLEUserLanguage Version5.7

Todothisyouneedtoprependthecharacterwithabackslash,asin
dlgLabel("Miller \\& Co.");

Thiswillresultin"Miller&Co."displayedinthedialog.
Notethatthereareactuallytwobackslashcharactershere,sincethislinewillfirstgo
throughtheUserLanguageparser,whichwillstripthefirstbackslash.

A Complete Example
Here'sacompleteexampleofaUserLanguageDialog.
int hor = 1;
int ver = 1;
string fileName;
int Result = dlgDialog("Enter Parameters") {
dlgHBoxLayout {
dlgStretch(1);
dlgLabel("This is a simple dialog");
dlgStretch(1);
}
dlgHBoxLayout {
dlgGroup("Horizontal") {
dlgRadioButton("&Top", hor);
dlgRadioButton("&Center", hor);
dlgRadioButton("&Bottom", hor);
}
dlgGroup("Vertical") {
dlgRadioButton("&Left", ver);
dlgRadioButton("C&enter", ver);
dlgRadioButton("&Right", ver);
}
}
dlgHBoxLayout {
dlgLabel("File &name:");
dlgStringEdit(fileName);
dlgPushButton("Bro&wse") {
fileName = dlgFileOpen("Select a file", fileName);
}
}
dlgGridLayout {
dlgCell(0, 0) dlgLabel("Row 0/Col 0");
dlgCell(1, 0) dlgLabel("Row 1/Col 0");
dlgCell(0, 1) dlgLabel("Row 0/Col 1");
dlgCell(1, 1) dlgLabel("Row 1/Col 1");
}
dlgSpacing(10);
dlgHBoxLayout {
dlgStretch(1);
dlgPushButton("+OK") dlgAccept();
dlgPushButton("Cancel") dlgReject();
}
};

Page132of136
EAGLEUserLanguage Version5.7

Supported HTML tags

EAGLEsupportsasubsetofthetagsusedtoformatHTMLpages.Thiscanbeusedto
formatthetextofseveralUserLanguageDialogobjects,inthe#usagedirectiveorinthe
descriptionoflibraryobjects.
TextisconsideredtobeHTMLifthefirstlinecontainsatag.Ifthisisnotthecase,andyou
wantthetexttobeformatted,youneedtoenclosetheentiretextinthe
<html>...</html>tag.
ThefollowingtablelistsallsupportedHTMLtagsandtheiravailableattributes:
Tag Description
AnHTMLdocument.Itunderstandsthefollowingattributes

bgcolorThebackgroundcolor,forexample
bgcolor="yellow"orbgcolor="#0000FF".
<html>...</html> backgroundThebackgroundpixmap,forexample
background="granit.xpm".
textThedefaulttextcolor,forexampletext="red".
linkThelinkcolor,forexamplelink="green".

<h1>...</h1> Atoplevelheading.
<h2>...</h2> Asublevelheading.
<h3>...</h3> Asubsublevelheading.
Aleftalignedparagraph.Adjustthealignmentwiththealign
<p>...</p>
attribute.Possiblevaluesareleft,rightandcenter.
<center>...</center
Acenteredparagraph.
>
<blockquote>...</blo
Anindentedparagraph,usefulforquotes.
ckquote>
Anunorderedlist.Youcanalsopassatypeargumenttodefinethe
<ul>...</ul> bulletstyle.Thedefaultistype=disc,othertypesarecircle
andsquare.
Anorderedlist.Youcanalsopassatypeargumenttodefinethe
<ol>...</ol> enumerationlabelstyle.Thedefaultistype="1",othertypesare
"a"and"A".
Alistitem.Thistagcanonlybeusedwithinthecontextofolor
<li>...</li>
ul.
Forlargerchunksofcode.Whitespacesinthecontentsare
<pre>...</pre>
preserved.Forsmallbitsofcode,usetheinlinestylecode.
Ananchororlink.Itunderstandsthefollowingattributes:

hrefThereferencetargetasin<a
<a>...</a>
href="#123">...</a>.
nameTheanchorname,asin<a name="123">...</a>.

Page133of136
EAGLEUserLanguage Version5.7

<em>...</em> Emphasized(sameas<i>...</i>).
<strong>...</strong
Strong(sameas<b>...</b>).
>
<i>...</i> Italicfontstyle.
<b>...</b> Boldfontstyle.
<u>...</u> Underlinedfontstyle.
<big>...</big> Alargerfontsize.
<small>...</small> Asmallerfontsize.
IndicatesCode.(sameas<tt>...</tt>.Forlargerchunksof
<code>...</code>
code,usetheblocktagpre.
<tt>...</tt> Typewriterfontstyle.
Customizesthefontsize,familyandtextcolor.Thetagunderstands
thefollowingattributes:

colorThetextcolor,forexamplecolor="red"or
color="#FF0000".
<font>...</font> sizeThelogicalsizeofthefont.Logicalsizes1to7are
supported.Thevaluemayeitherbeabsolute,forexample
size=3,orrelativelikesize=-2.Inthelattercase,the
sizesaresimplyadded.
faceThefamilyofthefont,forexampleface=times.

Animage.Thistagunderstandsthefollowingattributes:

srcTheimagename,forexample<img
src="image.xpm">.
Supportedimageformatsare:
".bmp"(WindowsBitmapFiles)
".pbm"(PortableBitmapFiles)
".pgm"(PortableGrayscaleBitmapFiles)
".png"(PortableNetworkGraphicsFiles)
".ppm"(PortablePixelmapFiles)
<img...>
".xbm"(XBitmapFiles)
".xpm"(XPixmapFiles)
widthThewidthoftheimage.Iftheimagedoesnotfitto
thespecifiedsize,itwillbescaledautomatically.
heightTheheightoftheimage.
alignDetermineswheretheimageisplaced.Perdefault,
animageisplacedinline,justlikeanormalcharacter.
Specifyleftorrighttoplacetheimageattherespective
side.

<hr> Ahorizonalline.
<br> Alinebreak.
<nobr>...</nobr> Nobreak.Preventswordwrap.

Page134of136
EAGLEUserLanguage Version5.7

Atabledefinition.Thedefaulttableisframeless.Specifythe
booleanattributeborderinordertogetaframe.Otherattributes
are:

bgcolorThebackgroundcolor.
widthThetablewidth.Thisiseitherabsoluteinpixelsor
relativeinpercentofthecolumnwidth,forexample
<table>...</table> width=80%.
borderThewidthofthetableborder.Thedefaultis0(=
noborder).
cellspacingAdditionalspacearoundthetablecells.The
defaultis2.
cellpaddingAdditionalspacearoundthecontentsof
tablecells.Defaultis1.

Atablerow.Canonlybeusedwithintable.Understandsthe
attribute
<tr>...</tr>
bgcolorThebackgroundcolor.

Atabledatacell.Canonlybeusedwithintr.Understandsthe
attributes

bgcolorThebackgroundcolor.
widthThecellwidth.Thisiseitherabsoluteinpixelsor
relativeinpercentoftheentiretablewidth,forexample
width=50%.
<td>...</td>
colspanDefineshowmanycolumnsthiscellspans.The
defaultis1.
rowspanDefineshowmanyrowsthiscellspans.The
defaultis1.
alignAlignment,possiblevaluesareleft,rightand
center.Thedefaultisleftaligned.

Atableheadercell.Liketdbutdefaultstocenteralignmentanda
<th>...</th>
boldfont.
<author>...</author
Markstheauthorofthistext.
>
<dl>...</dl> Adefinitionlist.
<dt>...</dt> Adefinitiontag.Canonlybeusedwithindl.
<dd>...</dd> Definitiondata.Canonlybeusedwithindl.
Tag Meaning
&lt; <
&gt; >
&amp; &

Page135of136
EAGLEUserLanguage Version5.7

&nbsp; nonbreakingspace
&auml;
&ouml;
&uuml;
&Auml;
&Ouml;
&Uuml;
&szlig;
&copy;
&deg;
&micro;
&plusmn;

Page136of136