s2s2lua 0.1.1

Transpile Stranded II .s2s scripts to Lua for OpenStranded
Documentation
// s2s2lua – transpile Stranded II .s2s scripts to Lua for OpenStranded
// Copyright (C) 2025  s2s2lua contributors
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.

//! Logos-based tokenizer for .s2s scripts.
//!
//! Tokens are defined as a Logos enum. The lexer wraps Logos to provide
//! skip of whitespace/comments and a peekable interface.

use logos::Logos;
use std::ops::Range;

/// Tokens recognized by the s2s lexer.
#[derive(Logos, Debug, Clone, PartialEq)]
pub enum Token {
    // ── Keywords ──────────────────────────────────────────
    #[token("on")]
    On,
    #[token("if")]
    If,
    #[token("elseif")]
    ElseIf,
    #[token("else")]
    Else,
    #[token("loop")]
    Loop,
    #[token("exit")]
    Exit,
    #[token("skip")]
    Skip,
    #[token("skipevent")]
    SkipEvent,

    // ── Keyword-operators (before Ident, since they match the same pattern) ──
    #[token("and")]
    AndKw,
    #[token("or")]
    OrKw,

    // ── Identifiers ───────────────────────────────────────
    #[regex(r"[a-zA-Z_][a-zA-Z0-9_]*")]
    Ident,

    // ── String literal ────────────────────────────────────
    #[regex(r#""([^"\\]|\\.)*""#)]
    String,

    // ── Numbers ───────────────────────────────────────────
    #[regex(r"[0-9]+(\.[0-9]+)?")]
    Number,

    // ── Variables ─────────────────────────────────────────
    #[regex(r"\$[a-zA-Z_][a-zA-Z0-9_]*")]
    Variable,

    // ── Operators ─────────────────────────────────────────
    #[token("==")]
    Eq,
    #[token("!=")]
    Ne,
    #[token("<=")]
    Le,
    #[token(">=")]
    Ge,
    #[token("<")]
    Lt,
    #[token(">")]
    Gt,
    #[token("&&")]
    And,
    #[token("||")]
    Or,
    #[token("xor")]
    Xor,
    #[token("*")]
    Star,
    #[token("/")]
    Slash,
    #[token("+=")]
    AddAssign,
    #[token("-=")]
    SubAssign,
    #[token("++")]
    Inc,
    #[token("--")]
    Dec,
    #[token("+")]
    Plus,
    #[token("-")]
    Minus,

    // ── Punctuation ───────────────────────────────────────
    #[token("=")]
    Assign,
    #[token("(")]
    LParen,
    #[token(")")]
    RParen,
    #[token("{")]
    LBrace,
    #[token("}")]
    RBrace,
    #[token(";")]
    Semicolon,
    #[token(",")]
    Comma,
    #[token(":")]
    Colon,
    #[token("@")]
    At,

    // ── Comments ──────────────────────────────────────────
    #[regex(r"//[^\n]*", allow_greedy = true)]
    LineComment,
    #[regex(r"/\*[^*]*\*+(?:[^/*][^*]*\*+)*/")]
    BlockComment,

    // ── Whitespace (skipped) ──────────────────────────────
    #[logos(skip r"[ \t\r\n]+")]
    Whitespace,
}

