<?xml version="1.0"?>

<!--
	description:

		"Echo Tasks"

	library: "Gobo Eiffel Ant"
	copyright: "Copyright (c) 2002, Sven Ehrke and others"
	license: "MIT License"
	date: "$Date$"
	revision: "$Revision$"
-->

<chapter xmlns="http://www.gobosoft.com/eiffel/gobo/documentation" id="echo_task">
<chapterinfo>
	<copyright>
		<year>2002-2005</year>
		<holder>Sven Ehrke</holder>
	</copyright>
	<author>
		<firstname>Sven</firstname><surname>Ehrke</surname>
	</author>
	<email>ericb@gobosoft.com</email>
	<date>7 July 2005</date>
</chapterinfo>

	<title>echo</title>

	<section id="echo_description">
		<title>Description</title>
		<para>
			Echo a message to stdout.
		</para>
	</section>

	<section id="echo_parameters">
		<title>Parameters</title>

		<variablelist>
			<varlistentry>
				<term>message</term>
				<listitem>
					<para><emphasis>Description: </emphasis>Message to be echoed</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>-</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>to_file</term>
				<listitem>
					<para><emphasis>Description: </emphasis>if specified this attribute defines the name of the file the message will be written to</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>valid filename</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>-</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>append</term>
				<listitem>
					<para><emphasis>Description: </emphasis>This attribute applies only if attribute 'to'file' was specified.
						If set to 'true' 'message' will be appended to the file. Otherwise the file will be overwritten with 'message'
					</para>
				</listitem>
				<listitem>
					<para><emphasis>Domain: </emphasis>Boolean (true|false)</para>
				</listitem>
				<listitem>
					<para><emphasis>Default: </emphasis>false</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</section>

	<section id="echo_specification">
		<title>RNG Specification</title>

		<programlisting><![CDATA[
<define name="echo">
  <element name="echo">
    <ref name="dir_if_unless"/>
    <choice>
      <text/>
      <attribute name="message"/>
    </choice>
    <optional>
      <attribute name="to_file"/>
      <optional>
        <attribute name="append"/>
      </optional>
    </optional>
  </element>
</define>
]]>
		</programlisting>
	</section>

	<section id="echo_examples">
		<title>Examples</title>

		<programlisting><![CDATA[
  <echo message="Hello world!"/>
  <echo message="Hello world!" to_file="messages.txt"/>
  <echo message="Hello world again!" to_file="messages.txt" append="true"/>
  <echo>Hello from inside 'echo'</echo>
  <echo>Hello from inside 'echo'
  using more than one line</echo>
]]>
		</programlisting>
	</section>

</chapter>
