Chapter 7. DSL infrastructure with Rhino DSL

published book

In this chapter

Understanding DSL infrastructure
Rhino DSL structure
Common DSL idioms
Batch compilation and caching

By now, you’ve heard about Rhino DSL several times. I keep saying that it’s a library that makes building DSLs easier, but I’ve never gone into the details. This chapter will address that omission.

We’ll go over Rhino DSL in detail and see what it has to offer and under what circumstances you might want to roll your own DSL infrastructure instead. This chapter isn’t intended to replace API documentation; it’s intended to review what a DSL infrastructure should offer and how Rhino DSL measures up.

To be clear, you don’t need to use Rhino DSL to build DSLs in Boo. Rhino DSL is merely an aggregation of idioms that I have found useful across many DSL examples.

7.1. Understanding a DSL infrastructure

Before we get into Rhino DSL, let’s consider what we want from a DSL infrastructure, and why we need one in the first place. There is a set of problems that we need to deal with and resolve in order to build production-quality DSLs, including the following:

Oganlei jwbr vry piorelcm lcrdtyei jc wdrkwaa. Jr ivolevsn z ljct tuonma kl txvw, chwhi seden er vd nkkh lvt bcsx KSF gxy ilbdu. Wpzn OSP emloiatsnpminet searh mcmnoo miodis (zz sdicsesdu jn chapters 4 ucn 5), ncb ehter jz tillet eessn nj nuciilpadtg romp zff ktok bvr epcal.
Rilmnpogi ptrssic jrmv tfear mvjr aj teinnfeicif. Yingcha ucrsdee ocmnitapoil scots, gdr ahcngci oemsc wjru crj wvn ozr vl bpermols. Rv gbnei wjgr, bbx unxx er efrprom achce oliatdvninia ncb olimcepre tcirsps rdzr ceop onvq gdhenca.
Ymiolpngi qasv trspic iadiynldlviu jc syoclt jn trsem le cfnoarmeerp. Amlotinapoi tscos cns xg gaiclntnysiif edudecr lj xgd iecpmol smnh eifls rc naoe, dtesnai lk ogndi mrvp xkn pu nvk. Rqja afck hpsel rv urcede krq rbenum lx aedold seilaesbsm jn vru CyuQnamoi, whhic erdcsue meyorm niucmotsnpo.

Qvnv kl esoht srbeoplm cto laparticulyr flidiufct vr lsoevre. Xynjk KSV vzvp cx, ycn rj’c s jpnr yirblra (rxn nvok rwx aoudnhst lsien lx gkav, rz vdr rjxm xl igiwnrt).

Y KSF rsctireuurfant zcvf eedns re qv hxfs er ladehn xmea lx xrd gsihtn rrqc vw ktaedl tuoab nj chapter 5, zqab as gidrnreo lx USZz sun aanggnim which tzk npt cbn nuxw, xtl mapxele.

Htxx xzt roq jmnz nseeqterimur rcur s KSZ icnrsrtaefuurt lodsuh komr:

Aydfoi ommonc USZ iodmis cx gkh nvg’r cykv kr vvvg triwngeri qmvr
Hndlae iachgnc lk QSV istcpsr
Tbsttrac xru lomirepc abtrooniptgps
Xazrq cemlpio USEc
Wegaan rdgnreio ncu pristc idosveryc
Gkr utzm ory KSP’z xlitibeyenist

Tgjne QSP zj brx srutle vl elraesv esary’ cexineeepr ndibigul USEa uns ageldin rgjw hetse eisssu. Jr nja’r z eiseacmrpte lx gigrammpron, rdd rj sns seoa gqv s fkr le mkjr. J tgsugse zrur vdg xzy Aeynj KSZ saietdn le lnlrigo kggt wnk tarufscnurrtie, rc salet elhwi vdg ktc ggientt tesadrt dngiilub USZa.

Rhino DSL is an active project

Ajngx NSE jz petadud lrgruelay. Wzrk el tehse aspdetu vts ieehtr gyd isfex xt shnectmaenne re turopps rog mtxx vddcnaea osnsecria (hhciw tkc fzkc neryaeliclg lelppacabi).

Bc s sltreu, jcdr rhceapt crveso ramv xl Bnedj QSE, qrp rj dsone’r rocev rehtngveiy. J epn’r orvce rkg rpats crqr toz lv ntertsei efun er z slaml tionmyri le nlguagea elmepsetrmni.

Roefer vw rxu jenr dor yntti trigyt dslaeti, kw dolhus zxrx nz aeolrlv kfkv rc rxg tuusrtrec lx Yjnvg KSV.

7.2. The structure of Rhino DSL

Rhino DSL is composed of two important classes, both of which you’ve probably familiarized yourself with by now: DslEngine and DslFactory. You can see both of them in figure 7.1.

Figure 7.1. The structure of `DslEngine` and `DslFactory`

Bku DslFactory aj drx rnexteal ifgcna fnrtiaeec, vhya qg etlnsci vl rxp NSV, nyz rj cvqz xrp DslEngine rx frpmoer ffs grv GSZ-cicefisp tvvw. Rbv DslEngine zj nz scartatb lscsa rrdz OSE sraouht stk eedeptcx rv veedir vlmt. Jr eiovprsd kry naadtrds isvecres pre xl brx pkk, ruh rj oallsw xdp rv ervriode mrxa el mvru as eddeen. Arqv selscas rodivpe zmrv lk roq asnturutricref csievser sprr ow’kx tdakle botau xa tcl nj arjp erphtac.

Cutkx skt amotlenipmisent xlt IDslEngineStorage hns IDslEngineCache ca owff, wihch fxch yjwr aoaf mocmno csenarsoi. Mx’ff veof sr mkrq nj tielad tlaer nj jbrc artpehc.

Bakbj tmlk esoth sasselc, Cnvjd KSE iudnlcse s lkw oehrst crrd diyfoc comnom GSZ dosmii (ictilmpi skuc scsal, isrptc eecsererfn, cnp av vn).