impl Token {
    /// Human-readable name for error messages.
    pub fn name(&self) -> &'static str {
        match self {
            Token::On => "'on'",
            Token::If => "'if'",
            Token::ElseIf => "'elseif'",
            Token::Else => "'else'",
            Token::Loop => "'loop'",
            Token::Exit => "'exit'",
            Token::Skip => "'skip'",
            Token::SkipEvent => "'skipevent'",
            Token::Ident => "identifier",
            Token::String => "string literal",
            Token::Number => "number",
            Token::Variable => "variable",
            Token::Eq => "'=='",
            Token::Ne => "'!='",
            Token::Le => "'<='",
            Token::Ge => "'>='",
            Token::Lt => "'<'",
            Token::Gt => "'>'",
            Token::And => "'&&'",
            Token::Or => "'||'",
            Token::Xor => "'xor'",
            Token::AndKw => "'and'",
            Token::OrKw => "'or'",
            Token::Star => "'*'",
            Token::Slash => "'/'",
            Token::AddAssign => "'+='",
            Token::SubAssign => "'-='",
            Token::Inc => "'++'",
            Token::Dec => "'--'",
            Token::Plus => "'+'",
            Token::Minus => "'-'",
            Token::Assign => "'='",
            Token::LParen => "'('",
            Token::RParen => "')'",
            Token::LBrace => "'{'",
            Token::RBrace => "'}'",
            Token::Semicolon => "';'",
            Token::Comma => "','",
            Token::Colon => "':'",
            Token::At => "'@'",
            Token::LineComment => "comment",
            Token::BlockComment => "block comment",
            Token::Whitespace => "whitespace",
        }
    }
}

/// A lexed token with its text and span.
#[derive(Debug, Clone)]
pub struct SpannedToken {
    pub token: Token,
    pub text: String,
    pub span: Range<usize>,
}

/// Lexer wrapper that yields `SpannedToken` items.
pub struct S2sLexer<'source> {
    inner: logos::Lexer<'source, Token>,
    source: &'source str,
    /// Store the next token for peek
    peeked: Option<Option<(Token, Range<usize>)>>,
}

impl<'source> S2sLexer<'source> {
    pub fn new(source: &'source str) -> Self {
        Self {
            inner: Token::lexer(source),
            source,
            peeked: None,
        }
    }

    /// Peek at the next token without consuming it.
    pub fn peek(&mut self) -> Option<&(Token, Range<usize>)> {
        if self.peeked.is_none() {
            self.peeked = Some(self.next_raw());
        }
        self.peeked.as_ref().and_then(|o| o.as_ref())
    }

    /// Consume and return the next token and its span.
    pub fn next_token(&mut self) -> Option<(Token, Range<usize>)> {
        if let Some(peeked) = self.peeked.take() {
            return peeked;
        }
        self.next_raw()
    }

    /// Get the next token from the inner lexer, skipping whitespace only.
    /// Comments (LineComment, BlockComment) are NOT skipped so the parser
    /// can preserve them in the Lua output.
    fn next_raw(&mut self) -> Option<(Token, Range<usize>)> {
        loop {
            let result = self.inner.next()?;
            match result {
                Ok(tok) => {
                    let span = self.inner.span();
                    match tok {
                        Token::Whitespace => continue,
                        _ => return Some((tok, span)),
                    }
                }
                Err(()) => {
                    // Skip unrecognized single characters (shouldn't normally happen)
                    let span = self.inner.span();
                    // Return it as an error token? Just skip for now.
                    if span.is_empty() {
                        return None;
                    }
                    // Skip the bad character
                    continue;
                }
            }
        }
    }

    /// Get the source text for a span.
    pub fn slice(&self, span: &Range<usize>) -> &'source str {
        &self.source[span.clone()]
    }

    /// Convert byte offset to (line, column).
    /// Takes offset directly rather than borrowing self to avoid borrow conflicts.
    pub fn offset_to_linecol(&self, offset: usize) -> (usize, usize) {
        let before = &self.source[..offset.min(self.source.len())];
        let line = before.matches('\n').count() + 1;
        let col = offset - before.rfind('\n').map(|p| p + 1).unwrap_or(0) + 1;
        (line, col)
    }

    /// Get the current peek offset without borrowing issues.
    /// Returns None if nothing is peeked.
    pub fn peek_offset(&mut self) -> Option<usize> {
        self.peek().map(|(_, s)| s.start)
    }

    /// Get the full source text.
    pub fn source(&self) -> &'source str {
        self.source
    }
}