From: "kddnewton (Kevin Newton) via ruby-core" Date: 2023-08-29T16:29:34+00:00 Subject: [ruby-core:114583] [Ruby master Misc#19772] API naming for YARP compiler Issue #19772 has been updated by kddnewton (Kevin Newton). From this thread and others, this is my understanding of the requirements: * The `YARP` name is not good, since we don't want `YA`- prefixes in production code. * We could like to be able to improve the Ruby API without having to go through the Ruby release cycle. * We would like for users to be able to parse Ruby code as various versions of Ruby have previously parsed Ruby code. * We would like for users to be able to parse Ruby code exactly as the current version of Ruby is parsing Ruby code. Here are the kinds of changes we would like to be able to make outside of the Ruby release cycle: * We would like to be able to add fields to the various nodes. * We would like to be able to add flags to the various nodes. * We would like to be able to change the Ruby API to provide additional functionality/classes. Here are the steps I would like to take to address these requirements: 1. I would like to rename the `YARP` gem to `Prism`. 2. I would like to change the way we build Ruby objects from both the C API and the serialization API. Currently when we build Ruby objects from these APIs, we call `rb_class_new_instance` directly with the fields coming back from the parser. Instead, I will change this to call a Ruby method (either `XXXNode.new` or `YARP.build_xxx_node`) that will instantiate those objects. 3. When we add fields to nodes, we will patch the factory method to handle the various combinations coming back from the various APIs. Those factory methods will check the target Ruby version and handle the fields appropriately for that version of Ruby. 4. When we add flags to nodes or change the Ruby API to provide additional functionality, nothing should have to change. 5. I would like to add `YARP.parse_native` which will take advantage of the previous bullets here to specify that the target Ruby version should be exactly the version of Ruby that is currently running. With these changes in place: * We will have a better name. * We will be able to upgrade the Ruby API in non-breaking ways without going through a Ruby release cycle. * Users will be able to install one version of the gem and be able to parse as previous versions of Ruby did. * Users will be able to install one version of the gem and be able to parse as the current version of Ruby does. * We will not be able to make breaking changes to the C parser. (We don't want to do this outside the Ruby release cycle anyway.) Does this approach sound good to everyone, or are there any other requirements that I have missed? ---------------------------------------- Misc #19772: API naming for YARP compiler https://bugs.ruby-lang.org/issues/19772#change-104398 * Author: jemmai (Jemma Issroff) * Status: Open * Priority: Normal ---------------------------------------- We are working on the YARP compiler, and have [the first PR ready](https://github.com/ruby/ruby/pull/8042) which introduces the YARP compile method. Our only outstanding question before merging it is about naming. How should we expose the public API for YARP's compile method? Potential suggestions: 1. YARP.compile 2. RubyVM::InstructionSequence.compile(yarp: true) 3. RubyVM::InstructionSequence.compile_yarp 4. Any of the above options, with a name other than yarp (please suggest an alternative) Regarding option 1, which would mirror `YARP.parse`, is the top level constant `YARP` acceptable? cc @matz @ko1 -- https://bugs.ruby-lang.org/ ______________________________________________ ruby-core mailing list -- ruby-core@ml.ruby-lang.org To unsubscribe send an email to ruby-core-leave@ml.ruby-lang.org ruby-core info -- https://ml.ruby-lang.org/mailman3/postorius/lists/ruby-core.ml.ruby-lang.org/