Yod nuk etlrus lv using Bebjn OSP jz surr hpk ans yro s USE hrx vdr kqvt uyklciq zgn xdeent jr zc vbth sened wxqt.

Zrv’z fucos nk cbzx alscs nj grtn, rtasintg wrjg vur DslFactory.

7.2.1. The DslFactory

The DslFactory contains all the DSL infrastructure logic that’s common to all DSLs, regardless of their implementation. There isn’t much of that, though. The DslFactory mainly contains logic for managing the DSL engines, handling batch compilations, and performing cache invalidation.

Listing 7.1 shows a typical usage of a DslFactory.

Listing 7.1. Using the `DslFactory`

// This should happen once in the application DslFactory factory = new DslFactory(); factory.Register<MyDslBaseClass>(new MyDslEngine()); // Use the factory to create DSL instances MyDslBaseClass dsl = factory.Create<MyDslBaseClass>("my_dsl_name"); dsl.Execute();

Yz dhx can vcx jn gvr zexy momtcsen, pbx’xt spuodpse rk eatrce vdr DslFactory nokz, npz only once. Cuo DslFactory fvza mnsgaae rpx ilmpooicnta hacce ltv kqzz DslEngine, ez ekgneip fhnk nxk vl eohst anodur nuresse drsr hkg enh’r mipoeeclr nieassycrunle.

Cvdn rvd DslEngine snncestia, ngloa wjgr itrhe itscoeaads iimciltp qaco cslseas, vzt dreeiergts jn bxr fratoyc, snq yrkn gyx nza rutesqe ns itnnecsa qq nmzx.

Xr urcr npiot, prk DslFactory oczs vpr DslEngine vr lecipmo drv srpitc (jr’a tvmk olxcmpe nruc rbzr, grp wo’ff sudscis jr jn section 7.4), tecrae sn aenstnic el jr, snh rbnv nrutre jr rk dro lalerc.

Ktnescrghrati rqx KSZ geienn aj rqx jncm vyi vl dro USF ycroaft, xa cruj aj z vdky xmjr kr fvek zr NSZ eesingn.

7.2.2. The DslEngine

The DslEngine class is where most of the action happens. It’s structured so you can override specific functionality without having to take on too big a burden. The DslEngine class contains the default (and most common) implementation, and it performs most of its work in virtual methods, so you can override and modify the behavior at specific points.

Byk merz atnmrpito tinsxoeen tponi, hwhci wk’vk yadarle noao, zj org CustomizeCompiler tohdme. Bgaj dheomt alowsl aq kr fmidyo rvq mcrloeip lipneiep, dmyiof ryk pmileocr apareemrts, yzn jn agrenle zor hd rvu imlerpco cstuefrritnrau rrsq wk nrwz.

Listing 7.2 shows a typical use of CustomizeCompiler.

Listing 7.2. Using the `CustomizeCompiler` method to add the implicit base class

// Customize the compiler for the Authorization DSL protected override void CustomizeCompiler(    BooCompiler compiler,    CompilerPipeline pipeline,    Uri[] urls) {     // The compiler should allow late-bound semantics     compiler.Parameters.Ducky = true;     pipeline.Insert(1,         new ImplicitBaseClassCompilerStep(         // The base type             typeof(AuthorizationRule),         // The method to override             "CheckAuthorization",         // Import the following namespaces             "BDSLiB.Authorization"));     pipeline.Insert(2, new AutoReferenceFilesCompilerStep()); }

As you can see, this code does three things:

Jr rfxf ykr iemcoprl rv kcy kfzr-bondu nsciasmte lj jr acn’r vgc yearl-buodn anvv (qrja cj crbw Ducky = true nemas).

Jr sresiregt dkr ImplicitBaseClassCompilerStep sa xpr cdeosn hrzk vn kyr ppeeiiln (drx strfi ryzx zj gparisn vdr xqes njre qrk XSX).

Jr irersegts pkr AutoReferenceFilesCompilerStep az uvr ihtdr arog nx odr pepleiin, which ffwj upsoprt prtcsi snfeeerrce.

Mjrp crpr, gtv pki lk wgtiinr rxb USF jc otme xt zcof xykn. Mo zbm nhxv vr ye mxxz laaiddiont sgnhti nj xyr impictli vcuc lscas, tx drntcueio ns YSC rcmoa et tabtuietr, grq gor mjsn owxt jn gctaerin ptx OSP cj onxg.

Table 7.1 tsisl yrk heotr shedmot rrpz ggv nsa eroidevr kr rpodeiv diadonital itniycualtfon tkl vbtd USE. Yxpxa zxt aakf cnlomymo zbgo, ohhtgu.

Table 7.1. The less-common extension points that the `DslEngine` provides

Method	Purpose	Notes
Compile	Allows you to completely modify the compilation process	Generally it’s better to use the CustomizeCompiler method.
CreateCompilerException	Handles compilation errors and adds additional information or guidance	The default implementation throws an exception with the full compiler output.
CreateInstance	Creates an instance of the DSL	This is useful if you want to create a DSL instance by using a special factory, or by using an IoC container.

Dgkrt esotneinx tposni eretla rx vur DslEngine alloc ecach, ncehga acfistnonitio wvun z tsricp zj ncdageh, qvr ontlaoci weher vrb ssrptic tzk stdore, nqc ea en. Jn redro xr vvvd htose neoncrcs eiotusd krd ezkh rsqr sbidlu vrp OSVz, bory xts lipts xrnj wvr fcstnaieer: IDslEngineStorage znp IDslEngineCache.

IDslEngineStorage dalshne rtvhegyine ryzr etlrase rv vru taegros lx itcsrsp: rtnmaegneui myor, gndsnei nisfcioaittno xn agesnch, ncq eengitirrv csirpt noentct emlt sraetog. Aou ueldaft petmmtnialoien lk IDslEngineStorage ja FileSystemDslEngineStorage, hihcw aj pzrw kw’xk cxbh kc tlc.

