Skip to content

Latest commit

 

History

History
294 lines (144 loc) · 5.15 KB

REFERENCE.md

File metadata and controls

294 lines (144 loc) · 5.15 KB

Reference

Table of Contents

Functions

  • pty::spawn: Spawns the specified command on a newly allocated pty

Data types

  • PTY::IO: The PTY::IO data type represents an IO-object to communicate via the PTY. An instance of PTY::IO class is created by the pty::spawn() funct

Functions

pty::spawn

Type: Ruby 4.x API

Spawns the specified command on a newly allocated pty.

NOTE: This function is designed to be used in a Bolt plan (not available in apply() block). See PTY::IO DataType documentation for more details.

pty::spawn(Array[String[1]] $cmd, Callable[PTY::IO] &$block)

Spawns the specified command on a newly allocated pty (block form).

Returns: Undef

Examples
Spawn /bin/sh and get the hostname
pty::spawn(['/bin/sh', '--norc']) |$pty| {
  $pty.puts('export PS1="pty::io$ "')
  $pty.read()
  $pty.set_expected_prompt(/\Rpty::io\$ /)
  $hostname = $pty.pwp('hostname').strip()
}
cmd

Data type: Array[String[1]]

The command to spawn.

&block

Data type: Callable[PTY::IO]

The code block, that is using PTY::IO object yielded to talk to the command executed.

pty::spawn(Array[String[1]] $cmd)

Spawns the specified command on a newly allocated pty (non-block form).

Returns: PTY::IO The PTY::IO object

Examples
Spawn /bin/sh and get the hostname
$pty = pty::spawn(['/bin/sh', '--norc'])
$pty.puts('export PS1="pty::io$ "')
$pty.read()
$pty.set_expected_prompt(/\Rpty::io\$ /)
$hostname = $pty.pwp('hostname').strip()
$pty.close()
cmd

Data type: Array[String[1]]

The command to spawn.

Data types

PTY::IO

The PTY::IO data type represents an IO-object to communicate via the PTY. An instance of PTY::IO class is created by the pty::spawn() function. In a block form this object is passed to the block as its first parameter. In a non-block form it is returned by the function. This data type is not expected to be created manually.

Functions

The following functions are available in the PTY::IO data type.

check

PTY::IO.check

Check if the process is alive.

Returns: Variant[Integer, Undef]

close

PTY::IO.close

Close streams and kill the process spawned.

Returns: Variant[Integer, Undef]

write

PTY::IO.write(param1)

Send a message as-is.

Returns: Integer

param1

Data type: String[1]

puts

PTY::IO.puts(param1)

Send a message with terminating line feed appended.

Returns: Undef

param1

Data type: String

read

PTY::IO.read(param1)

Read the input if any.

Returns: Variant[String, Undef]

param1

Data type: Struct[{'maxlen' => Optional[Integer[0]], 'timeout' => Optional[Variant[Integer[0], Float]]}]

set_expected_prompt

PTY::IO.set_expected_prompt(param1)

Set the prompt to implicitly expect by pwp() and pwp_until() methods.

Returns: Regexp

param1

Data type: Variant[Regexp, String]

expect

PTY::IO.expect(param1, param2)

Wait for a pattern to appear (or until timeout expires).

Returns: Variant[String, Undef]

param1

Data type: Variant[Regexp, String[1]]

param2

Data type: Struct[{'timeout' => Optional[Variant[Integer, Float]]}]

pwp

PTY::IO.pwp(param1, param2)

Send a message, wait for the prompt and return the text received.

Returns: Variant[String, Undef]

param1

Data type: String[1]

param2

Data type: Struct[{'timeout' => Optional[Variant[Integer, Float]], 'keep_prompt' => Optional[Boolean]}]

pwp_until

PTY::IO.pwp_until(param1, param2, param3)

Send the message, wait for the prompt, check for the pattern, repeat if not found.

Returns: Variant[String, Undef]

param1

Data type: String[1]

param2

Data type: Regexp

param3

Data type: Struct[{'interval' => Optional[Variant[Integer[0], Float]], 'limit' => Optional[Integer[0]], 'timeout' => Optional[Variant[Integer[0], Float]]}]

type_in

PTY::IO.type_in(param1)

Send a message by typing a char and waiting for it to be echoed back by console before typing a next one.

Returns: Variant[String, Undef]

param1

Data type: String[1]

set_raw

PTY::IO.set_raw

Switch the pty to raw mode.

Returns: Undef

set_cooked

PTY::IO.set_cooked

Switch the pty to 'cooked' mode (default mode usually).

Returns: Undef

set_echo

PTY::IO.set_echo(param1)

Enable/disable echo on the pty.

Returns: Boolean

param1

Data type: Boolean

set_debug

PTY::IO.set_debug(param1)

Enable/disable debug messages on stderr.

Returns: Boolean

param1

Data type: Boolean