Echo

The Echo language design was informed by these observations:

Echo was designed to provide application developers with a natural, direct way to express these pipelined processing chains. Echo contains commands for a rich set of filters and generators. Developers control the composition of the tasks and their order of execution simply by the commands' relative placement within an XML document, with leaf nodes sending their output toward containing elements (commands), which in turn may filter the data and send that output to their parents, upward towards the Echo document's root element and the Echo processor which invoked it.

Echo allows for the implementation of extremely fast and efficient processors:

An Echo Processor is any computer program, that when provided with an Echo script, produces output(s) that conform the rules for processing Echo Commands. Those rules are described in this specification.

An Echo processor transforms instances of an abstract data model (one that is based upon the XML Infoset) to other instances of that data model. Some of those transformations have side effects, such as writing to a file or port, or POSTing to an HTTP location.

An Echo script is a well-formed XML document that specifies how data represented in XML and programs that operate on that data are assembled to produce results. Echo scripts tell the Echo processor:

An Echo Processor operates with a content repository for obtaining and storing text and binary data files as well as XML documents.

All objects (files) in a processor's repository are associated with names. The names are organized into a recursive structure of named collections (or folders) analogous to a computer's file system. An important concept is the "item", which is the association of a name and a version with the folder (its parent property) and a specific XML document, text, or binary file or folder (its contents property).

<e:echo xmlns:e="http://namespaces.xmlecho.org/echo">
    <e:itemGet name="/src/docs/echo/processor.xml" />
</e:echo>

<section  xmlns="http://docbook.org/ns/docbook" xml:id="echo-processor">
  <title>Echo Processor</title>
  ...
</section>

Commands in Echo are expressed syntactically as XML Elements. An Echo processor exhibits specific behaviors for the Elements named here, and has a default behavior for all other elements. Any XML element, therefor, is treated by an Echo processor as a command (or command modifier) in the Echo language, and any well-formed XML document can be treated as an Echo script. The script is rooted at the document element.

An Echo processor needs to exist in a supporting infrastructure that provides it with:

a Server based Echo processor will also provide a repository for reading and writing named instances, and for associating those instances with metadata such as name, owner, permissions, etc.

Echo does not provide for user authentication, that is expected to be provided by another layer of the environment, such as a web server. An Echo processor does provide, however, information about the authenticated user to allow for Echo scripts to base the authorization.

Security rules for authentication and access control can be applied according to the users' role.

Every ECHO script can be thought of as a function; called with a given set of parameters, it produces an output. In the most common case, the inputs are bound to names as parameters in a context, and the output is XML.

Within an ECHO script, every element, whether in the ECHO namespace or otherwise, is either itself a function, or an ECHO modifier/commentary element. The simplest function is one which takes no parameters and produces a literal result.

<e:echo xmlns:e='http://namespaces.xmlecho.org/echo">
    <h2>Hello</h2>
</e:echo>
    

<h2>Hello</h2>

In the above example, an ECHO processor will treat the h2 element as a function which returns the literal results consisting of an element named "h2" and PCDATA contents of "Hello".

<e:echo xmlns:e='http://namespaces.xmlecho.org/echo">
    <e:paramSet>
       <e:param name="yourName">Annie</e:param>
    </e:paramSet> 
    <h2>Hello <e:paramRef refParamName="yourName" /></h2>
</e:echo>
    

<h2>Hello Annie</h2>

In this example, the h2 is again producing the literal output element "h2" but performs a function call on the ECHO command, e:paramRef to complete the value of h2's PCDATA contents. The e:param element within the e:paramSet declares that the script will make use of a parameter named "yourName" and gives it a default value.

Since: 1) every ECHO command is an XML element, 2) every content element in an ECHO script is a function, and 3) all ECHO functions produce XML, ECHO commands and non-ECHO elements can be nested and composed into sophisticated processing chains.

The Echo processor converts a request into a result by applying transformation rules. The transformation rules are applied at the data model level. Before the transformations are applied, the Echo request is parsed into an instance of the Echo XML data model.

Elements in the Echo namespace fall broadly into one of two categories:

An Echo processor performs the following (conceptual) operations on an Echo script, which results in a transformation of the script into a result.

