## org.das2.util.Expect

Provides similar functions as the Unix Expect tool.
There are two ways to create an Expect object: a constructor that takes an {@link InputStream} handle and {@link OutputStream} handle; or spawning a process by providing a command String.
The API is loosely based on Perl Expect library:
http://search.cpan.org/~rgiersig/Expect-1.15/Expect.pod
If you are not familiar with the Tcl version of Expect, take a look at:
http://oreilly.com/catalog/expect/chapter/ch03.html
Expect uses a thread to convert InputStream to a SelectableChannel; other than this, no multi-threading is used.
A call to expect() will block for at most timeout seconds. Expect is not designed to be thread-safe, in other words, do not call methods of the same Expect object in different threads.

## Expect( java.io.InputStream input, java.io.OutputStream output )

## before

String before the last match(if there was a match), updated after each expect() call

## match

String representing the last match(if there was a match), updated after each expect() call

## isSuccess

Whether the last match was successful, updated after each expect() call

## RETV_TIMEOUT

## RETV_EOF

## RETV_IOEXCEPTION

## byteToPrintableString

byteToPrintableString( byte b ) → String

### Parameters

b - a byte

### Returns:

java.lang.String
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## bytesToPrintableString

bytesToPrintableString( byte[] bytes ) → String

Static method used for convert byte array to string, each byte is converted to an ASCII character, if the byte represents a control character, it is replaced by a printable caret notation http://en.wikipedia.org/wiki/ASCII , or an escape code if possible.

### Parameters

bytes - bytes to be printed

### Returns:

String representation of the byte array
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## close

close( ) → void

The OutputStream passed to Expect constructor is closed; the InputStream is not closed (there is no need to close the InputStream).
It is suggested that this method be called after the InputStream has come to EOF. For example, when you connect through SSH, send an "exit" command first, and then call this method.
When this method is called, the thread which write to the sink of the pipe will end.

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## expect

expect( Object[] patterns ) → int

Convenience method, same as calling {@link #expect(int, Object...) expect(default_timeout, patterns)}

### Parameters

patterns - a java.lang.Object[]

### Returns:

an int
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## expect

expect( int timeout, Object[] patterns ) → int

Convenience method, internally it constructs a List{@literal } using the object array, and call {@link #expect(int, List) } using the List. The {@link String}s in the object array will be treated as literals; meanwhile {@link Pattern}s will be directly added to the List. If the array contains other objects, they will be converted by {@link #toString()} and then used as literal strings.

### Parameters

timeout - timeout in seconds
patterns - array of String regex, Pattern, or Object where toString() is called.

### Returns:

an int
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## expect

expect( int timeout, java.util.List list ) → int

Expect will wait for the input handle to produce one of the patterns in the list. If a match is found, this method returns immediately; otherwise, the methods waits for up to timeout seconds, then returns. If timeout is less than or equal to 0 Expect will check one time to see if the internal buffer contains the pattern.

### Parameters

timeout - timeout in seconds
list - List of Java {@link Pattern}s used for match the internal buffer obtained by reading the InputStream

### Returns:

position of the matched pattern within the list (starting from 0); or a negative number if there is an IOException, EOF or timeout
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## expectEOF

expectEOF( int timeout ) → int

Convenience method, internally it calls {@link #expect(int, List) expect(timeout, new ArrayList<Pattern>())}. Given an empty list, {@link #expect(int, List)} will not perform any regex matching, therefore the only conditions for it to return is EOF or timeout (or IOException). If EOF is detected, {@link #isSuccess} and {@link #before} are properly set.

### Parameters

timeout - an int

### Returns:

same as return value of {@link #expect(int, List)}
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## expectEOF

expectEOF( ) → int

Convenience method, same as calling {@link #expectEOF(int) expectEOF(default_timeout)}

### Returns:

same as return value of {@link #expect(int, List)}
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## expectEOFOrThrow

expectEOFOrThrow( int timeout ) → int

Throws checked exceptions when expectEOF was not successful.

### Parameters

timeout - timeout in seconds

### Returns:

same as return value of {@link #expect(int, List)}
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## expectEOFOrThrow

expectEOFOrThrow( ) → int

Convenience method, same as calling {@link #expectEOF(int) expectEOF(default_timeout)}

### Returns:

same as return value of {@link #expect(int, List)}
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## expectOrThrow

expectOrThrow( int timeout, Object[] patterns ) → int

This method calls {@link #expect(int, Object...) expect(timeout, patterns)}, and throws checked exceptions when expect was not successful. Useful when you want to simplify error handling: for example, when you send a series of commands to an SSH server, you expect a prompt after each send, however the server may die or the prompt may take forever to appear, you would want to skip the following commands if those occurred. In such a case this method will be handy.

### Parameters

timeout - an int
patterns - a java.lang.Object[]

### Returns:

same as {@link #expect(int, Object...) expect(timeout, patterns)}
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## expectOrThrow

expectOrThrow( Object[] patterns ) → int

Convenience method, same as calling {@link #expectOrThrow(int, Object...) expectOrThrow(default_timeout, patterns) }

### Parameters

patterns - a java.lang.Object[]

### Returns:

same as {@link #expect(int, Object...) expect(timeout, patterns)}
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## forwardInputStreamTo

forwardInputStreamTo( java.io.PrintStream duplicatedTo ) → void

While performing expect operations on the InputStream provided, duplicate the contents obtained from InputStream to a PrintStream (you can use System.err or System.out). DO NOT call this function while there are live Expect objects as this may cause the piping thread to end due to unsynchronized code; if you need this feature, add the following to both {@link #inputStreamToSelectableChannel(InputStream)} and {@link #forwardInputStreamTo(PrintStream)}:

     	synchronized(Expect.duplicatedTo) {...
     }

### Parameters

duplicatedTo - call with null if you want to turn off

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getDefault_timeout

getDefault_timeout( ) → int

### Returns:

int
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getProcess

getProcess( ) → java.lang.Process

### Returns:

the spawned process, if this {@link Expect} object is created by spawning a process
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isNotransfer

isNotransfer( ) → boolean

### Returns:

boolean
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## isRestart_timeout_upon_receive

isRestart_timeout_upon_receive( ) → boolean

### Returns:

boolean
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## printDebugInfo

printDebugInfo( ) → void

print internal debug information to stderr.

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## send

send( String str ) → void

### Parameters

str - Convenience method to send a string to output handle

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]
send( byte[] toWrite ) → void [view source]

## setDefault_timeout

setDefault_timeout( int default_timeout ) → void

### Parameters

default_timeout - an int

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## setNotransfer

setNotransfer( boolean notransfer ) → void

### Parameters

notransfer - a boolean

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## setRestart_timeout_upon_receive

setRestart_timeout_upon_receive( boolean restart_timeout_upon_receive ) → void

### Parameters

restart_timeout_upon_receive - a boolean

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## spawn

spawn( String command ) → org.das2.util.Expect

Creates an Expect object by spawning a command.
To Linux users, perhaps you need to use "bash -i" if you want to spawn Bash.
Note: error stream of the process is redirected to output stream.

### Parameters

command - a String

### Returns:

Expect object created using the input and output handles from the spawned process
[search for examples] [view on GitHub] [view on old javadoc] [view source]