编程语言语言运行时编译器解释器嵌入式【免费下载链接】mrubyLightweight Ruby项目地址https://gitcode.com/gh_mirrors/mr/mruby点击查看免费下载导读mruby-struct是 mruby 标准库中提供Struct类的 mrbgem。它允许你无需手写类定义即可将一组属性成员捆绑成带访问器方法的简单类行为与 Ruby 核心的Struct保持一致。本文将围绕官方文档展开从基本用法、三种keyword_init初始化模式、全部可用方法到 C 层实现原理、case/in模式匹配挂钩与测试验证完整呈现这个 gem 的实战价值与内部机制。一、mruby-struct 是什么Struct是 Ruby 世界中的一个经典设施把若干命名属性聚合在一起自动生成读写这些属性的访问器方法省去手工编写类与初始化代码的样板。mruby 将这一能力以独立 mrbgemmruby-struct的形式提供见 mrbgems/mruby-struct/mrbgem.rakeMRuby::Gem::Specification.new(mruby-struct) do |spec| spec.license MIT spec.author mruby developers spec.summary standard Struct class end如何启用默认构建build_config/default.rb引用 mrbgems/default.gembox中stdlib-extgembox 已经包含mruby-struct见 mrbgems/stdlib-ext.gemboxconf.gem :core mruby-struct。其他 gem 也可能通过依赖自动引入它。例如mruby-process的Process::Tms就是一个 Struct因此在 mrbgems/mruby-process/mrbgem.rake 中声明了spec.add_dependency mruby-struct, core: mruby-struct。在自定义构建中显式启用在build_config.rb中写conf.gem :core mruby-struct。注意当前仓库版本为 mruby 4.0见 include/mruby/version.h而文档提到的keyword_init关键字初始化能力在 mruby 3.4 起引入因此本文描述的所有特性在当前仓库中均已具备。二、基本用法定义、实例化、读写与 inspect定义与创建实例# 定义一个包含成员 :x, :y 的 Struct 类 Point Struct.new(:x, :y) # 用位置参数创建实例 origin Point.new(0, 0) # 访问属性成员访问器 puts origin.x # Output: 0 puts origin[:y] # Output: 0 # 设置属性 origin.x 10 origin[:y] 20 puts origin.inspect # Output: #struct Point x10, y20带类名的旧式定义除了匿名定义后赋给常量Struct.new也支持第一种参数为字符串类名生成的类会成为Struct的常量此即 CRuby 兼容的旧式写法Customer Struct.new(Customer, :name, :address) joe Customer.new(Joe Smith, 123 Maple, Anytown NC) puts joe.name # Output: Joe Smith puts joe.address # Output: 123 Maple, Anytown NC底层实现要点从源码看mrbgems/mruby-struct/src/struct.cstruct 实例的内部存储复用 mruby 数组宏RSTRUCT_LEN/RSTRUCT_PTR直接映射到RARRAY_LEN/RARRAY_PTR见src/struct.c顶部因此 struct 在内存中就是一个带成员元信息的数组对象读写效率与数组相当。成员表以__members__实例变量保存在 struct 类上通过类继承链向上查找struct_s_members因此子类自动继承父类的成员定义。每个成员的读访问器mrb_struct_ref与写访问器mrb_struct_set_m在make_struct_define_accessors中通过闭包cfunc env绑定各自的成员下标为每个成员生成一个 reader 和一个以结尾的 writermrb_id_attrset负责拼接后缀并 intern 为新符号。Struct.new与生成的 struct 类的[]即StructClass.[]都是mrb_struct_s_def/mrb_struct_new这两个 C 函数见mrb_mruby_struct_gem_init与make_struct中的方法注册。三、keyword_init关键字初始化与三种模式mruby 3.4 起Struct.new支持通过keyword_init选项启用关键字初始化# 创建启用关键字初始化的 Struct Person Struct.new(:name, :age, keyword_init: true) # keyword_init: true 时只能使用关键字参数 person Person.new(name: Alice, age: 30) puts person.name # Output: Alice puts person.age # Output: 30 # 允许部分关键字缺失成员为 nil person2 Person.new(name: Bob) puts person2.name # Output: Bob puts person2.age # Output: nil # 允许空初始化 person3 Person.new puts person3.name # Output: nil # 位置参数在 keyword_init: true 时会报错 # Person.new(Charlie, 25) # ArgumentError: wrong number of arguments (given 2, expected 0)三种模式对照keyword_init选项共有三种取值语义如下模式允许的初始化方式说明keyword_init: true仅关键字参数位置参数报ArgumentErrorkeyword_init: false仅位置参数哈希按普通值处理keyword_init: nil默认位置参数与关键字参数均可灵活模式# 灵活模式默认行为 FlexPoint Struct.new(:x, :y) p1 FlexPoint.new(1, 2) # Positional arguments p2 FlexPoint.new(x: 3, y: 4) # Keyword arguments p3 FlexPoint.new({x: 3, y: 4}) # Hash passed positionally is a plain value: x{x: 3, y: 4} # 仅关键字模式 KeywordPoint Struct.new(:x, :y, keyword_init: true) p4 KeywordPoint.new(x: 5, y: 6) # Only keyword arguments allowed # 仅位置模式 PositionalPoint Struct.new(:x, :y, keyword_init: false) p5 PositionalPoint.new(7, 8) # Only positional arguments p6 PositionalPoint.new({x: 9, y: 10}) # Hash is treated as first value需要特别留意的是灵活模式下“位置传入的哈希”与“关键字参数”的差别FlexPoint.new(x: 3, y: 4)中x/y是关键字按成员名初始化而FlexPoint.new({x: 3, y: 4})花括号包裹的哈希是作为第一个位置参数传入的普通值因此结果是x{x: 3, y: 4}, ynil。这一区分在测试 mrbgems/mruby-struct/test/struct.rb 中被专门验证c.new({foo: 1, bar: 2})时o.foo得到整个哈希o.bar为nil。查询模式keyword_init?生成的类通过keyword_init?报告其模式返回true、false或nil子类会继承所派生 struct 类的模式KeywordPoint.keyword_init? # true PositionalPoint.keyword_init? # false FlexPoint.keyword_init? # nil Class.new(KeywordPoint).keyword_init? # true实现上keyword_init值被存在 struct 类的__keyword_init__实例变量上struct_s_keyword_init沿类继承链向上查找最近的非nil值mrbgems/mruby-struct/src/struct.c这正是“子类继承模式”的机制来源。测试 mrbgems/mruby-struct/test/struct.rb 对三种取值、非布尔值keyword_init: 12被当作真值处理以及子类继承行为都有断言。keyword_init 在 C 层的实现初始化分派的核心是struct_init_bodymrbgems/mruby-struct/src/struct.c逻辑如下keyword_init: true若参数个数大于 1或唯一的参数不是哈希则调用mrb_argnum_error抛出ArgumentError否则按成员名从哈希取值缺失成员填nilmrb_struct_init_with_keywords。keyword_init: nil默认且调用方确实传了关键字、且唯一的参数是哈希走关键字初始化。其余情况走位置参数初始化mrb_struct_init_with_args参数少于成员数时剩余成员填nil超过成员数则抛ArgumentError: struct size differs。关键字初始化还会校验键合法性对哈希中不在成员列表里的键收集后统一抛出ArgumentError: unknown keywords: ...见mrb_struct_init_with_keywords的末尾校验测试 mrbgems/mruby-struct/test/struct.rb 用unknown keywords: roo, baq验证了该错误信息。覆盖 initialize 时的参数转发如果用户为 struct 类或其子类覆盖了initializeC 构造器mrb_struct_new会检测到initialize不是默认实现mrb_func_basic_p转而将位置参数、关键字参数与 block 通过 Ruby 层桥接方法__struct_init_fwd定义于 mrbgems/mruby-struct/mrblib/struct.rb重新派发给用户自定义的initializeprivate def __struct_init_fwd(args, kw, blk) initialize(*args, **kw, blk) end原因是 mruby 的 C API 无法直接投递关键字参数而 Ruby 层的*args, **kw能保持关键字语义。测试覆盖了位置参数sub.new(1)经initialize放大为2、关键字kw.new(foo: 3)、block 转发c.new { 42 }等多种场景mrbgems/mruby-struct/test/struct.rb。四、可用方法全览类方法生成的 struct 类上方法说明.new(args...)/.[](args...)创建实例两者等价.members返回成员符号数组.keyword_init?返回true/false/nil见上一节实例方法以下方法由 C 层注册见struct_rom_entriesmrbgems/mruby-struct/src/struct.c或由 Ruby 层实现members返回成员名字符号数组。each对每个属性调用一次 block传入对应值返回self。由 Ruby 层实现mrbgems/mruby-struct/mrblib/struct.rbStruct还include Enumerable因此map、reduce等能力一并可用。each_pair对每个属性调用 block传入成员名符号与值mrbgems/mruby-struct/mrblib/struct.rb。select返回 block 为真的值组成的数组mrbgems/mruby-struct/mrblib/struct.rb。to_a/values返回成员值数组。to_h返回成员名符号到值的哈希支持传入 block 将每对[k, v]变换后构造成新哈希block 版实现在 mrbgems/mruby-struct/mrblib/struct.rb非数组返回值抛TypeError长度不为 2 抛ArgumentError。length/size返回成员个数。values_at(*indices)按索引批量取值支持负索引越界抛IndexError。dig(key, ...)逐层抽取嵌套值中间任一步为nil时返回nilmrbgems/mruby-struct/mrblib/struct.rb。[]/[]支持符号、字符串与整数索引三种取值方式符号/字符串对应成员名不存在抛NameError整数按成员位置越界抛IndexError。C 层mrb_struct_aref/mrb_struct_aset会先把字符串键 intern 成符号再查找。/eql?比较两个 struct 实例。要求同类且各成员值相等逐成员用eql?逐成员用eql?实现还针对递归成员与比较过程中成员存储被替换的极端情况做了防护MRB_RECURSIVE_BINARY_FUNC_P对应测试见 mrbgems/mruby-struct/test/struct.rb。deconstruct返回与to_a相同的成员值数组供case/in的数组模式调用。deconstruct_keys(keys)返回给定键名对应成员的哈希传nil时返回全部成员同to_h供case/in的哈希模式调用。to_s/inspect生成#struct Name x10, y20形式字符串递归引用时输出#struct ...防止无限循环测试 mrbgems/mruby-struct/test/struct.rb。五、case/in 模式匹配deconstruct 与 deconstruct_keysStruct在 mruby 中支持模式匹配解构。deconstruct由 C 层直接映射到mrb_struct_to_a而deconstruct_keys由mrb_struct_deconstruct_keys实现mrbgems/mruby-struct/src/struct.c其行为细节如下deconstruct_keys(nil)返回全部成员哈希等于to_h。传入数组时按成员名符号或字符串或成员位置含负索引返回子集键的顺序即传入顺序。遇到第一个不指向任何成员的键立即停止返回已收集的部分键的个数超过成员数时直接返回空哈希——模式只要包含 struct 没有的键就不可能匹配。非数组且非nil的参数抛TypeError。示例Customer Struct.new(:name, :address, :zip) joe Customer.new(Joe Smith, 123 Maple, Anytown NC, 12345) joe.deconstruct # [Joe Smith, 123 Maple, Anytown NC, 12345] joe.deconstruct_keys([:zip]) # {zip: 12345} joe.deconstruct_keys([:phone]) # {}与case/in配合c Struct.new(:a, :b) s c.new(1, 2) case s in [1, x] then x # 数组模式命中 2 end case s in {b: 2, a: x} then x # 哈希模式命中 1 end case s in {zz: 1} then :no in {a: 1} then :yes # 不存在的键模式不匹配回退到本分支 :yes end上述模式匹配行为均有完整测试佐证mrbgems/mruby-struct/test/struct.rb包括字符串/位置键、提前终止、超量键返回空哈希、TypeError等边界。六、参数校验与边界行为Struct.new与实例化过程的边界行为在测试中覆盖得很细值得归纳成员名去重Struct.new(:a, :a)会抛ArgumentError: duplicate member: :a见mrb_struct_s_def中的两两比对循环。非法类名Struct.new(Test-, :a)抛NameError类名必须是合法常量名。成员必须可转符号Struct.new(Test, [:a])抛TypeError。参数数量实例化时位置参数多于成员数抛ArgumentErrorkeyword 模式下位置参数一律报错。冻结o.freeze之后o.m :modify与o[:m] :modify都会抛FrozenErrorC 层mrb_struct_modify宏调用mrb_check_frozen。成员访问器越界访问不存在的成员名如 14 个成员的 struct 访问m14抛NoMethodError[]/[]使用非法键类型抛TypeError。initialize_copy 类型检查Struct.new(Test, :a)与Struct.new(Test, :a, :b)生成的同名类不是同一类型跨类型initialize_copy抛TypeError测试 mrbgems/mruby-struct/test/struct.rb。七、总结与进一步阅读mruby-struct以极小的 C 代码量单文件 src/struct.c 约 980 行复刻了 CRubyStruct的核心能力并以 mruby 3.4 引入的keyword_init三模式、keyword_init?查询、覆盖initialize时的关键字转发以及case/in模式匹配挂钩提供了与标准 Ruby 兼容的现代用法。默认构建经 mrbgems/stdlib-ext.gembox 即可直接使用无需额外配置。如需深入可以继续阅读以下仓库文件实现源码mrbgems/mruby-struct/src/struct.cRuby 层实现each/each_pair/select/to_h/dig/桥接mrbgems/mruby-struct/mrblib/struct.rb完整测试mrbgems/mruby-struct/test/struct.rb构建声明mrbgems/mruby-struct/mrbgem.rakegembox 启用配置mrbgems/stdlib-ext.gembox赞分享编程语言语言运行时编译器解释器嵌入式【免费下载链接】mrubyLightweight Ruby项目地址https://gitcode.com/gh_mirrors/mr/mruby点击查看免费下载相关推荐mruby-sleep 模块全解析为 mruby 注入 Kernelsleep 与 Kernelusleep 延时能力mruby sleep 模块全解析为 mruby 注入 Kernel sleep 与 Kernel usleep 延时能力 导读 mruby sleep 是可观测性日志分析云原生流处理fuels-rs 自定义类型详解Struct / Enum 的 ABI 绑定生成与泛型支持fuels rs 自定义类型详解Struct / Enum 的 ABI 绑定生成与泛型支持 本文聚焦于 Fuel Rust SDKfuels rs中「自定区块链后端rust-by-example 结构体解构Struct Destructuring实战match 模式匹配与嵌套字段绑定rust by example 结构体解构Struct Destructuring实战match 模式匹配与嵌套字段绑定 结构体解构destructur文档教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考