Echo's context element binds one or more parameter names to values. The bindings can be expressed as either XML Attributes, or as nested children param or function Elements. Parameter values can be strings, elements or functions.

  <e:toString><e:quote><e:echo xmlns:e="http://namespaces.xmlecho.org/echo">
    <!-- gets the same document 6 times using different techniques for param binding -->
    
    <!-- one way -->
    <e:itemGet name="/test/myDoc.xml" />
    
    <!-- another way -->
    <e:itemGet>
      <e:context name="/test/myDoc.xml" />
    </e:itemGet>
    
    <!-- a third way lets me use non-legal XML attribute name for param name-->
    <e:itemGet>
      <e:context>
        <e:param name="name" value="/test/myDoc.xml"/>
      </e:context>
    </e:itemGet>
    
    <!-- a fourth way value is content of param -->
    <e:itemGet>
      <e:context>
        <e:param name="name">/test/myDoc.xml</e:param>
      </e:context>
    </e:itemGet>

    <!-- parameters are inherited from our ancestor or calling environment -->
    <e:echo>
      <e:context>
        <e:param name="name">/test/myDoc.xml</e:param>
      </e:context>
      <e:itemGet/>
    </e:echo>

    <!-- parameters are evaluated with a very simple expression language-->
    <e:echo>
      <e:context>
        <e:param name="prefix">/test/myDoc</e:param>
        <e:param name="suffix">xml</e:param>
      </e:context>

      <e:itemGet name="{$prefix}.{$suffix}" />
    </e:echo>
  </e:echo>

Provides a list of parameter names, and possibly default values, for context parameters which are expected to be referenced when the containing element is evaluated. In the case of xslt, the parameters are made available to the xslt transformation engine.

Provided to allow developer and/or user documentation to be embedded within ECHO documents. There are no constraints on the contents of this element.

Provided to allow arbitrary meta-data to be embedded within ECHO documents. There are no constraints on the contents of this element.

describe <title>Trim</title>

describe UserName.

describe Crypt.

describe Substring.

describe SubstringBefore.

describe SubstringAfter.

describe IndexOf.

describe LastIndexOf.

describe StartsWith.

describe EndsWith.

describe Contains.

describe Translate

describe Millis.

describe Validate.

describe FormatDate.

describe DeformatDate

describe Hash Function

Concatenates the string values of its arguments.

Returns true if the userID in the first argument is a member of the group identified by the second argument.

A string of characters enclosed in a pair of either single or double quotes.

describe IntegerValue.

Adds the number value of the two expressions.

returns the product of multiplying the number values of its two arguments.

returns the result of subtracting the number value of the second argument from the number value of the first argument.

Returns the result of dividing the number value of the first argument by the number value of the second argument.

Evaluates a user defined function

Some ECHO commands require a single content producing child element. echo can be used to group multiple elements and/or PCDATA within a single element. It can also be used to group context parameter bindings, parameter declarations and documentation. By convention, echo is commonly the outer-most element in an ECHO script.

The ECHO processor replaces the echo command in the result by copying any contained PCDATA to the output and recursively processing and transforming any child content elements.

Transformations are among the most common operations in a pipes and filters programming model, and XSLT is a powerful standard for specifying XML transformations. Echo request elements may invoke XSLT transformations as part of the transformations of their content, and the XSLT stylesheets may, through an XSLT extension element, invoke an Echo processor as part of their transformation.

Echo provides the xslt command to identify the stylesheet and content to transform

An Echo processor replaces the xslt command with the results of running an XSLT transformation over its last child content element. if there is only one child content element, it is treated as the source content to be transformed, and the stylesheet is located in the repository from the "name" and "path" context bindings. If there are two content elements, the first content element is treated as the xslt stylesheet for the transformation.

The paramSet modifier element, if present, specifies which parameters from the context will be provided to the XSLT transformation engine.

<e:xslt>
  <e:itemGet path="/demo" name="change.xsl"  />	
  <e:itemGet path="/demo" name="foo.xml"  />
</e:xslt>

<e:echo xmlns:e="http://namespaces.xmlecho.org/echo">
    
    <e:paramSet>
       <e:param name="yourName">Annie</e:param>
       <e:param name="yourElement">div</e:param>
    </e:paramSet> 

    <e:xslt>
       <e:paramSet>
          <e:param name="yourElement" />
       </e:paramSet> 
   
       <e:quote>
          <xsl:stylesheet 
               xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
             <xsl:param name="yourElement" />
             <xsl:template match="h2">
                <xsl:element name="{$yourElement}">
                   <xsl:value-of select="text()"/>
                </xsl:element> 
             </xsl:template>
          </xsl:stylesheet>
       </e:quote>

       <h2>Hello <e:paramRef refParamName="yourName"/></h2>

    </e:xslt>

</e:echo>
        

<div>Hello Annie</div>

