rush-shell 0.0.2

data/lib/rush/builtins/printf.rb

@@ -0,0 +1,39 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `printf format [arg ...]` — write the arguments under the control of the
+    # format, which is reused until the arguments are exhausted. Writes no
+    # trailing newline of its own. A present non-numeric argument to a numeric
+    # conversion is reported and treated as 0 (exit status 1).
+    class Printf < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        return usage if operands.empty?
+
+        text, ok = PrintfFormatter.new(operands.drop(1)).render(operands.first)
+        stdout.write(text)
+        report(ok)
+      end
+
+      private
+
+      sig { params(valid: T::Boolean).returns(Status) }
+      def report(valid)
+        return success if valid
+
+        stderr.puts('rush: printf: expected numeric value')
+        failure
+      end
+
+      sig { returns(Status) }
+      def usage
+        stderr.puts('rush: printf: usage: printf format [arguments]')
+        failure(2)
+      end
+    end
+  end
+end

data/lib/rush/builtins/printf_formatter.rb

@@ -0,0 +1,111 @@
+# typed: false
+# frozen_string_literal: true
+
+require 'strscan'
+
+module Rush
+  module Builtins
+    # Renders a printf template against its arguments: literal text (with
+    # backslash escapes), %% and the %[flags][width][.prec]conv conversions,
+    # cycling the template while arguments remain. Flags/width/precision defer to
+    # Ruby's format; numeric conversions coerce their argument (a present
+    # non-number is reported via the ok flag and treated as 0, a missing one as
+    # 0 silently). %b and octal escapes arrive in a later slice. Returns [text, ok].
+    class PrintfFormatter
+      NUMERIC = %w[d i o u x X].freeze
+
+      # Scans and walks one pass of a printf template: literal runs and resolved
+      # backslash escapes pass straight through, while each %conversion is handed
+      # back to the formatter to render against the next argument (double
+      # dispatch), so the scanning lives here and the formatting stays there.
+      class Template < StringScanner
+        ESCAPES = { '\\' => '\\', 'a' => "\a", 'b' => "\b", 'f' => "\f",
+                    'n' => "\n", 'r' => "\r", 't' => "\t", 'v' => "\v" }.freeze
+        ESCAPE_TABLE = EscapeTable.new(ESCAPES).freeze
+        SPEC = /\A([-+ #0]*\d*(?:\.\d+)?)([diouxXcs%])/
+
+        def emit(formatter)
+          out = +''
+          while (char = getch)
+            out << piece(formatter, char)
+          end
+          out
+        end
+
+        private
+
+        def piece(formatter, char)
+          return conversion(formatter) if char == '%'
+          return escape if char == '\\'
+
+          char
+        end
+
+        def conversion(formatter)
+          return '%' unless scan(SPEC)
+
+          flags, conv = captures
+          formatter.convert(T.must(flags), T.must(conv))
+        end
+
+        def escape
+          ESCAPE_TABLE.escape(getch)
+        end
+      end
+
+      def initialize(args)
+        @args = args
+        @cursor = 0
+        @ok = true
+      end
+
+      def render(template)
+        start = @cursor
+        text = Template.new(template).emit(self)
+        return [text, @ok] if @cursor == start || @cursor >= @args.size
+
+        rest, = render(template)
+        [text + rest, @ok]
+      end
+
+      # Render one %conversion (called back from Template): %% is a literal %, a
+      # numeric/char/string conversion consumes and formats the next argument.
+      def convert(flags, conv)
+        return '%' if conv == '%'
+
+        arg = take
+        return numeric(flags, conv, arg) if NUMERIC.include?(conv)
+        return format("%#{flags}s", first_char(arg)) if conv == 'c'
+
+        format("%#{flags}s", arg)
+      end
+
+      private
+
+      def numeric(flags, conv, arg)
+        format("%#{flags}#{conv}", to_int(arg))
+      end
+
+      def to_int(arg)
+        return 0 if arg.empty?
+
+        Integer(arg, exception: false) || invalid
+      end
+
+      def invalid
+        @ok = false
+        0
+      end
+
+      def take
+        arg = @args.fetch(@cursor, '')
+        @cursor += 1
+        arg
+      end
+
+      def first_char(arg)
+        arg.each_char.first
+      end
+    end
+  end
+end

data/lib/rush/builtins/pwd.rb

@@ -0,0 +1,17 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `pwd` — print the shell's logical working directory.
+    class Pwd < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        stdout.puts(executor.state.variables.pwd)
+        success
+      end
+    end
+  end
+end

data/lib/rush/builtins/read.rb

@@ -0,0 +1,93 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `read [-r] var ...` — read a logical line from stdin, split it on IFS and
+    # assign the fields to the named variables (the last variable takes the
+    # remainder). Repeated or clustered `-r` flags are accepted and `--` ends
+    # option parsing; any other option or an invalid variable name is a usage
+    # error. Without -r a backslash preserves the next character (shielding it
+    # from field splitting) and a trailing backslash continues onto the next
+    # physical line; with -r the line is taken verbatim. Returns non-zero when
+    # end of file arrives before a newline (assigning what was read).
+    class Read < Base
+      extend T::Sig
+
+      NAME = /\A[A-Za-z_]\w*\z/
+
+      sig { returns(Status) }
+      def call
+        parsed = parse_operands
+        return usage_error unless valid?(parsed)
+
+        raw, names = T.must(parsed)
+        read_and_assign(raw, names)
+      end
+
+      private
+
+      sig { returns(T.nilable([T::Boolean, T::Array[String]])) }
+      def parse_operands
+        args = operands.dup
+        mode = consume_options(args)
+        return if mode == :invalid
+
+        [mode == :raw, args]
+      end
+
+      sig { params(args: T::Array[String], mode: Symbol).returns(Symbol) }
+      def consume_options(args, mode: :cooked)
+        return mode unless option?(option = args.first)
+
+        args.shift
+        return mode if option == '--'
+        return :invalid unless option.to_s.delete_prefix('-').chars.all?('r')
+
+        consume_options(args, mode: :raw)
+      end
+
+      sig { params(arg: T.nilable(String)).returns(T::Boolean) }
+      def option?(arg)
+        !!arg&.start_with?('-') && arg != '-'
+      end
+
+      sig { params(parsed: T.nilable([T::Boolean, T::Array[String]])).returns(T::Boolean) }
+      def valid?(parsed)
+        !!parsed && parsed.last.any? && parsed.last.all? { |name| name.match?(NAME) }
+      end
+
+      sig { params(raw: T::Boolean, names: T::Array[String]).returns(Status) }
+      def read_and_assign(raw, names)
+        result = ReadInput.new(stdin, raw, pending: -> { executor.trap_runner.pending? }).call
+        return failure unless result
+
+        chars, complete = result
+        assign(chars, names)
+        complete ? success : failure
+      end
+
+      sig { params(chars: T::Array[Expansion::ReadChar], names: T::Array[String]).void }
+      def assign(chars, names)
+        fields = Expansion::ReadSplitter.new(ifs, names.size).split(chars)
+        names.each_with_index { |name, index| executor.state.variables.assign(name, fields.fetch(index)) }
+      end
+
+      sig { returns(T.nilable(String)) }
+      def ifs
+        executor.state.variables.get('IFS')
+      end
+
+      sig { returns(T.untyped) }
+      def stdin
+        io.get(0)
+      end
+
+      sig { returns(Status) }
+      def usage_error
+        stderr.puts('rush: read: arg count')
+        failure(2)
+      end
+    end
+  end
+end

data/lib/rush/builtins/read_input.rb

@@ -0,0 +1,146 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'io/wait'
+
+module Rush
+  module Builtins
+    # Reads one logical line for the `read` builtin from the given stream.
+    # Without -r a backslash escapes the next character (annotating it as
+    # protected from field splitting) and a trailing unescaped backslash joins
+    # the next physical line. `call` returns the annotated characters plus
+    # whether the line was complete — terminated by a newline before end of
+    # file, dash's read exit-status rule.
+    class ReadInput
+      extend T::Sig
+
+      # Adds caught-signal polling only to real IO; StringIO-backed reads stay
+      # direct and deterministic.
+      class LineReader
+        extend T::Sig
+
+        POLL_INTERVAL = 0.01
+
+        sig { params(stream: T.untyped, pending: T.proc.returns(T::Boolean)).void }
+        def initialize(stream, pending)
+          @stream = stream
+          @pending = pending
+        end
+
+        sig { returns(T.nilable(String)) }
+        def gets
+          stream = @stream
+          return stream.gets unless stream.is_a?(IO)
+
+          wait_for_line(stream)
+        end
+
+        private
+
+        sig { params(stream: IO).returns(T.nilable(String)) }
+        def wait_for_line(stream)
+          line = +''
+          catch(:physical_line) { loop { read_step(stream, line) } }
+        end
+
+        sig { params(stream: IO, line: String).void }
+        def read_step(stream, line)
+          throw(:interrupted, line) if @pending.call
+          char = next_char(stream)
+          throw(:physical_line, line.empty? ? nil : line) unless char
+          append_char(line, char) if char.is_a?(String)
+        end
+
+        sig { params(line: String, char: String).void }
+        def append_char(line, char)
+          line << char
+          throw(:physical_line, line) if char == "\n"
+        end
+
+        sig { params(stream: IO).returns(T.untyped) }
+        def next_char(stream)
+          return :wait_readable unless stream.wait_readable(POLL_INTERVAL)
+
+          read_char(stream)
+        end
+
+        sig { params(stream: IO).returns(T.untyped) }
+        def read_char(stream)
+          stream.read_nonblock(1)
+        rescue IO::WaitReadable
+          :wait_readable
+        rescue EOFError
+          nil
+        end
+      end
+
+      # A line whose backslash-pairs all match, leaving one lone trailing
+      # backslash: a line-continuation request.
+      CONTINUED = /\A(?:[^\\]|\\.)*\\\z/m
+
+      # One output character: an optional escaping backslash and the character.
+      PAIR = /(\\)?(.)/m
+
+      sig { params(stdin: T.untyped, raw: T::Boolean, pending: T.proc.returns(T::Boolean)).void }
+      def initialize(stdin, raw, pending: -> { false })
+        @reader = LineReader.new(stdin, pending)
+        @raw = raw
+        @chars = T.let([], T::Array[Expansion::ReadChar])
+        @complete = T.let(false, T::Boolean)
+      end
+
+      sig { returns(T.nilable([T::Array[Expansion::ReadChar], T::Boolean])) }
+      def call
+        partial = catch(:interrupted) do
+          gather
+          return [@chars, @complete]
+        end
+        partial_result(partial)
+      end
+
+      private
+
+      sig { params(partial: String).returns(T.nilable([T::Array[Expansion::ReadChar], T::Boolean])) }
+      def partial_result(partial)
+        decode(partial)
+        [@chars, false] unless @chars.empty?
+      end
+
+      sig { void }
+      def gather
+        line = @reader.gets
+        return @complete = false unless line
+
+        @complete = line.end_with?("\n")
+        gather if decode(line.delete_suffix("\n"))
+      end
+
+      # Appends the line's annotated characters; true means a continuation is
+      # pending and the next physical line belongs to this logical one.
+      sig { params(text: String).returns(T::Boolean) }
+      def decode(text)
+        return cook(text) unless @raw
+
+        verbatim(text)
+        false
+      end
+
+      sig { params(text: String).void }
+      def verbatim(text)
+        text.each_char { |char| @chars << [char, false] }
+      end
+
+      # A continuation leaves a zero-width escaped joint (['', true]) where the
+      # lines meet: dash's region boundary, which ends a whitespace-delimiter
+      # run in the splitter without contributing a character.
+      sig { params(text: String).returns(T::Boolean) }
+      def cook(text)
+        pending = text.match?(CONTINUED)
+        body = pending ? T.must(text[0..-2]) : text
+        body.scan(PAIR) { |escape, char| @chars << [T.must(char), escape == '\\'] }
+        (@chars << ['', true]) if pending
+        pending
+      end
+    end
+  end
+end

data/lib/rush/builtins/readonly.rb

@@ -0,0 +1,20 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `readonly name[=value] ...` — mark each name read only, so a later
+    # assignment or unset aborts (ReadonlyError); see Declare for the shared
+    # engine. (The `-p` listing form arrives with the variable-printing slice.)
+    class Readonly < Declare
+      extend T::Sig
+
+      private
+
+      sig { params(operand: String).void }
+      def declare(operand)
+        executor.state.variables.readonly_operand(operand)
+      end
+    end
+  end
+end

data/lib/rush/builtins/registry.rb

@@ -0,0 +1,36 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # O(1) name -> builtin class lookup, populated by Builtins.default_registry.
+    class Registry
+      extend T::Sig
+
+      sig { void }
+      def initialize
+        @builtins = {}
+      end
+
+      sig { params(name: String, klass: T.class_of(Base)).void }
+      def register(name, klass)
+        @builtins[name] = klass
+      end
+
+      sig { params(name: String).returns(T.class_of(Base)) }
+      def fetch(name)
+        @builtins.fetch(name)
+      end
+
+      sig { params(name: T.nilable(String)).returns(T.nilable(T.class_of(Base))) }
+      def lookup(name)
+        @builtins[name]
+      end
+
+      sig { params(name: T.nilable(String)).returns(T::Boolean) }
+      def key?(name)
+        @builtins.key?(name)
+      end
+    end
+  end
+end

data/lib/rush/builtins/return_.rb

@@ -0,0 +1,24 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `return [n]` — return from the current function with status n (default: the
+    # last command's status). A non-numeric n is a special-builtin error.
+    class Return < Base
+      extend T::Sig
+
+      sig { returns(T.noreturn) }
+      def call
+        raise ReturnSignal, code
+      end
+
+      private
+
+      sig { returns(Integer) }
+      def code
+        operands.first ? numeric_operand(operands.fetch(0)) : executor.state.last_status.exitstatus
+      end
+    end
+  end
+end

data/lib/rush/builtins/set.rb

@@ -0,0 +1,101 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `set [-/+ options] [--] [arg ...]` — toggle shell options (-x/+x and the
+    # `-o name`/`+o name` long form) and, when operands follow (or after `--`),
+    # replace the positional parameters. With no operands the parameters are left
+    # unchanged; an unknown option is ignored. A bare trailing `-o` writes the
+    # current settings table, a bare `+o` the re-input form (POSIX XCU set).
+    # Options: -a/allexport, -C/noclobber, -e/errexit, -n/noexec, -u/nounset,
+    # -x/xtrace, -f/noglob, -v/verbose, pipefail.
+    class Set < Base
+      extend T::Sig
+
+      OPTIONS = Options::LETTERS
+      LONG = Options::LONG
+
+      sig { returns(Status) }
+      def call
+        rest = strip_options(operands)
+        executor.state.positional.replace(rest) if rest
+        success
+      end
+
+      private
+
+      sig { params(args: T::Array[String]).returns(T.nilable(T::Array[String])) }
+      def strip_options(args)
+        return if args.empty?
+
+        positionals(args, consume_options(args))
+      end
+
+      sig { params(args: T::Array[String]).returns(Integer) }
+      def consume_options(args)
+        index = 0
+        while (cluster = OptionCluster.parse(args[index]))
+          index += advance(cluster, args, index)
+        end
+        index
+      end
+
+      sig { params(cluster: OptionCluster, args: T::Array[String], index: Integer).returns(Integer) }
+      def advance(cluster, args, index)
+        return apply_long(cluster.sign, args[index + 1]) if cluster.letters.join == 'o'
+
+        apply(cluster)
+        1
+      end
+
+      sig { params(args: T::Array[String], index: Integer).returns(T.nilable(T::Array[String])) }
+      def positionals(args, index)
+        return if index == args.size
+
+        args[index] == '--' ? args.drop(index + 1) : args.drop(index)
+      end
+
+      sig { params(cluster: OptionCluster).void }
+      def apply(cluster)
+        cluster.each_letter { |char, sign| toggle(OPTIONS.fetch(char, nil), sign) }
+      end
+
+      # With a name, toggle that option; bare `set -o` prints the option
+      # table (format follows dash), bare `set +o` the lines that re-create
+      # the settings when re-input (POSIX XCU set).
+      sig { params(sign: T.nilable(String), name: T.nilable(String)).returns(Integer) }
+      def apply_long(sign, name)
+        return toggle_long(sign, name) if name
+
+        options = executor.state.options
+        print_lines(sign == '-' ? ['Current option settings', *options.settings_rows] : options.reinput_lines)
+      end
+
+      sig { params(sign: T.nilable(String), name: String).returns(Integer) }
+      def toggle_long(sign, name)
+        toggle(LONG.fetch(name, nil), sign)
+        2
+      end
+
+      # Prints a listing and consumes just the bare -o/+o flag itself.
+      sig { params(lines: T::Array[String]).returns(Integer) }
+      def print_lines(lines)
+        lines.each { |line| stdout.puts(line) }
+        1
+      end
+
+      sig { params(option: T.nilable(Symbol), sign: T.nilable(String)).void }
+      def toggle(option, sign)
+        return unless option
+
+        enabled = sign == '-'
+        # Monitor carries side effects (SIGTSTP disposition, tty check) and can
+        # refuse, so it routes through the job-control policy, not bare state.
+        return executor.state.set_option(option, enabled) unless option == :monitor
+
+        enabled ? executor.job_control.enable(stderr) : executor.job_control.disable
+      end
+    end
+  end
+end

data/lib/rush/builtins/shift.rb

@@ -0,0 +1,35 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `shift [n]` — discard the first n positional parameters (default 1) and
+    # renumber the rest. As a special builtin, two errors abort a non-interactive
+    # shell with status 2 (BuiltinError, firing the EXIT trap), matching dash: a
+    # non-numeric / negative operand ("Illegal number"), and asking to shift more
+    # than $# ("can't shift that many"). Extra operands past the first are ignored.
+    class Shift < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        raise BuiltinError, "shift: can't shift that many" if count > state.positional.size
+
+        state.positional.shift(count)
+        success
+      end
+
+      private
+
+      sig { returns(ShellState) }
+      def state
+        executor.state
+      end
+
+      sig { returns(Integer) }
+      def count
+        operands.empty? ? 1 : numeric_operand(T.must(operands.first))
+      end
+    end
+  end
+end

data/lib/rush/builtins/test_.rb

@@ -0,0 +1,48 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # `test EXPR` / `[ EXPR ]` — evaluate a conditional expression, returning
+    # success (0) when true and failure (1) when false. A malformed expression
+    # is reported on stderr with exit status 2. Invoked as `[`, the expression
+    # must be terminated by a closing `]`.
+    class Test < Base
+      extend T::Sig
+
+      sig { returns(Status) }
+      def call
+        evaluate(bracketed? ? without_close(operands) : operands)
+      rescue TestError => e
+        report(e.message)
+      end
+
+      private
+
+      sig { returns(T::Boolean) }
+      def bracketed?
+        argv.first == '['
+      end
+
+      sig { params(ops: T::Array[String]).returns(T::Array[String]) }
+      def without_close(ops)
+        *body, close = ops
+        raise TestError, "missing `]'" unless close == ']'
+
+        body
+      end
+
+      sig { params(ops: T::Array[String]).returns(Status) }
+      def evaluate(ops)
+        context = TestContext.new(executor.system, FdOperand.new(io))
+        TestExpr.new(ops, context).true? ? success : failure
+      end
+
+      sig { params(message: String).returns(Status) }
+      def report(message)
+        stderr.puts("rush: #{argv.first}: #{message}")
+        failure(2)
+      end
+    end
+  end
+end

data/lib/rush/builtins/test_context.rb

@@ -0,0 +1,24 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  module Builtins
+    # The impure inputs to one test/[ evaluation: the filesystem port plus the
+    # resolver that projects shell-level fd bindings onto unary operands.
+    class TestContext
+      extend T::Sig
+
+      sig { params(files: SystemCalls, fd_operand: FdOperand).void }
+      def initialize(files, fd_operand)
+        @files = files
+        @fd_operand = fd_operand
+      end
+
+      sig { params(operator: String, operand: String).returns(T::Boolean) }
+      def unary(operator, operand)
+        resolved = @fd_operand.resolve(operator, operand)
+        TestOperators.unary(operator).call(@files, resolved)
+      end
+    end
+  end
+end