feat 重构stream流API并适配lex_parse和lexer

runtime/libcore/include/core_stream.h

@@ -1,67 +1,120 @@
-#ifndef __SMCC_CORE_STREAM_H__
-#define __SMCC_CORE_STREAM_H__
+#ifndef __SMCC_CORE_PROBE_STREAM_H__
+#define __SMCC_CORE_PROBE_STREAM_H__
 
 #include "core_impl.h"
 #include "core_macro.h"
 #include "core_mem.h"
 #include "core_str.h"
 
-struct core_stream;
-typedef struct core_stream core_stream_t;
+struct core_probe_stream;
+typedef struct core_probe_stream core_probe_stream_t;
 
 #define core_stream_eof (-1)
 
-struct core_stream {
+/**
+ * @brief 带探针的流接口
+ *
+ * 这个流提供了双指针机制：当前读取位置（头指针）和探针位置（尾指针）。
+ * 尾指针只能向前移动，用于查看而不消费。
+ * 头指针可以前进或单次后退，但不能一直后退到尾指针后面。
+ */
+struct core_probe_stream {
     cstring_t name;
 
+    /// @brief 消费头指针处的字符（移动头指针）
+    int (*consume)(core_probe_stream_t *stream);
+
+    /// @brief 查看当前探针位置的字符，不移动任何指针
+    int (*peek)(core_probe_stream_t *stream);
+
+    /// @brief 移动探针位置并返回字符
+    int (*next)(core_probe_stream_t *stream);
+
+    /// @brief 移动头指针到探针位置
+    void (*sync)(core_probe_stream_t *stream);
+
+    /// @brief 重置探针位置到头指针位置
+    void (*reset)(core_probe_stream_t *stream);
+
+    /// @brief 回退一个字符（单次后退，头指针后退一步）
+    cbool (*back)(core_probe_stream_t *stream);
+
     /// @brief 读取指定数量的字符到缓冲区
-    usize (*read_buf)(core_stream_t *stream, char *buffer, usize count);
+    usize (*read_buf)(core_probe_stream_t *stream, char *buffer, usize count);
 
-    /// @brief 获取下一个字符
-    int (*peek_char)(core_stream_t *stream);
+    /// @brief 检查是否到达流末尾
+    cbool (*is_at_end)(core_probe_stream_t *stream);
 
-    /// @brief 重置字符流位置
-    void (*reset_char)(core_stream_t *stream);
-
-    /// @brief 读取并消费下一个字符（移动流位置）
-    int (*next_char)(core_stream_t *stream);
-
-    /// @brief 释放资源
-    void (*free_stream)(core_stream_t *steam);
+    /// @brief 销毁流并释放资源
+    void (*destroy)(core_probe_stream_t *stream);
 };
 
-static inline usize core_stream_read_buf(core_stream_t *self, char *buffer,
-                                         usize count) {
+static inline int core_probe_stream_consume(core_probe_stream_t *self) {
+    return self->consume(self);
+}
+
+static inline int core_probe_stream_peek(core_probe_stream_t *self) {
+    return self->peek(self);
+}
+
+static inline int core_probe_stream_next(core_probe_stream_t *self) {
+    return self->next(self);
+}
+
+static inline void core_probe_stream_sync(core_probe_stream_t *self) {
+    self->sync(self);
+}
+
+static inline cbool core_probe_stream_back(core_probe_stream_t *self) {
+    return self->back(self);
+}
+
+static inline void core_probe_stream_reset(core_probe_stream_t *self) {
+    self->reset(self);
+}
+
+static inline usize core_probe_stream_read_buf(core_probe_stream_t *self,
+                                               char *buffer, usize count) {
     return self->read_buf(self, buffer, count);
 }
 
-static inline int core_stream_peek_char(core_stream_t *self) {
-    return self->peek_char(self);
+static inline cbool core_probe_stream_is_at_end(core_probe_stream_t *self) {
+    return self->is_at_end(self);
 }
 
-static inline void core_stream_reset_char(core_stream_t *self) {
-    self->reset_char(self);
+static inline cbool core_probe_stream_has_more(core_probe_stream_t *self) {
+    return !self->is_at_end(self);
 }
 
-static inline int core_stream_next_char(core_stream_t *self) {
-    return self->next_char(self);
+static inline void core_probe_stream_destroy(core_probe_stream_t *self) {
+    self->destroy(self);
 }
 
-static inline void core_stream_free_stream(core_stream_t *self) {
-    self->free_stream(self);
-}
-
-#ifndef __SMCC_CORE_NO_MEM_STREAM__
-typedef struct core_mem_stream {
-    core_stream_t stream;
+#ifndef __SMCC_CORE_NO_MEM_PROBE_STREAM__
+/**
+ * @brief 内存探针流结构
+ */
+typedef struct core_mem_probe_stream {
+    core_probe_stream_t stream;
     const char *data;
     usize data_length;
-    usize curr_pos;
-    usize peek_pos;
-    cbool owned;
-} core_mem_stream_t;
-core_stream_t *core_mem_stream_init(core_mem_stream_t *stream, const char *data,
-                                    usize length, cbool need_copy);
+    usize curr_pos;  // 当前读取位置
+    usize probe_pos; // 探针位置（用于peek）
+    cbool owned;     // 是否拥有数据（需要释放）
+} core_mem_probe_stream_t;
+
+/**
+ * @brief 初始化内存探针流
+ *
+ * @param stream 流结构指针
+ * @param data 数据指针
+ * @param length 数据长度
+ * @param need_copy 是否需要复制数据
+ * @return core_probe_stream_t* 成功返回流指针，失败返回NULL
+ */
+core_probe_stream_t *core_mem_probe_stream_init(core_mem_probe_stream_t *stream,
+                                                const char *data, usize length,
+                                                cbool need_copy);
 #endif
 
-#endif /* __SMCC_CORE_STREAM_H__ */
+#endif /* __SMCC_CORE_PROBE_STREAM_H__ */