Since ECHO sources and ECHO results are both instances of the data model, the results of evaluating ECHO may itself be treated as ECHO for evaluation. Used in conjunction with the itemGet command, above, this allows us to call ECHO scripts which are stored in the repository from within other ECHO scripts.

Evaluates the contents producing an intermediate result, then evaluates that intermediate result as an ECHO script. Replacement happens in the following steps:

This has the effect that the result of transforming an ECHO request should itself be treated as a request and transformed

<e:echo xmlns:e="http://namespaces.xmlecho.org/echo">

    <e:paramSet>
    <e:param name="myName">Hector</e:param>
    <e:param name="myElement">h1</e:param>
    </e:paramSet> 
    
    <e:eval yourName="{$myName}" yourElement="{$myElement}">
    <e:itemGet name="/demo/run-map.echo" />
    </e:eval>
    </e:echo>
    

<h1>Hello Hector</h1>

Normal Echo processing can be disabled through the quote command. This allows Elements in the Echo namespace to be copied to the output without interpretation and without attribute expression evaluation.

The Echo processor replaces with the quote command with a literal copy of its single content element with no transformations performed.

<e:echo xmlns:e="http://namespaces.xmlecho.org/echo" xmlns="">
   <e:quote userHome="jenny" userName="Jennifer">
      <e:xslt xmlns:e="http://namespaces.xmlecho.org/echo">
         <e:itemGet path="/user/{$userHome}" name="jenny.xsl" />
         <h1>hello <e:paramRef refParamName="userName" /></h1>
      </e:xslt>
   </e:quote>
</e:echo>

<e:xslt xmlns:e="http://namespaces.xmlecho.org/echo">
   <e:itemGet path="/user/{$userHome}" name="jenny.xsl"/>
   <h1>hello <e:paramRef refParamName="userName"/></h1>
</e:xslt>

As with quote, Echo processing can be disabled through the noEval command. While, like quote, this allows most Echo commands to be copied to the output without interpretation, it differs in that as it copies, it does perform parameter substition through attribute value expression evaluation and through evaluation of Echo's paramRef command.

The noEval Echo command element is replaced with a literal copy of its single content element with only parameter substitution transformations performed.

<e:echo xmlns:e="http://namespaces.xmlecho.org/echo" xmlns="">
   <e:noEval userHome="jenny" userName="Jennifer">
      <e:xslt xmlns:e="http://namespaces.xmlecho.org/echo">
         <e:itemGet path="/user/{$userHome}" name="jenny.xsl" />
         <h1>hello <e:paramRef refParamName="userName" /></h1>
      </e:xslt>
   </e:noEval>
</e:echo>

<e:xslt xmlns:e="http://namespaces.xmlecho.org/echo">
   <e:itemGet path="/user/jenny" name="jenny.xsl"/>
   <h1>hello Jennifer</h1>
</e:xslt>

The element command produces an XML element with a specified name in the output.

Replaced with an element with a name constructed from "elementName" for the localName, and namespace from "elementNS" and a namespace map which assocates the namespace with the prefix in elementNSPrefix.

The contents of the generated element are replaced in the result by copying any PCDATA to the output and recursively processing and transforming any content elements.

An Echo processor may provide an XML representation of inputs to an Echo process invocation through this mechanism. This is a convenient method of passing HTTP GET and/or POST parameters to Echo scripts which service the request.

Replaced with the element bound to the context parameter "StandardXMLIn"

<e:echo xmlns:e="http://namespaces.xmlecho.org/echo" xmlns="">
    <e:standardXMLIn />
</e:echo>

<formXML>
    <parm name="yourName">
        <value>Jane</value>
    </parm>
    <parm name="yourElement">
        <value>baz</value>
    </parm>
</formXML>

<e:echo xmlns:e="http://namespaces.xmlecho.org/echo">
    <e:eval>
        <e:itemGet name="/demo/stdin-example.echo" />
        <foo><bar>...</bar></foo>
    <e:eval>
<e:echo>

<foo><bar>...</bar></foo>

Content can be dynamically generated from values bound to context parameters. The paramRef command places the value of a named parameter into the output.

Replaced with the value bound to the context parameter whose name matches the value bound to "refParamName", either a string or XML document.

