section-companion.tex

一个语言识别引擎

\chapter{The standard YARP companion utility}

We specify a standard command-line 
utility called ``yarp'' for performing a set of
useful operations for a YARP network.  
%
The functionality described here 
can be provided in other ways also, but
at a minimum this utility should be present on a YARP 2.0 
system.
%
We specify the utility by the user-facing functionality
it provides.  For any of the examples below, the word ``verbose'' 
inserted as the first argument should increase the level of 
detail at which the operation of the utility and problems
encountered is described.


\newusage{}
\usage{yarp}
%
This lists a human-readable summary of the 
ways the utility can be used.  Example output:

\begin{code}
here are ways to use this program:
  <this program> read /name
  <this program> write /name [/target]
  <this program> connect /source /target [carrier]
     carrier can be: tcp udp mcast text
  <this program> disconnect /source /target
  <this program> server
  <this program> where
  <this program> version
  <this program> name {arguments}
\end{code}


\newusage{}
\usage{yarp server}
\usage{yarp server SOCKETPORT}
\usage{yarp server IP SOCKETPORT}
%
This starts a name server running on the current machine, optionally
specifying the socket-port to listen to (default whatever was used in
the previous invocation, as recorded in a configuration file, or 10000
if this is the first time to run).
%
Also, the IP by which the name server should be identified can
optionally be specified (default is a fairly random choice of
the IPs associated with the current machine).

\newusage{}
\usage{yarp where}
%
This will report where the name server is believed to be running,
and the location of the configuration file used to determine that.
Example output:

\begin{code}
Name server is available at ip 5.255.112.225 port 10000
This is configured in file /home/paulfitz/.yarp/conf/namer.conf
You can change the directory where this configuration file is stored
with the YARP\_ROOT environment variable.
\end{code}

\newusage{}
\usage{yarp version}
%
This will report on the yarp version available.  Example:

\begin{code}
YARP network version 2.0
\end{code}

\newusage{}
\usage{yarp name COMMAND $ARG_1$ $ARG_2$ \ldots}
%
This will send the given command and arguments to the name server
using the YARP name server protocol, and report the results.
See Section~\ref{sect:name-protocol}.
%
%Equivalent to the telnet examples given in Section XXX, except the
%``NAME\_SERVER'' prefix is added automatically to the message send to
%the name server.

\newusage{}
\usage{yarp read PORT}
%
This will create an input port of the specified name.  It will
then loop, 
reading ``yarp bottles'' (a simple serialized list) and prints their content
to standard output.  This simple utility is intended for use in testing, or
getting familiar with using YARP.

\newusage{}
\usage{yarp write PORT}
%
This will create an output port of the specified name.  It will then
loop, reading from standard input and writing yarp bottles..
Optionally, a list of input ports to connect to automatically can be
appended to the command.  This simple utility is intended for use in
testing, or getting familiar with using YARP.

\newusage{}
\usage{yarp connect OUTPUT\_PORT INPUT\_PORT}
\usage{yarp connect OUTPUT\_PORT INPUT\_PORT CARRIER}
%
This will request the specified output port to send its output in 
future to the specified input port.
Optionally, the carrier to be used can be added as an extra argument
(e.g. tcp, udp, mcast, ...).

\newusage{}
\usage{yarp disconnect OUTPUT\_PORT INPUT\_PORT}
%
This will request the specified output port to cease sending its output to
the specified input port.

Appendix \ref{sect:using-utility} has a user guide to getting started
with the YARP network companion utility.