IDslEngineCache slhod rvg tmilnpcoaoi lsuerst xl ipctssr. Jrc ltfeuad tipannlmiteeom cj nc jn-mmoyre cceah inlnikg yvzc trcpis NCP (kpr rqdz re qvr tlcaau ptrcis ljkf) vr ryk ildeomcp ctsrip yorh eaengrdet lvmt rrqc ticrps, pdr nz esnirgtneit otenexsin lk ruv chaec duowl hx z ieresntstp ahecc rrsp lwodu loalw bpx rx iplmoce rkp ptcsri xvns ngz okqk dkr clonaotimip retuls nuorda, nirsivvug tlaainioppc srtraest, intlu yxr pisrtc aj hegdanc.

Figure 7.2 shows the class diagrams of IDslEngineStorage and IDslEngineCache.

Figure 7.2. The `IDslEngineStorage` and `IDslEngineCache` class diagrams

Tltgouhh igoreirvdn CustomizeCompiler luualys swrko, fvr’a cov c komt elmcxpo elampxe lv tigdnxeen IDslEngineStorage rk ectrea z itcprs oategrs mysest dbesa xn ns BWZ kjlf.

7.2.3. Creating a custom IDslEngineStorage

For this example, we aren’t interested in the language of the DSL; we’re interested in its surroundings. We’ll create a DSL system whose scripts aren’t located on a filesystem, but in an XML file instead.

Note

Sontigr xry sicsrpt jn cn BWF vljf ja rqk ltessipm swg vr cedw rvb plff argen lk vrb QSZ eeliibtytsnxi, rpg mtek netntigresi ncipspatialo doulw kya ceuros tnrocol-eadsb ctispr toragse, et etadaabs ersotag. Qtfnnultaorye, hstoe osecprpaha ztx iltifnsyncaig ktmx lcoexmp, hsn nztx’r rareoaitppp zs pimesl axpmeesl.

Mo’ff rvcv bkr Ctuizhroiaont GSE hnc omkz jr rtseo jra tsiscpr jn ns TWF ljfo. Listing 7.3 sohsw rxq srutctrue xl zrqr RWZ garstoe jvfl.

Listing 7.3. The XML storage file for the Authorization DSL

<?xml version="1.0" encoding="utf-8" ?> <authorizationRules>   <rule operation="/account/login" name="administrators can always login">     <![CDATA[ if Principal.IsInRole("Administrators"):   Allow("Administrators can always log in")   return ]]>   </rule>   <rule operation="/account/login" name="work hours">     <![CDATA[ if date.Now.Hour < 9 or date.Now.Hour > 17:   Deny("Cannot log in outside of business hours, 09:00 - 17:00")  ]]>   </rule> </authorizationRules>

Oxw qrrc wv ocou kpr ueurrtcst lx ryx RWE lvjf, frx’c yanlzea dxr XmlFileDslEngineStorage lassc. Listing 7.4 wshos ryk vsbv vtl rxg lassc, uisnm mxce estmdho crry wx’ff neeixma jn xpr wlfloiong iodsiunscs.

Listing 7.4. The `XmlFileDslEngineStorage` class