<e:echo xmlns:e="http://namespaces.xmlecho.org/echo" xmlns="">
    <div>
        <e:echo p1="one">
            <p>p1: "<e:paramRef refParamName="p1" />"</p>
                <e:echo p1="two">
                   <p>p1: "<e:paramRef refParamName="p1" />"</p>
                   <e:echo p2="--{$p1}--">
                      <p>p1: "<e:paramRef refParamName="p1" />",
                         p2: "<e:paramRef refParamName="p2" />"</p>
                   </e:echo> 
                </e:echo>
            <p>p1: "<e:paramRef refParamName="p1" />"</p>
        </e:echo>
    </div>
</e:echo>

<div>
    <p>p1: "one"</p>
    <p>p1: "two"</p>
    <p>p1: "two",
       p2: "--two--"</p>
    <p>p1: "one"</p>
</div>

Silent evaluates its contents in exactly the same manner as echo, but returns no transformed results. This can be useful in evaluating some ECHO code for its side effects, such as inserting a document with itemPut, while discarding the output.

Replaced by an empty string.

Trim evaluates its contents in exactly the same manner as echo, but removes leading and trailing whitespace.

[ describe ]

[ describe ]

Evaluates its first child content element with the un-evaluated second child element bound to the context parameter "continuation".

wrap is replaced by the results of evaluating it's first child content producing element. Binds the second element to the special context parameter, "continuation", then evaluates the first.

During it's evaluation, the first element may request the second element's evaluation along with any new bindings of context parameters by invoking the continue element

<e:echo xmlns:e="http://namespaces.xmlecho.org/echo">

  <e:wrap>

    <!-- item 1 some ECHO to evaluate -->
    <e:xslt path="/homework/testje" name="map.xsl"/>    
      <e:continue/>
    </e:xslt>


    <!-- item 2 some ECHO to evaluate whenever we find "continue" in item 1 -->
    <e:xslt path="/homework/testje" name="fed-merge.xsl"/>     
      <e:itemEval path="/homework/testje" name="federate.echo"/>
    </e:xslt>
        
  </e:wrap>       

</e:echo>

Replaced by the results of evaluating the Echo command element bound to the special parameter "continuation".

continue can be used to evaluate an Echo procedure from within another procedure. Typically, the "continuation" procedure is created by the Echo command element, wrap.

Rather than including the all the content, stylesheets, and ECHO scripts in-line, we can share and re-use components by storing them as items in the repository. This enhances modularity. To obtain the content of an XML document from the ECHO processor's repository, use the itemGet command.

Replaced by an XML document identified by name and path or by itemID from the XML content repository managed by the ECHO processor.

<e:echo xmlns:e="http://namespaces.xmlecho.org/echo">

    <e:paramSet>
       <e:param name="yourName">Annie</e:param>
       <e:param name="yourElement">div</e:param>
    </e:paramSet> 

    <e:xslt>
        <e:paramSet>
           <e:param name="yourElement" />
        </e:paramSet> 
   
        <e:itemGet name="/demo/map-h2.xsl" />
        <h2>Hello <e:paramRef refParamName="yourName"/></h2>

    </e:xslt>

</e:echo>
        

Echo scripts often make use of other scripts in the Echo processor's repository by getting, then evaluating the script. One way to accomplish this is to place an itemGet element inside an evalelement.

<e:eval xmlns:e="http://namespaces.xmlecho.org/echo"><e:itemGet name="/test/foo.echo"/></e:eval>

A shorter way to accomplish this same effect is with itemEval, which performs both actions in a single command

<e:itemEval xmlns:e="http://namespaces.xmlecho.org/echo" name="/test/foo.echo"/>

Replaced by the results of processing the XML document identified by name and path or by itemID from the XML content repository as an Echo script.

We use itemList to get information about items in the ECHO processor's repository, and in the case of Folders, a listing of their contents.

<e:itemList name="/demo/examples" />

<folder id="11698" name="examples" revision="1" 
        current="yes" mimeType="FOLDER" docID="" 
        parent="762" status="1" ownerID="1" owningGroupID="1" 
        createTime="2003-10-26 08:34:58" lastUpdated="2003-10-26 08:34:58" 
        permissions="279" dirPath="/demo" read="true" write="true" exe="true">
    <doc id="9716" name="example3.echo" revision="1" current="yes" 
         mimeType="application/xml" docID="6755" parent="11698" 
         status="3" ownerID="1" owningGroupID="1" 
         createTime="2003-10-22 16:16:01" lastUpdated="2003-10-22 16:16:01" 
         permissions="279" dirPath="/demo/examples" 
         read="true" write="true" exe="true"/>
    <binary id="11699" name="ad_info.gif" revision="1" 
            current="yes" mimeType="image/gif" docID="" parent="11698" 
            status="1" ownerID="1" owningGroupID=