Class: Ukiryu::Shell::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/ukiryu/shell/base.rb

Overview

Base class for shell implementations

Each shell implementation must provide:

  • SHELL_NAME: Symbol identifying the shell

  • PLATFORM: Symbol for platform grouping (:unix, :windows, :powershell)

  • EXECUTABLE: Default executable path/name

  • name: Instance method returning the shell name (for compatibility)

Each shell implementation must provide:

  • escape(string): Escape a string for this shell

  • quote(string): Quote an argument for this shell

  • format_path(path): Format a file path for this shell

  • env_var(name): Format an environment variable reference

  • join(executable, *args): Join executable and arguments into a command line

Each shell class also provides:

  • detect_alias(command_name): Detect if a command is a shell alias

Direct Known Subclasses

Cmd, PowerShell, Tcsh, UnixBase

Constant Summary collapse

SHELL_NAME =

Symbol identifying the shell (override in subclass)

nil
PLATFORM =

Platform grouping (override in subclass)

nil
EXECUTABLE =

Default executable path (override in subclass)

nil
WHITESPACE_PATTERN =

Pre-compiled regex patterns for performance

/\s/.freeze
SPECIAL_CHARS_PATTERN = 
/[\s&*()\[\]{}|;<>?`~!@%"]/.freeze

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.detect_alias(_command_name) ⇒ Hash?

Detect if a command is a shell alias

Returns alias information if the command is an alias, nil otherwise. Subclasses should override to provide shell-specific alias detection.

Parameters:

  • command_name (String) —

    the command to check

Returns:

  • (Hash, nil) —

    “…”, target: “…” or nil if not an alias



43
44
45
46
 
# File 'lib/ukiryu/shell/base.rb', line 43

def self.detect_alias(_command_name)
  # Default implementation - no alias detection
  nil
end

Instance Method Details

#capabilities ⇒ Hash{Symbol => Object}

Get shell capabilities

Defines what features and environment behaviors this shell supports. Subclasses should override to customize capabilities.

Parameters:

  • capabilities (Hash) —

    a customizable set of options

Returns:

  • (Hash{Symbol => Object}) —

    capability flags and values



57
58
59
60
61
62
63
 
# File 'lib/ukiryu/shell/base.rb', line 57

def capabilities
  {
    supports_display: true,
    supports_ansi_colors: true,
    encoding: Encoding::UTF_8
  }
end

#encoding ⇒ Encoding

Get the shell’s output encoding

Returns:

  • (Encoding) —

    the encoding for shell output



76
77
78
 
# File 'lib/ukiryu/shell/base.rb', line 76

def encoding
  capabilities[:encoding]
end

#env_var(name) ⇒ String

Format an environment variable reference

Parameters:

  • name (String) —

    the variable name

Returns:

  • (String) —

    the formatted reference

Raises:

  • (NotImplementedError) 


132
133
134
 
# File 'lib/ukiryu/shell/base.rb', line 132

def env_var(name)
  raise NotImplementedError, "#{self.class} must implement #env_var"
end

#environment_to_h(env) ⇒ Hash

Convert Environment to Hash for Open3

This is the ONLY place where Environment should be converted to Hash. All Shell subclasses must use this method before calling Open3.

Parameters:

  • env (Environment, Hash) —

    the environment (Environment or legacy Hash)

Returns:

  • (Hash) —

    environment variables for Open3



198
199
200
 
# File 'lib/ukiryu/shell/base.rb', line 198

def environment_to_h(env)
  env.is_a?(Environment) ? env.to_h : env
end

#escape(string) ⇒ String

Escape a string for this shell

Parameters:

  • string (String) —

    the string to escape

Returns:

  • (String) —

    the escaped string

Raises:

  • (NotImplementedError) 


91
92
93
 
# File 'lib/ukiryu/shell/base.rb', line 91

def escape(string)
  raise NotImplementedError, "#{self.class} must implement #escape"
end

#execute_command(executable, args, env, timeout, cwd = nil) ⇒ Hash

Execute a command using this shell

This method provides OOP encapsulation of shell-specific command execution. Each shell subclass implements its own execution strategy. The Environment object is stored and converted to Hash only at Open3 call site.

Parameters:

  • executable (String) —

    the executable path

  • args (Array<String>) —

    command arguments

  • env (Environment) —

    environment variables (converted to Hash at Open3 site)

  • timeout (Integer) —

    timeout in seconds

  • cwd (String, nil) (defaults to: nil) —

    working directory (nil for current directory)

Returns:

  • (Hash) —

    execution result with :status, :stdout, :stderr keys

Raises:

  • (Timeout::Error) —

    if command times out



173
174
175
 
# File 'lib/ukiryu/shell/base.rb', line 173

def execute_command(executable, args, env, timeout, cwd = nil)
  raise NotImplementedError, "#{self.class} must implement #execute_command"
end

#execute_command_with_stdin(executable, args, env, timeout, cwd, stdin_data) ⇒ Hash

Execute a command with stdin input using this shell

Parameters:

  • executable (String) —

    the executable path

  • args (Array<String>) —

    command arguments

  • env (Environment) —

    environment variables (converted to Hash at Open3 site)

  • timeout (Integer) —

    timeout in seconds

  • cwd (String, nil) —

    working directory (nil for current directory)

  • stdin_data (String, IO) —

    stdin input data

Returns:

  • (Hash) —

    execution result with :status, :stdout, :stderr keys

Raises:

  • (Timeout::Error) —

    if command times out



187
188
189
 
# File 'lib/ukiryu/shell/base.rb', line 187

def execute_command_with_stdin(executable, args, env, timeout, cwd, stdin_data)
  raise NotImplementedError, "#{self.class} must implement #execute_command_with_stdin"
end

#format_environment(env_vars) ⇒ Hash

Format environment variables for command execution

Parameters:

  • env_vars (Hash) —

    environment variables to set

Returns:

  • (Hash) —

    formatted environment variables



149
150
151
 
# File 'lib/ukiryu/shell/base.rb', line 149

def format_environment(env_vars)
  env_vars
end

#format_path(path) ⇒ String

Format a file path for this shell

Parameters:

  • path (String) —

    the file path

Returns:

  • (String) —

    the formatted path



124
125
126
 
# File 'lib/ukiryu/shell/base.rb', line 124

def format_path(path)
  path
end

#headless_environment ⇒ Hash

Get headless environment variables (e.g., DISPLAY=“” for Unix)

Returns:

  • (Hash) —

    environment variables for headless operation



156
157
158
 
# File 'lib/ukiryu/shell/base.rb', line 156

def headless_environment
  {}
end

#join(executable, *args) ⇒ String

Join executable and arguments into a command line

Parameters:

  • executable (String) —

    the executable path

  • args (Array<String>) —

    the arguments

Returns:

  • (String) —

    the complete command line

Raises:

  • (NotImplementedError) 


141
142
143
 
# File 'lib/ukiryu/shell/base.rb', line 141

def join(executable, *args)
  raise NotImplementedError, "#{self.class} must implement #join"
end

#name ⇒ Symbol

Identify the shell

Returns:

  • (Symbol) —

    the shell name

Raises:

  • (NotImplementedError) 


83
84
85
 
# File 'lib/ukiryu/shell/base.rb', line 83

def name
  raise NotImplementedError, "#{self.class} must implement #name"
end

#needs_quoting?(string) ⇒ Boolean

Check if a string needs quoting Strings with spaces, special chars, or empty strings need quoting

Parameters:

  • string (String) —

    the string to check

Returns:

  • (Boolean) —

    true if quoting is needed



100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/ukiryu/shell/base.rb', line 100

def needs_quoting?(string)
  str = string.to_s
  # Empty strings need quoting
  return true if str.empty?
  # Strings with whitespace need quoting (use pre-compiled pattern)
  return true if str =~ WHITESPACE_PATTERN
  # Strings with shell special characters need quoting (use pre-compiled pattern)
  return true if str =~ SPECIAL_CHARS_PATTERN

  false
end

#quote(string) ⇒ String

Quote an argument for this shell

Parameters:

  • string (String) —

    the string to quote

Returns:

  • (String) —

    the quoted string

Raises:

  • (NotImplementedError) 


116
117
118
 
# File 'lib/ukiryu/shell/base.rb', line 116

def quote(string)
  raise NotImplementedError, "#{self.class} must implement #quote"
end

#supports?(capability) ⇒ Boolean

Check if shell supports a specific capability

Parameters:

  • capability (Symbol) —

    the capability to check

Returns:

  • (Boolean) —

    true if the capability is supported



69
70
71
 
# File 'lib/ukiryu/shell/base.rb', line 69

def supports?(capability)
  capabilities.key?(capability) && capabilities[capability]
end