/ 
Sidef-26.05
⭐ Starred 115 / Sidef::Types::Glob::Pipe

NAME

Sidef::Types::Glob::Pipe - Interface for creating and managing pipe handles

SYNOPSIS

# Create a pipe for reading command output
var pipe = Pipe("ls -la")
pipe.open_r(\var fh)
fh.each { |line|
    say line
}
fh.close

# Create a pipe for writing to a command
var pipe = Pipe("sort | uniq")
pipe.open_w(\var fh)
fh.say("banana")
fh.say("apple")
fh.say("banana")
fh.say("cherry")
fh.close

# Alternative: using open with mode
var pipe = Pipe("wc -l")
pipe.open('<', \var in_fh)   # read mode
# or
pipe.open('>', \var out_fh)  # write mode

DESCRIPTION

The Pipe class provides an interface for working with Unix-style pipes in Sidef. Pipes allow bidirectional communication between your Sidef program and external commands or processes, enabling data to flow from your program to a command (write mode) or from a command to your program (read mode).

This class wraps the underlying system pipe mechanisms and provides a clean, object-oriented interface for pipe operations.

INHERITS

Inherits methods from:

* Sidef::Object::Object

METHODS

new

Pipe.new(command)
Pipe(command)

Creates a new Pipe object for the specified command string.

Parameters:

  • command - The shell command to execute (String)

Returns: A new Pipe object

Example:

var pipe = Pipe("grep 'error' /var/log/syslog")
var pipe2 = Pipe.new("cat file.txt | sed 's/foo/bar/g'")

Note: The command is not executed until open, open_r, or open_w is called.

Aliases: call

command

pipe.command

Returns the command string associated with this Pipe object.

Returns: The command string (String)

Example:

var pipe = Pipe("ls -la")
say pipe.command          # prints: ls -la

open

pipe.open(mode, var_ref)

Opens the pipe in the specified mode and assigns the resulting filehandle to the variable reference provided.

Parameters:

  • mode - The opening mode: '<' for read, '>' for write (String)

  • var_ref - A reference to a variable that will receive the filehandle

Returns: The filehandle object

Example:

var pipe = Pipe("grep pattern file.txt")
pipe.open('<', \var fh)    # open for reading

var output_pipe = Pipe("sort")
output_pipe.open('>', \var out)  # open for writing

Note: The mode parameter follows Perl/Unix conventions: '<' or 'r' for read mode (input from command) '>' or 'w' for write mode (output to command)

open_r

pipe.open_r(var_ref)

Opens the pipe in read mode, allowing your program to read output from the command. This is equivalent to open('<', var_ref).

Parameters:

  • var_ref - A reference to a variable that will receive the filehandle

Returns: The filehandle object configured for reading

Example:

var pipe = Pipe("ps aux | grep sidef")
pipe.open_r(\var fh)

fh.each { |line|
    say "Process: #{line}"
}
fh.close

Use Case: Use this when you want to capture and process output from a shell command within your Sidef program.

Aliases: open_read

open_w

pipe.open_w(var_ref)

Opens the pipe in write mode, allowing your program to send data to the command's standard input. This is equivalent to open('', var_ref)>.

Parameters:

  • var_ref - A reference to a variable that will receive the filehandle

Returns: The filehandle object configured for writing

Example:

var pipe = Pipe("mail -s 'Report' user@example.com")
pipe.open_w(\var fh)

fh.say("This is the report content.")
fh.say("Generated at: #{Time.local}")
fh.close

Use Case: Use this when you want to pipe data from your Sidef program into another command for processing.

Aliases: open_write

to_s

pipe.to_s

Returns a string representation of the Pipe object, typically showing the command it encapsulates.

Returns: String representation of the Pipe object

Example:

var pipe = Pipe("echo 'hello'")
say pipe.to_s             # shows Pipe object info
say pipe.dump             # same output

Aliases: dump, to_str

USAGE EXAMPLES

Reading from a Pipe

# Execute a command and read its output line by line
var pipe = Pipe("find /etc -name '*.conf'")
pipe.open_r(\var fh)

var count = 0
fh.each { |line|
    say line.trim
    ++count
}
fh.close

say "Found #{count} configuration files"

Writing to a Pipe

# Send data to a command for processing
var data = %w(zebra apple mango banana kiwi)
var pipe = Pipe("sort -r")
pipe.open_w(\var fh)

data.each { |item|
    fh.say(item)
}
fh.close

Complex Pipeline

# Chain multiple commands together
var pipe = Pipe("ps aux | awk '{print $2, $11}' | sort -n")
pipe.open_r(\var fh)

say "PID\tCommand"
say "=" * 40
fh.each { |line|
    say line
}
fh.close

Error Handling

# Always check if pipe operations succeed
var pipe = Pipe("some-command")

try {
    pipe.open_r(\var fh)
    fh.each { |line| say line }
    fh.close
} catch {
    say "Error: #{_}"
}

COMPARISON WITH FILE OPERATIONS

While FileHandle deals with regular files on disk, Pipe works with commands and processes:

# File operations
var file = File("data.txt")
file.open_r(\var fh)
# reads from file

# Pipe operations
var pipe = Pipe("cat data.txt")
pipe.open_r(\var fh)
# reads from command output

The key difference: Pipes execute commands and stream data to/from them, while FileHandles access data stored in files.

TECHNICAL NOTES

  • Pipes use the underlying operating system's pipe mechanism

  • Commands are executed through the shell, so shell metacharacters are interpreted

  • Pipe handles should be closed when finished to avoid resource leaks

  • The command doesn't execute until the pipe is opened

  • Write operations are buffered; close the handle to ensure all data is flushed

PLATFORM CONSIDERATIONS

Pipe functionality depends on the underlying operating system:

  • Unix/Linux/macOS: Full support for pipes with shell command execution

  • Windows: Limited pipe support; some shell features may not work as expected

SEE ALSO

AUTHOR

Daniel Șuteu (trizen)

LICENSE

This module is free software; you can redistribute it and/or modify it under the same terms as Sidef itself.