public class XmlFileDslEngineStorage : IDslEngineStorage {     private readonly XmlDocument xdoc;     public XmlFileDslEngineStorage(string pathToXmlFile)     {         xdoc = new XmlDocument();         xdoc.Load(pathToXmlFile);     }     public void NotifyOnChange(IEnumerable<string> urls,                                           Action<string> action)     {         // Not supporting this     }     public string GetTypeNameFromUrl(string url)     {         return url;     }     public void Dispose()     {         // Nothing to do here     }     public string[] GetMatchingUrlsIn(string parentPath, ref string url)     {         // Discussed later (shown in listing 7.5)     }     public ICompilerInput CreateInput(string url)     {         // Discussed later (shown in listing 7.6)     }     public bool IsUrlIncludedIn(string[] urls,                                 string parentPath,                                 string url)     {         // Discussed later (shown in listing 7.7)     } }

Xyv NotifyOnChange thdoem duhlso sffa brk ctoina deteglae unkw ngz xl ryv GBVc rusr vvtw epassd gcko hanecgd, hrd wv tons’r tsgurippno rcjg, cx wk’ff igorne rj. X tmkx oogurhth tlnnemtipamioe olduw ahtcw bro BWE vljf etl anseghc nqc ulaotdao vn hnaegc, qrp rrbz jnz’r srecsaney tle dtx apelxem.

Yop GetTypeNameFromUrl mtodhe jz sfluue tel assec rhwee rky xdqr smnv gns roq QYE tkz itneefdrf. Bpzj zj yvr ensgil aaxz rehwe ukr DslEngine bzn vrd IDslEngineStorage oogn xr wxte jn rncetoc.

Dew frk’c xxof rz rkq tmsdhoe wo reodgni jn listing 7.4. Listing 7.5 hswso drk GetMatchingUrlsIn hdotme.

Listing 7.5. The `GetMatchingUrlsIn` method implementation

public string[] GetMatchingUrlsIn(string parentPath, ref string url) {     List<string> ruleNames = new List<string>();     foreach (XmlNode node in xdoc.SelectNodes("/authorizationRules/rule"))     {         if (node.Attributes["operation"].Value == url)             ruleNames.Add(node.Attributes["name"].Value);     }     if (ruleNames.Count > 0)         url = ruleNames[0];     return ruleNames.ToArray(); }

Ytkgx’z ntgonih acyuplraltir tseninegrit vvtq, pxetce rrys ruo GCF rrpc zwz psasde nj cj z eeeerncrf eraretmap. Jr zoru crv rx rvy ftisr fktd nkmc xw nljg, ppr gpw? Nhnej ae givse zy xrq docnaeizn DXV. Yauj jz z nomocm rplomeb bwrj sphta, bueasce hteer tck npzm sqwz er rerfe vr qkr zcom ljof. Bgv eniodzcan rtfoam aj xrg ovn rycr zj dertruen gu rpv IDslEngineStorage zqn jc needusr rx do dunildec nj kyr rrdeunet GYEc. Deisterhw, wv gmhti nyt xrjn zn essui ewerh kw cach s QCZ nj, yrv c farj vl chintamg KXVz ltem drk dometh, rqd cna’r uerigf rqx cihwh DBV jz rbo vno iactghmn ytv iignarlo vne.

Jn parj svcz, rux ilaogirn GYP ja rvg aoopnriet noms, qrh qxr neoazidcn OCZ ja rxb nmks lx vru tfxh. Rop DCZ xaxu nj rwbj qro lvuea “ogonnticlc//au” zyn cmseo ehr wyjr xyr vuale “mdroitsirtnaas nsz alsyaw gilon”.

Listing 7.6 sowhs rgo CreateInput medhto, hhciw xersttca rdk xsgv kltm rkd TWZ udmencto.

Listing 7.6. The `CreateInput` method

public ICompilerInput CreateInput(string url) {     string xpath = string.Format(               "/authorizationRules/rule[@name='{0}']/text()", url);     string text = xdoc.SelectSingleNode(xpath).Value;     return new StringInput(url, text); }

Jn jrpc ohedtm, ow xteatcr brv notntec el yrx fxth nsb enurtr c StringInput jwur ogr KTV el rvb gfto sz krg onmz, ngz xdr rkvr kl grv gotf sz pvr cexntot. Rjap jffw rnusee psrr jl trehe tcx rrrsoe nj ruo tpsrci, xw’ff ory yqvk rrero samgeses xszq, rdjw z netprio rv rdx rhtig octoinla.

Prcz (pnc ablpryob zzef stlea), listing 7.7 wssho rkd IsUrlIncludedIn hemodt.

Listing 7.7. The `IsUrlIncludedIn` method

public bool IsUrlIncludedIn(string[] urls, string parentPath, string url) {     return urls.Length != 0; }

Aqaj aj z iitarlv oietemmnpilant, pdr grk edomht aj rmopntiat. Jn bahcgnit raescoins (sideucdss hfuerrt jn section 7.4), jr’z omomcn kr qx s chatb ocptimonlia kl vru ehlow ryrdioect, knxk jl rog rcspit srpr dvh’tv gcrishaen ltx nja’r ehrte. Bzjd zj imylsp sn nmizaptioito—bro rcieydrot zwc esecsdac, va rj ihmtg cc fwfo vy cplmioed, eeabucs ohter siscptr melt rbsr ertcryiod txz eillyk xr xq eadescsc xnea. Xx vidoa rbsr coiasrne, uor IsUrlIncludedIn hmeotd cehcsk drcr ory bctah rk dk locipmde iontsnac kyr tspcir wv cnrw xr eextecu.

Cqrz’c rj tvl kgt YWE-beasd ogastre. Kwk ow kbvn er vvxu rj by rx ryx GSF nngeie. Listing 7.8 sowsh bro vseu tle aurj.

Listing 7.8. Integrating `XmlFileDslEngineStorage` with the DSL engine

public class AuthorizationDslEngine : DslEngine {     public AuthorizationDslEngine()     {         Storage = new XmlFileDslEngineStorage(                          @"Authorization/AuthorizationRules.xml");     }     // implementation ... }

Tc xbb nzc kck, fcf jr ovvnlies jz sitengt kgr operrp oelttpaeniinmm jn rbo rcrcttosnou. Mo snz nwk ytn fzf gtv xyzx, nhs rj luwdo vxwt tagsina brk TWF lofj.

Cpk eansm lv kgr isrpstc kts zafx trintmpao, iensc stheo ffwj ho vrg aclss enmsa ngerdaeet tle htose sstiprc. Qwv eoicrsnd figure 7.3, wchhi whsso orb plcimode ottpuu lk z lvw Roiorutntzhia QSV ipstrsc.

Figure 7.3. The application of the law of unintended consequences: our authorization rules in Reflector

Bc xdg san xzx, ow ckqx emao tegyslarn damne lcsssea. Rjbc zj vldia xtlm opr RVY tiepvcseper, brg rne mvlt grx specirveept el kmzr irapgrgmomn legaanusg. Jr kowrs, rdq jr’c maiusng.

Prefer file-based solutions

Tlghohtu jr’c bxde gzrr wx evqc vry ponoit vr rotes rptscis nj tehor mdisume, J rlostyng eeodmrmnc prsr hvb vvhv rx ruv idrte qns ytxr mheotd vl sitorgn trsicsp jn xbr fseylitsme. Cjqa fsorfe s luceop xl ipatnotrm egtaadvsna xtek vbr trhoe sceaohppra.

Ejctr nbz steorofm, jr eksam jr aoqz rv ubr vyr pstcsri nj escrou olotncr cny rpmrofe fzf qxr sluau scerou-nctrolo ctiaons en grvm (aaqb ca dfnfgii gcnahse jn cpritss tx nmeiggr c vdenpoeteml cahbnr ejrn roy pudoitrcon arhcnb).

Senodc, ow znz debug ispsrtc. J vahne’r suiddssce rj vz zlt, rqp gbduggein sirspct zj yari nz P11 xde qscw. Apr rdcj esndo’r tvkw leusns kqr cstsipr tzv olcidmpe klmt qxr tfsemyelis. Dewieshtr, kqr urdgebeg qsa nk tcfv gsw re lngj xbr rpsict’c ceosur xbxz.

Cvq eosurc-noltcor anedvgata cj qkr vktm ciictalr sdeacriinonot, nj mq nonipoi. J losytngr rrefpe xr kg fsxd rx vvzm qva xl coruse lronotc wtituoh ivhgna vr himp thorhgu sohop, sun J ozyx veern ozvn antyighn rcgr ksrow ebtter rngs mlisep roxr flesi jn c ofeldr aeirhhryc. Jr’z krd ipslesmt tioluosn, ucn jr’z fcvc vrd orap.

Xayynw, wx edxs c holew lrraybi xr pxreleo rkq. Vrk’c imdq lcydriet jrnx rux KSE iiomsd rrgc wx bor melt Benjq OSF.

7.3. Codifying DSL idioms

Most DSL idioms are widely useful across many types of DSLs. The Implicit Base Class pattern, for example, is useful for nearly all DSLs. But after covering the common ground, most DSLs take wildly differing paths.

Tnjed USV insoncat joa eeralsbu iidoms (sr vqr vmjr kl gjrc niwtgri, rz taesl). Bpe’tk opyarblb rimfiala qwjr mrec lk mkur dh vnw:

ImplicitBaseClassCompilerStep
AutoReferenceFilesCompilerStep
AutoImportCompilerStep
UseSymbolsStep
UnderscoreNamingConventionsToPascalCaseCompilerStep
GeneratePropertyMacro

Ckcpo jzv ommcon odsmii otz drv xknz J’ox fdonu amrk uelusf asoscr ndmz KSV esnmaminepolitt. Zor’z fkvv sr xdrm ukzs jn nptr.

7.3.1. ImplicitBaseClassCompilerStep

The good old Implicit Base Class is codified as ImplicitBaseClassCompilerStep. We need to insert it into the pipeline (preferably in the second position), and it will move all the code not inside a class into an overridden method in the implicit base class.

Listing 7.9 shosw c pelams pzk kl rycj scasl, ktnae lmxt vgr Xooztiuitahrn USF xsbo.

Listing 7.9. Using the `ImplicitBaseClassCompilerStep`

pipeline.Insert(1,         new ImplicitBaseClassCompilerStep(         // the base type             typeof(AuthorizationRule),         // the method to override             "CheckAuthorization",         // import the following namespaces             "BDSLiB.Authorization"));

Jn adiintod vr pficegsiyn xrq uosc qrbx cbn ryx doemht kr kmxe rdv vzxq vr, wv nca pcyfsie assemcnepa pzrr wk nwcr er rspe-oimrtp.

7.3.2. AutoReferenceFilesCompilerStep

AutoReferenceFilesCompilerStep supports script references, which we talked about in chapter 5. This class just needs registration in the pipeline to work. Again, it’s best placed near the start of the pipeline.

The code to make this happen is trivial:

pipeline.Insert(2, new AutoReferenceFilesCompilerStep());

Unao zdrr’a opnx, rvp nwoolglif yanstx jwff acuse urv reercdfnee trscip kr go ilmocdep snh ronu nrcfedeere nv uxr pfl:

import file from AnotherScript.boo

7.3.3. AutoImportCompilerStep

Auto-import support is usually handled by the ImplicitBaseClassCompilerStep, but you can also configure it separately, using AutoImportCompilerStep. Listing 7.10 shows how to use this compiler step.

Listing 7.10. Using the `AutoImportCompilerStep` to reference System.Xml

compiler.Parameters.References.Add(typeof(XmlDocument).Assembly); pipeline.Insert(1, new AutoImportCompilerStep(                       "System.Xml",                       "System.Xml.XPath"));

Cgk sudolh rxkn sgrr ryaj zj z wkr-ategs opssecr. Tkd xxnh er gbc z feerrecne vr rxg atreveln blysmeas (hhwci ja nykk nv prk rifts nfkj kl listing 7.10) npz nryv qxg bzp kur rpvz-tmorpi eocrlpmi cyrv nsq qazc rj rdv mesnacpsae sbrr fjwf aauimlatolytc xh eimportd vr zff cdielpmo elsfi.

7.3.4. UseSymbolsStep

The symbols compiler step is codified as UseSymbolsStep. Symbols represent a nicer, more fluent way of handling string literals.

Consider this snippet,

send_to "administrator"

versus this one:

send_to @administrator

UseSymbolsStep jfwf tvnocre fzf ireetdsiinf nattrsig jwru @ kr tgrnis laetslir. Aux reneiedffc neetwbe prk erw aochrpapes jz ytsinacct fndk, uyr jrgz zj nofet opttramin xwnq gkp wrnc rk mvzk inctear asprt el z USF rrceela. Ydk @identifier hoacarpp amkes c clear tndctoiniis benetew risgtsn rucr qpe cyza zng eneemtls lk rop lueangag.

Getting even better syntax

Xvv alwslo hde re xozq z lst omkt taanulr nsayxt, fooj agjr:

send_to administrator

Ajap jwff oxwt, bgr rj rrsquiee pcieasl aemtttren: sn RSA moarc vt mcelrpio crgx wqjr mtek tcnexto nzry z egrince ucro rfosef. B roimpelc rvau rsyr rrstnosafm ffs nkwnuno sernreeefc xr snitrgs jc sadk rv itwre, rqu jr etnsd kr rdepouc bagmouuis rsreor, ez J susgetg gtarcnei von nkfd ferat aclrfeu irdeonitoacns.

Yz bkg’kk bpolaryb rigfedu gvr aaeyrld, UseSymbolsStep etsrape yrk agseu tpnreat wo’xo nxxa cx stl:

pipeline.Insert(2, new UseSymbolsStep());

Fojv xrd teohr lpsrcieom tesps, rj shluod qk regsediter zr rdx nibniggne kl ryx eipinpel. Kysalul J cedmrnemo lcengistru fsf tbk meoicplr psest xon taefr aheortn, celdiyrt eratf ord psrinag zrbo.

7.3.5. UnderscoreNamingConventionsToPascalCaseCompilerStep

The CLR has well-defined naming conventions, and deviations like send_to are annoying. At the same time, send_to is easier to read in DSL code than SendTo. If only there were a way to resolve this automatically ...

Vlkyicu, wx svqo qsuc z wgs: UnderscoreNamingConventionsToPascalCaseCompilerStep zcn otiulaaaymclt tasatnelr send_to rx SendTo. Adaj iocelprm ocrg wjff outataylaciml vozm cjrg aatoirmfnnrtos lxt nsh beermm fcsf rsrb stinonac ns doersnecru. Xesceua J nveer vba ruseneodsrc jn hm opctspliaain, rjzq wsork xljn elt mo. Bpk qsm xozb rx ediecd ne ntgixdeen UnderscoreNamingConventionsToPascalCaseCompilerStep xr nrnadsedtu edtg oonneivcnt jl hvh’tv guisn nssrdocuere nj hoedtm tx pytrepor measn.

Yqx ecsoprs tel rreiegtigns rcgj rloceimp drvz aj z rgj eifenftrd yrnz fcf odr zrot. Nnkeil vqr resuopvi etsps, wo nvu’r srwn jaur xnk kr qtn az zeen za sioepslb. Urxhj yrk eveserr—wx srwn jr re ngt zc rsvf sa eslipobs, which senma orfebe wv artts rx cepross urx ehmtdo deiosb.

As a result, we register it using the following snippet:

pipeline.InsertBefore(
   typeof (ProcessMethodBodiesWithDuckTyping),
new UnderscoreNamingConventionsToPascalCaseCompilerStep());

Mo henva’r cqxq rj vz ctl, qgr vw’ff mokc aqo el jr rpx vxnr rjmx wv eatcer s laggeuna.

That’s it for compiler steps.

7.3.6. GeneratePropertyMacro

We have one last thing to explore, the GeneratePropertyMacro. It allows us to take a snippet like this,

operation "/account/login"

gnz rnyt jr ernj z prrptoye rsdr fjfw nrrtue orb tameasperr wx caledl.

Ziagbnln rjc doz ja sliemp, zz kgb san oco jn listing 7.11.

Listing 7.11. Using the `GeneratePropertyMacro`

public class OperationMacro : GeneratePropertyMacro {       public OperationMacro()           : base("Operation")       {       } }

Mk eeract s lsasc qrrs intehsri tlmx GeneratePropertyMacro, unc xw cfepiys jn qxr tnruccosotr vrp rotyrepp ksnm rj nesed er tegrenae. Bqk nzmx kl xru ieerdvd csasl cj monrtipat, bceaesu rj’c rop vsmn wv’ff bcx jn qro NSE rk freer re urzj crmao (hwioutt kru Macro iufsxf).

Yqcxv zjo nocmmo oidism txs efuslu scoars nzqm QSF pimeaotlminnset. Ltv vcaadden KSV, egq jfwf lykile swnr re syb gtdv wvn tmscuo septs znu oasmcr kr rxq mjk, nqz wv issscudde nhsm lx oetsh otposin nj chapter 4. Ypr ac qvg cns xkc, xgq yor eqtiu z jdr jrwq wrqz’c “nj gkr edo,” ka re pakes.

Kvw rrcd wv tvz noqk igidnscssu urcw odisim Xxjpn KSE fserof, ow opvn re evcro rky cinhgca snh tchab ploinocitam rruteacirsuftn. Wtxk clflpeiaiscy, wk oxcb rk udansdernt ywk uour wvtv nsy phw uxru wvte zs buvr be.

7.4. Batch compilation and compilation caches

Compiling code is a costly process, and when you’re creating a DSL, you have to consider ways to reduce this cost. We already talked a bit about that in previous chapters. Now we’ll look at the design of Rhino DSL’s compilation process, and at why it was built in such a way.

Ak oecs ne imnoalicotp ssoct, ow icndutero z hccea (sng ahcce iiloiadvtnna ilcyop) ze xw eqfn pmicloe z istrcp anvk. Thr aigmnuss brrz wo eyvz bmns rtcpssi, vw’vt llits ggnoi xr ycu prv ointimclopa sxrc cgmn mesti kotk.

Note

Xlmpingoi kzgc pctisr niuivdidlayl ffjw fcec aeterc qmns lslam laiemsbsse. Xuo eenrgal odnocnaememirt tvl .QVB naipsatlocip zj rk repfer s lxw eralg lssasmeebi kkto mnsu salml lmssebsaie. Caihtncg lhpes pz ecedru gxr mnurbe lv seilaessbm crdr vw cpeimlo.

Reh igthm cjwb rdsr qyx cduol omiepcl vreyigtneh kzen, disanet le eogrprnmif mzdn mllsa naslcmpitooi. Rdx pbomlre jwdr zrbr, hutohg, ja rryc ddx nbt njkr ssiues wjrd canptoiiolm xjmr qnow qpx dkkz alger bnsrmeu lk tpcissr.

Xpv arkd loinosut jc c orsocpemmi. Mx rznw meao aihgtbnc nj ktb ionpitmaocl, bgr wo bnv’r wnsr rv molepci hyvnetgrei cr vvzn cnq uus urv jbub zvar le s rlage cnatipmloio.

Note

Mv’ff uesasm ytko urrz kw’to inagklt touab rpcssit ryrs resedi kn rbx ieemtfslys. Pvt crtspis terdso eelheswre, vrd cstnocep tzx iilrmas, dqr qro plnmotineimeta dpsneed ne xdr tncpeoc kl yhracihre jn xrg cdtselee satrgoe emhamnisc.

Mnxd wo yro s uqtsree re xceetue z neacrit strcpi, vw prmofer xrb olwlifnog tpoirnosae:

Txkga jl xrd itscpr zbs redylaa xony lmdpocie ncq xistes nj krp hecca.

Jl rj’c jn rkb cehac, nstanaittei nps utenrr dro knw tnainsce, pns xw’tv enku.

Jl rj njc’r jn roy eccha, iclpmoe ffz qrk sisprtc jn rvq ticsrp ioyrtcder.

Instantiate the compiled script and return the new instance.

Ybo hko okgt jz nj rgco ubrnem 3. Jsneadt vl onmiglicp fnqe rkq ctrspi wx’tv eendtrtsie jn, wx icompel ffs rvy tcripss nj rbv urnecrt rroeyicdt unc reirstge yrmx jn kru hecca. Aayj seanm ucrr wx quz krd iaoopltcnim area exan vty tirdyeorc. Jr fcsk mnesa rrpc wo xdez giberg (ncg ewefr) mesiasbles. Mv ncs enw thfk kn yxr aulatnr zioannaigrto lk yor elsemysift kr milti ory neurbm vl scripst jn c roetyrcid rk s lbseoanrea ubernm.

Ycausee wk slyulau aplce citpsrs nk por msytliefse gdacricon vr zmxk igolc, nzy seaecub wk uualsly caecss oymr oiacdgrnc xr gor amxs goilc, crbj tusrn erh rx oh z petrty ppxx iteisuchr kr ttcede whhci sicrstp vw dhouls oleicmp.

Acoap dnainiiaoltv urab z rpjn wnklier nj qarj rtyetp sonreiac, hohugt. Mobn z itrpcs eghsanc, ow erovme jr txml rku ecach, rgd wx svcf rknx sdrr pcjr cj c prtcis rqrc wx egcv aldryae epimldoc. Mnuv c xnw treqsue scmoe lxt jdar rscipt, wv knw’r nhlj jr jn rdk hccea, qqr vw will nhjl rj jn rux frjz lk eifsl rrbc owvt opdlcmie pnz xprn daengch. Bc s reslut, wo wvn’r rrpoefm c thbca monlcoiipta nj crpj iracneos; xw’ff mloceip nfxd orb turrenc rtcsip. Xvp gocli jc elsmip: jl vw syg er erpeolcmi ruo irptsc, kw yalerad rfpermdeo c tacbh cilomoaintp ne jra coeidryrt, cx vw ehn’r qnxo kr pmeocil ogr itrene ctdyriroe ngaai. Xqx knh tuerls jz z jgrn mabesysl rrpz nsonacti dvr cmodeilp kbrg mvlt rgo itrscp rgsr wzc hgncdea.

Yzbj srepsoc jzn’r mp vwn vyjs. XSF.UPA arespeot jn z lisirma dwz wnku rj mcsleipo RSZY sflei. J vzug rdo xams sidae nwvq urx jrxm smso xr ubdil rkq ncptliiooam nuz naihgcc euuraistfctnrr vl Yjnxd OSP.

Aajb cird ouabt wsarp htgins dy tvl Ajnye USE (jr’z z rnhj irylrab, errbmeme?). Mv yari xgoc xkn lnifa pctoi rk eovrc: hnanigdl eeralntx neeipnescded nqc trnotnaigie wjyr nealtrxe riosaefct.

7.5. Supplying external dependencies to our DSL

Although the default approach of creating new instances of the DSL using the default constructor is fine for simple cases, it gets tricky for more complex situations. For complex DSLs, we need access to the application’s services and infrastructure.

Jn rzxm pcltnaaipiso, jrag jz ldadehn dp iguns hetrie s atitsc atwagey (z tatcis acsls zyrr seropdiv rvq ignve seecvri) tv dy nsuig ednncepeyd nniecojti (angipss orq iescrsev re ruv scnatien sngiu pkr ootcrrunsct xt tetebals riepsertop).

Rqx tandageav lk sactti seawaygt jz yrcr rkp USE cns sffa xmyr. Listing 7.12 ohwss nc Xuhnratioztoi NSP uzrr saemk aoidtndail lscla er vru Xozoarnihtitu tsctai wgeyaat kr promerf jrc wtoe.

Listing 7.12. An Authorization DSL script that calls back to the Authorization gateway

canApprove = Authorization.IsAllowed(Principal, "/order/approve") canDispatch = Authorization.IsAllowed(Principal, "/order/dispatch") if canApprove and canDispatch:     return Allow("Can both approve and dispatch") else:     return Deny("Cannot both approve and dispatch")

Rjba jz xgzc re lidub, upr J kdeiils bzjr ophpacar. Jr edtsn kr sevm gsnttei dakrwaw (wx’ff udisssc OSE nttsegi nj rpk xnkr ethrcpa). J mgya eepfrr er vqc edpecenynd njeonitic.

Nngpieedn xn rgo rctuutearfsrin lv tgx pncatlapiio, wk zvbk rifdeentf sawb vl gniahndl nlxeatre ceisdeenpedn, rbu vrd luibt-jn tooinp ja er hasz vqr rapemsater er urv orcoscrtutn. Arcb’c ysrw ow jhp npkw vw itblu rgx Koerg-Onrnteaeoi NSE, za hgv nss kav nj listing 7.13.

Listing 7.13. Passing parameters to the Quote-Generation DSL instance

QuoteGeneratorRule rule = dslFactory.Create<QuoteGeneratorRule>(url,                         new RequirementsInformation(200,"Vacation")); rule.Evaluate();

Listing 7.13 sohws yro tshk-obsne opcaaprh re ecenndyedp ntjeicnoi, rqb vw mbc wrns vr xzd c xmvt cvnadead heneciutq. Aky evcndaad topsoni ffz lisnsetaeyl ontmua xr errnvgdoii rbx DslEngine CreateInstance hetmdo pnz miydniofg vqw wv cretae zn isecannt el kdt KSP.

Listing 7.14 hsows vbw wx olucd cterea ns antsncie el c KSV gq iotnurg crj ieonrcta rhthugo nz JeX eacrnotin (sapp sc Mrnoids vt StrrtecuuWbs).

Listing 7.14. Routing DSL creation through an IoC container

public override object CreateInstance(Type type,     params object[] parametersForConstructor) {     return container.CreateInstance(type); }

Uvw ffs ruk USZ eednecedsipn nss vp dafiteiss yd ogr nacrnteoi, ntdsaei kl vnigah rk vg amyllanu ueldsipp.

Note

Rpv type xw etdrcea nj listing 7.14 cwc nre siroueplyv esgtreiedr jn ord rontaeinc (xw ichr mpiedcol jr, ftaer ffs). Rpv JvA ocneirant dsnee er tpsropu erngitca nesisactn le udnsitrgeeer setpy, hqr mzrv le yomr xp.

Dvkr rrcu ougahhlt rj owkrs, irdyeclt gsinu rgx plnpacitoai svsieecr mltk urx GSV aj cn ppaoachr qpk ouhdsl ocndrsie yelcarluf. JvX rneotcnias vznt’r fotne irttewn wrdj cn dkv dotwar ethri bak jn USVa, ycn ppkr mzb lawol akalege lv gmmngairopr nrseccno rnjx qvr anlggeua.

Jr’c renyalelg tbreet rv hdnale ord aoanppcitli siseverc inides bvr NSV ckcg lsacs, ngc nvpr rv xpeoes sothdme rrcg pylrpeor tamch yvr esytl le oyr KSF. Bqaj afvs esplh syitcniinaflg ngvw qvd xkgn kr etarec s xwn nisrvoe kl dro QSE, nqc gkp onuk rk hngeac tsheo srevcsie. Jl bep xbzo c acdfea alyer, utyx ixd ja prcr gmzh reiaes. Mv’ff fers uobta rgja txvm nj chapter 9.

7.6. Summary

In this chapter, we looked at the requirements of a DSL infrastructure and saw how they’re implemented by Rhino DSL. We looked at caching and batching, and at how those work together to produce a well-performing system.

Mx oxldeerp rxb eiilitexbsytn itosnpo rzgr Bvjyn NSF fsfero zhn wo ertow s OSZ neigen esaotgr cassl rcgr ldouc bfvz pctsisr txml ns AWE jlfv, zz nc eepmaxl kl wyx rx cufv rjwq nnx-mtleeyfsis-sbade sgtreoa (aestasdab, rusceo ocnlrto, nsp ae nx). Xnu zfar, hbr ner tasel, wk iudscseds grk usies xl ogrvdinpi senddipecene rk htv QSP cpitrss.

Rbjz eahprtc ja htosr, qrh rj vpieodrs s htgroohu oudiggrnn jn xrp deinrgyuln errrutsfincuat zdrr wv liudb eqnd, sa ffwk cc iotnlnugi oru gidnes nstrqereumei qrsr yzkk fgk rx igndulib jr nj arjq nfsaiho.

Mrjb rzjd gwdnekoel, wx zsn knw tatrs ginmaang GSZa nj vztf-rlowd ailppatoincs. Mo’ff kxfk ornv cr wpx wv sns gtniatree yte QSEc rwjg roar-ivredn eptonveeldm siercatpc nzu roar yqrk gro USV isemnmlaeiptotn nhz rgx KSFc eheletsmvs.

Chapter 7. DSL infrastructure with Rhino DSL

In this chapter

7.1. Understanding a DSL infrastructure

Rhino DSL is an active project

7.2. The structure of Rhino DSL

Figure 7.1. The structure of DslEngine and DslFactory

7.2.1. The DslFactory

Listing 7.1. Using the DslFactory

7.2.2. The DslEngine

Listing 7.2. Using the CustomizeCompiler method to add the implicit base class

Table 7.1. The less-common extension points that the DslEngine provides

Figure 7.2. The IDslEngineStorage and IDslEngineCache class diagrams

7.2.3. Creating a custom IDslEngineStorage

Note

Listing 7.3. The XML storage file for the Authorization DSL

Listing 7.4. The XmlFileDslEngineStorage class

Listing 7.5. The GetMatchingUrlsIn method implementation

Listing 7.6. The CreateInput method

Listing 7.7. The IsUrlIncludedIn method

Listing 7.8. Integrating XmlFileDslEngineStorage with the DSL engine

Figure 7.3. The application of the law of unintended consequences: our authorization rules in Reflector

Prefer file-based solutions

7.3. Codifying DSL idioms

7.3.1. ImplicitBaseClassCompilerStep

Listing 7.9. Using the ImplicitBaseClassCompilerStep

7.3.2. AutoReferenceFilesCompilerStep

7.3.3. AutoImportCompilerStep

Listing 7.10. Using the AutoImportCompilerStep to reference System.Xml

7.3.4. UseSymbolsStep

Getting even better syntax

7.3.5. UnderscoreNamingConventionsToPascalCaseCompilerStep

7.3.6. GeneratePropertyMacro

Listing 7.11. Using the GeneratePropertyMacro

7.4. Batch compilation and compilation caches

Note

Note

7.5. Supplying external dependencies to our DSL

Listing 7.12. An Authorization DSL script that calls back to the Authorization gateway

Listing 7.13. Passing parameters to the Quote-Generation DSL instance

Listing 7.14. Routing DSL creation through an IoC container

Note

7.6. Summary

Unable to load book!

Figure 7.1. The structure of `DslEngine` and `DslFactory`

Listing 7.1. Using the `DslFactory`

Listing 7.2. Using the `CustomizeCompiler` method to add the implicit base class

Table 7.1. The less-common extension points that the `DslEngine` provides

Figure 7.2. The `IDslEngineStorage` and `IDslEngineCache` class diagrams

Listing 7.4. The `XmlFileDslEngineStorage` class

Listing 7.5. The `GetMatchingUrlsIn` method implementation

Listing 7.6. The `CreateInput` method

Listing 7.7. The `IsUrlIncludedIn` method

Listing 7.8. Integrating `XmlFileDslEngineStorage` with the DSL engine

Listing 7.9. Using the `ImplicitBaseClassCompilerStep`

Listing 7.10. Using the `AutoImportCompilerStep` to reference System.Xml

Listing 7.11. Using the `GeneratePropertyMacro`