rush-shell 0.0.2

data/lib/rush/lexer/case_tracker.rb

@@ -0,0 +1,146 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # Tracks paren depth and `case` constructs inside a $( ... ) body so
+    # ParenReader can tell a pattern-terminating `)` (POSIX case_item — not
+    # paren-balanced) from a `)` that counts toward closing the substitution.
+    # ParenReader feeds it words and operator events; each open construct is
+    # a CaseFrame advancing :case_word → :await_in → :pattern ⇄ :body until
+    # `esac` pops it.
+    class CaseTracker
+      extend T::Sig
+
+      # Keyword words at a command position.
+      KEYWORDS = { 'case' => :open_case, 'esac' => :close_case }.freeze
+      # Reserved words that keep the next word at a command position.
+      CONTINUERS = %w[if then else elif while until do ! {].freeze
+      # What a CaseFrame word directive means to the frame stack.
+      DIRECTIVES = { pop: :pop_frame, none: :noop }.freeze
+
+      sig { void }
+      def initialize
+        @frames = T.let([], T::Array[CaseFrame])
+        @command = T.let(true, T::Boolean)
+        @depth = T.let(1, Integer)
+      end
+
+      sig { returns(T::Boolean) }
+      def open?
+        @depth.positive?
+      end
+
+      sig { params(text: String).void }
+      def word(text)
+        return command_word(text) if state == :body
+
+        send(DIRECTIVES.fetch(T.must(frame).word(text)))
+      end
+
+      sig { void }
+      def separator
+        @command = true
+      end
+
+      # dash rejects a newline between a pattern word and its `)` at parse
+      # time; abandoning the frame lets the next `)` close the substitution,
+      # so the invalid construct fails at the re-parse, as it does in dash.
+      sig { void }
+      def newline
+        separator
+        @frames.pop if frame&.marked_pattern?(@depth)
+      end
+
+      # After a redirection operator the next word is a target, not a command.
+      sig { void }
+      def redirect
+        @command = false
+      end
+
+      sig { void }
+      def dsemi
+        @command = true
+        frame&.reopen(@depth)
+      end
+
+      sig { void }
+      def open_paren
+        @command = true
+        frame&.group(@depth)
+        @depth += 1
+      end
+
+      # True when the just-read `)` stays in the body: either it terminates a
+      # case pattern (swallowed, not counted) or it closes a nested paren.
+      # False only for the `)` that ends the substitution.
+      sig { returns(T::Boolean) }
+      def close_paren?
+        return true if pattern_close?
+
+        @depth -= 1
+        finish_group
+        open?
+      end
+
+      private
+
+      sig { returns(T.nilable(CaseFrame)) }
+      def frame
+        @frames.last
+      end
+
+      sig { returns(Symbol) }
+      def state
+        found = frame
+        found ? found.state : :body
+      end
+
+      sig { returns(T::Boolean) }
+      def pattern_close?
+        return false unless frame&.pattern?(@depth)
+
+        enter_body
+        true
+      end
+
+      # A grouped pattern `(x)` closing back to its base depth enters the
+      # item's body.
+      sig { void }
+      def finish_group
+        enter_body if frame&.grouped?(@depth)
+        @command = true
+      end
+
+      sig { void }
+      def enter_body
+        T.must(frame).body
+        @command = true
+      end
+
+      sig { params(text: String).void }
+      def command_word(text)
+        send(KEYWORDS.fetch(text, :noop))
+        @command = CONTINUERS.include?(text)
+      end
+
+      sig { void }
+      def noop; end
+
+      sig { void }
+      def pop_frame
+        @frames.pop if frame&.at?(@depth)
+      end
+
+      sig { void }
+      def open_case
+        @frames.push(CaseFrame.new(@depth)) if @command
+      end
+
+      sig { void }
+      def close_case
+        pop_frame if @command
+      end
+    end
+  end
+end

data/lib/rush/lexer/dollar_scanner.rb

@@ -0,0 +1,53 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # Reads a substitution at the word scanner's current position into the matching
+    # AST segment: $name / ${...} parameter refs (via ParamScanner), $(...) command
+    # substitution, $((...)) arithmetic, and `...` backticks. #read returns nil for
+    # a lone `$` that begins no valid reference, so the caller keeps it as a
+    # literal dollar.
+    class DollarScanner
+      extend T::Sig
+      include ScannerPredicates
+
+      sig { params(scanner: StringScanner).void }
+      def initialize(scanner)
+        @scanner = scanner
+      end
+
+      # The segment for a `$...` at the scanner head (the `$` not yet consumed),
+      # or nil when no valid reference follows. An unterminated ${ asks for more
+      # input: an interactive word may continue on the next line.
+      sig { params(quoted: T::Boolean).returns(T.untyped) }
+      def read(quoted:)
+        @scanner.getch
+        return dollar_paren(quoted) if peek?('(')
+
+        ref = ParamScanner.new(@scanner, error: IncompleteInput, quoted: quoted).read
+        ref && AST::ParamSegment.new(ref, quoted)
+      end
+
+      # The command segment for a `` `...` `` at the scanner head.
+      sig { params(quoted: T::Boolean).returns(AST::CommandSegment) }
+      def read_backtick(quoted:)
+        @scanner.getch # `
+        AST::CommandSegment.new(SubstitutionReader.new(@scanner).backticks, quoted)
+      end
+
+      private
+
+      # `$((` begins arithmetic; a lone `$(` (including `$( (`) is command sub.
+      sig { params(quoted: T::Boolean).returns(AST::DynamicSegment[String]) }
+      def dollar_paren(quoted)
+        @scanner.getch # opening (
+        reader = SubstitutionReader.new(@scanner)
+        return AST::CommandSegment.new(reader.parens, quoted) unless peek?('(')
+
+        @scanner.getch # second (
+        AST::ArithSegment.new(reader.arithmetic, quoted)
+      end
+    end
+  end
+end

data/lib/rush/lexer/double_quote_scanner.rb

@@ -0,0 +1,71 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # Scans the interior of a "..." region into the host word's SegmentBuffer:
+    # literal runs keep their quoted flag, $ and ` stay live, and a backslash
+    # escapes only " \ $ ` — plus the line continuation, whose interactive
+    # rules the host owns and injects as a callback. The opening quote is
+    # already consumed when this scanner starts; it consumes the closing one.
+    class DoubleQuoteScanner
+      extend T::Sig
+      include ScannerPredicates
+
+      LITERAL = /[^"$\\`]+/
+      SPECIAL = ['"', '\\', '$', '`'].freeze
+
+      sig { params(scanner: StringScanner, buffer: SegmentBuffer, continuation: T.proc.void).void }
+      def initialize(scanner, buffer, continuation)
+        @scanner = scanner
+        @buffer = buffer
+        @continuation = continuation
+      end
+
+      sig { void }
+      def scan
+        push('') if peek?('"') # "" yields one empty field
+        step until done?
+        raise IncompleteInput, 'unterminated double quote' if @scanner.eos?
+
+        @scanner.getch
+      end
+
+      private
+
+      sig { returns(T::Boolean) }
+      def done?
+        @scanner.eos? || peek?('"')
+      end
+
+      sig { void }
+      def step
+        return dollar if peek?('$')
+        return @buffer.push(DollarScanner.new(@scanner).read_backtick(quoted: true)) if peek?('`')
+        return escape if peek?('\\')
+
+        push(@scanner.scan(LITERAL))
+      end
+
+      sig { void }
+      def escape
+        @scanner.getch
+        return @continuation.call if peek?("\n")
+
+        SPECIAL.include?(@scanner.peek(1)) ? push(@scanner.getch) : push('\\')
+      end
+
+      # A lone `$` that begins no valid reference stays a quoted literal dollar.
+      sig { void }
+      def dollar
+        segment = DollarScanner.new(@scanner).read(quoted: true)
+        segment ? @buffer.push(segment) : push('$')
+      end
+
+      sig { params(value: T.untyped).void }
+      def push(value)
+        @buffer.push(AST::LiteralSegment.new(value, true))
+      end
+    end
+  end
+end

data/lib/rush/lexer/heredoc_body.rb

@@ -0,0 +1,91 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # Scans an unquoted here-document body into an AST::Word of literal / :param /
+    # :command segments. Unlike WordScanner there are no quote delimiters (quotes
+    # are literal) and no terminator (it consumes the whole body); a backslash
+    # escapes only $, ` and \. Expansion itself is deferred to execution, so the
+    # body reflects the variable values at the time the command runs. Parameter
+    # references are read by the shared ParamScanner.
+    class HeredocBody
+      extend T::Sig
+      include ScannerPredicates
+
+      ESCAPES = { '$' => '$', '`' => '`', '\\' => '\\' }.freeze
+      ESCAPE_TABLE = EscapeTable.new(ESCAPES).freeze
+
+      sig { params(text: String).void }
+      def initialize(text)
+        @scanner = StringScanner.new(text)
+        @buffer = SegmentBuffer.new
+      end
+
+      sig { returns(AST::Word) }
+      def scan
+        loop do
+          char = @scanner.getch
+          return @buffer.word unless char
+
+          step(char)
+        end
+      end
+
+      private
+
+      sig { params(char: String).void }
+      def step(char)
+        return dollar if char == '$'
+        return backtick if char == '`'
+        return escape if char == '\\'
+
+        @buffer << char
+      end
+
+      sig { void }
+      def dollar
+        peek?('(') ? dollar_paren : param
+      end
+
+      sig { void }
+      def dollar_paren
+        @scanner.getch
+        reader = SubstitutionReader.new(@scanner)
+        peek?('(') ? arithmetic(reader) : command_sub(reader)
+      end
+
+      sig { params(reader: SubstitutionReader).void }
+      def command_sub(reader)
+        @buffer.push(AST::CommandSegment.new(reader.parens, false))
+      end
+
+      sig { params(reader: SubstitutionReader).void }
+      def arithmetic(reader)
+        @scanner.getch
+        @buffer.push(AST::ArithSegment.new(reader.arithmetic, false))
+      end
+
+      sig { void }
+      def backtick
+        @buffer.push(AST::CommandSegment.new(SubstitutionReader.new(@scanner).backticks, false))
+      end
+
+      # A here-doc body is a quoted context for its ${...} references: dash
+      # treats their operator words as if inside double quotes.
+      sig { void }
+      def param
+        ref = ParamScanner.new(@scanner, quoted: true).read
+        ref ? @buffer.push(AST::ParamSegment.new(ref, true)) : (@buffer << '$')
+      end
+
+      sig { void }
+      def escape
+        char = @scanner.getch
+        return if char == "\n" # line continuation, as inside double quotes
+
+        @buffer << ESCAPE_TABLE.escape(char)
+      end
+    end
+  end
+end

data/lib/rush/lexer/heredoc_reader.rb

@@ -0,0 +1,93 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # Reads here-document bodies from the lexer's scanner once the command line's
+    # terminating newline is reached. For each pending `<<word` holder it gathers
+    # the following lines up to the delimiter line, strips leading tabs for the
+    # `<<-` form, and parses the body for expansion unless the delimiter was
+    # quoted (a quoted delimiter makes the body literal).
+    class HeredocReader
+      extend T::Sig
+
+      sig { params(scanner: StringScanner, interactive: T::Boolean).void }
+      def initialize(scanner, interactive:)
+        @scanner = scanner
+        @interactive = interactive
+      end
+
+      # Fill each holder, in the order the `<<`s appeared, with its body.
+      sig { params(holders: T::Array[HereDoc]).void }
+      def fill(holders)
+        holders.each { |holder| holder.fill(read(holder)) }
+      end
+
+      private
+
+      sig { params(holder: HereDoc).returns(AST::Word) }
+      def read(holder)
+        build_body(holder, gather(holder, +''))
+      end
+
+      sig { params(holder: HereDoc, out: String).returns(String) }
+      def gather(holder, out)
+        line = heredoc_line(holder)
+        return out unless line
+
+        gather(holder, out << line)
+      end
+
+      sig { params(holder: HereDoc).returns(T.nilable(String)) }
+      def heredoc_line(holder)
+        return eof_line if @scanner.eos?
+
+        line = read_line
+        return if delimiter?(holder, line)
+
+        strip_tabs(holder, line)
+      end
+
+      sig { returns(T.nilable(String)) }
+      def eof_line
+        raise IncompleteInput, 'unterminated here-document' if @interactive
+      end
+
+      sig { returns(String) }
+      def read_line
+        @scanner.scan_until(/\n/) || rest_line
+      end
+
+      sig { returns(String) }
+      def rest_line
+        line = @scanner.rest
+        @scanner.terminate
+        line
+      end
+
+      sig { params(holder: HereDoc, line: String).returns(T::Boolean) }
+      def delimiter?(holder, line)
+        strip_tabs(holder, line).chomp == holder.delimiter
+      end
+
+      sig { params(holder: HereDoc, line: String).returns(String) }
+      def strip_tabs(holder, line)
+        holder.strip ? line.sub(/\A\t+/, '') : line
+      end
+
+      # A quoted delimiter (<<'EOF') makes the body literal; an unquoted one is
+      # parsed for expansion ($var, $(...), `...`), applied later at execution.
+      sig { params(holder: HereDoc, text: String).returns(AST::Word) }
+      def build_body(holder, text)
+        return literal_word(text) if holder.quoted
+
+        HeredocBody.new(text).scan
+      end
+
+      sig { params(text: String).returns(AST::Word) }
+      def literal_word(text)
+        AST::Word.new([AST::LiteralSegment.new(text, false)])
+      end
+    end
+  end
+end

data/lib/rush/lexer/lex_state.rb

@@ -0,0 +1,128 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # Tracks command position (POSIX Grammar Rule 1) plus the for-header and case
+    # modes (Rules 4-6): the for NAME and `in`, and the case subject / `in` /
+    # pattern / `esac` positions. A compound stack lets nested for/case/if/etc.
+    # temporarily use their own header modes inside a case body, then return to
+    # the surrounding case body so `;;` and `esac` are classified correctly.
+    class LexState
+      extend T::Sig
+
+      REDIRECT_OPS = T.let(['<', '>', :DGREAT, :LESSGREAT, :CLOBBER].freeze, T::Array[T.any(String, Symbol)])
+      INTRODUCERS = T.let([
+        :NEWLINE, ';', '&', '|', '(', ')', :AND_IF, :OR_IF,
+        :If, :Then, :Else, :Elif, :Lbrace, :Bang, :While, :Until, :Do, :DSEMI
+      ].freeze, T::Array[T.any(String, Symbol)])
+      NEUTRAL = T.let(%i[ASSIGNMENT_WORD IO_NUMBER].freeze, T::Array[Symbol])
+      OPENERS = T.let({ For: :Done, While: :Done, Until: :Done, If: :Fi,
+                        Case: :Esac, Lbrace: :Rbrace, '(' => ')' }.freeze,
+                      T::Hash[T.any(String, Symbol), T.any(String, Symbol)])
+      TRANSITIONS = {
+        %i[normal For] => :for_name, %i[case_body For] => :for_name,
+        %i[normal Case] => :case_subject, %i[case_body Case] => :case_subject,
+        %i[for_name NAME] => :for_in,
+        %i[for_in In] => :normal, %i[for_in Do] => :normal,
+        %i[for_in NEWLINE] => :normal, [:for_in, ';'] => :normal, [:for_in, '&'] => :normal,
+        %i[case_subject WORD] => :case_in, %i[case_in In] => :case_arm,
+        %i[case_arm WORD] => :case_pat, %i[case_arm Esac] => :normal,
+        [:case_pat, ')'] => :case_body, %i[case_body DSEMI] => :case_arm
+      }.freeze
+
+      sig { void }
+      def initialize
+        @command_position = true
+        @expect_filename = false
+        @mode = :normal
+        @compounds = []
+      end
+
+      sig { returns(T::Boolean) }
+      def expects_command?
+        @command_position && !@expect_filename
+      end
+
+      # A command word here is a real command name, so alias substitution applies:
+      # the normal mode and a case arm's command list. The for-header and case
+      # subject/pattern modes do not expand aliases, even when a newline resets
+      # command position.
+      sig { returns(T::Boolean) }
+      def command_mode?
+        @mode == :normal || @mode == :case_body
+      end
+
+      sig { returns(T::Boolean) }
+      def for_name?
+        @mode == :for_name
+      end
+
+      sig { returns(T::Boolean) }
+      def for_in?
+        @mode == :for_in
+      end
+
+      sig { returns(T::Boolean) }
+      def case_subject?
+        @mode == :case_subject
+      end
+
+      sig { returns(T::Boolean) }
+      def case_in?
+        @mode == :case_in
+      end
+
+      sig { returns(T::Boolean) }
+      def case_arm?
+        @mode == :case_arm
+      end
+
+      sig { returns(T::Boolean) }
+      def case_pat?
+        @mode == :case_pat
+      end
+
+      sig { params(symbol: T.any(String, Symbol)).void }
+      def advance(symbol)
+        transition(symbol)
+        update_position(symbol)
+      end
+
+      private
+
+      sig { params(symbol: T.any(String, Symbol)).void }
+      def transition(symbol)
+        start_compound(symbol)
+        @mode = TRANSITIONS.fetch([@mode, symbol], @mode)
+        @mode = T.must(@compounds.pop).last if @compounds.last&.first == symbol
+      end
+
+      sig { params(symbol: T.any(String, Symbol)).void }
+      def update_position(symbol)
+        return @expect_filename = true if REDIRECT_OPS.include?(symbol)
+        return reset if INTRODUCERS.include?(symbol)
+        return @expect_filename = false if NEUTRAL.include?(symbol)
+
+        consume_word
+      end
+
+      sig { params(symbol: T.any(String, Symbol)).void }
+      def start_compound(symbol)
+        close = OPENERS.fetch(symbol, nil)
+        @compounds << [close, @mode] if close && expects_command? && command_mode?
+      end
+
+      sig { void }
+      def reset
+        @command_position = true
+        @expect_filename = false
+      end
+
+      sig { void }
+      def consume_word
+        @expect_filename ? (@expect_filename = false) : (@command_position = false)
+      end
+    end
+  end
+end

data/lib/rush/lexer/operator_table.rb

@@ -0,0 +1,32 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # Maximal-munch operator table: alternatives are tried longest-first so `>>`
+    # beats `>`, `&&` beats `&`, `>|` beats `>`, and the fd-dup `>&`/`<&` beat
+    # `>`/`<` then `&`. Single-character operators are their own token (matching
+    # the grammar's '<' '>' '|' '&' ';'); multi-char operators map to named tokens.
+    module OperatorTable
+      OPERATORS = {
+        '<<-' => :DLESSDASH, '&&' => :AND_IF, '||' => :OR_IF, '>>' => :DGREAT,
+        '<<' => :DLESS, ';;' => :DSEMI, '<>' => :LESSGREAT, '>|' => :CLOBBER,
+        '>&' => :GREATAND, '<&' => :LESSAND,
+        '<' => '<', '>' => '>', '|' => '|', '&' => '&', ';' => ';', '(' => '(', ')' => ')'
+      }.freeze
+
+      # POSIX 2.2.1 removes a backslash-newline before tokenization — even between
+      # the characters of one operator: dash splices it at the character read
+      # (pgetc_eatbnl), so `&\<newline>&` lexes as `&&`. Each alternative therefore
+      # admits continuation pairs between its characters; the lexer splices them
+      # back out of the match before looking the operator up.
+      CONTINUATION = /\\\n/
+
+      splice = "(?:#{CONTINUATION.source})*"
+      longest_first = OPERATORS.keys.sort_by { |op| -op.length }
+      PATTERN = Regexp.new(
+        longest_first.map { |op| op.chars.map { |char| Regexp.escape(char) }.join(splice) }.join('|')
+      ).freeze
+    end
+  end
+end

data/lib/rush/lexer/param_scanner.rb

@@ -0,0 +1,43 @@
+# typed: true
+# frozen_string_literal: true
+
+module Rush
+  class Lexer
+    # Reads the parameter reference after a consumed `$` at the scanner head:
+    # $name / $digit / $special, or the braced ${...} forms (whose body the
+    # BracedReader matches to the closing brace). Returns nil when no reference
+    # begins, so the caller keeps the `$` literal. An unterminated ${ raises
+    # the given error class: IncompleteInput lets an interactive word ask for
+    # another line, while heredoc bodies and prompt values are already complete
+    # and fail as plain parse errors. `quoted` names the surrounding context —
+    # inside double quotes and here-doc bodies a single quote is ordinary.
+    class ParamScanner
+      extend T::Sig
+
+      PARAM = /[a-zA-Z_]\w*|\d|[@*#?$!\-0]/
+
+      sig { params(scanner: StringScanner, quoted: T::Boolean, error: T.class_of(ParseError)).void }
+      def initialize(scanner, quoted:, error: ParseError)
+        @scanner = scanner
+        @error = error
+        @quoted = quoted
+      end
+
+      sig { returns(T.nilable(AST::ParamRef)) }
+      def read
+        return braced if @scanner.peek(1) == '{'
+
+        name = @scanner.scan(PARAM)
+        name && AST::ParamRef.simple(name)
+      end
+
+      private
+
+      sig { returns(AST::ParamRef) }
+      def braced
+        @scanner.getch
+        AST::ParamRef.parse(BracedReader.new(@scanner, error: @error, quoted: @quoted).read)
+      end
+    end
+  end
+end