From: "kddnewton (Kevin Newton) via ruby-core" Date: 2023-08-24T13:41:04+00:00 Subject: [ruby-core:114490] [Ruby master Misc#19772] API naming for YARP compiler Issue #19772 has been updated by kddnewton (Kevin Newton). Thank you all for taking the time to discuss this issue at the meeting! I'm sorry I wasn't able to be there this time. I have a couple of concerns about the naming, which I'd like to discuss further. Going forward, the only people that will be using the Ruby API of the parser will be tool developers. (For example, formatters like Syntax Tree, linters like Rubocop, static analysis tools like Steep.) In order to provide a good experience for them, we will need to be able to provide bug fixes and features outside of the Ruby release cycle. As a couple of examples, we recently added `IntegerNode#value`, `FloatNode#value`, `Location#join`, etc. We also fixed some bugs in the Ruby API itself that doesn't impact the C API. In order for developers to upgrade their version of the parser gem, they will need to be able to install the new version. Currently, when you install the latest version of the `yarp` gem, it comes earlier in the load path so it gets picked up before the bundled version. This works well. If we were to name the Ruby API `::Ruby::Parser`, but we weren't allowed to define any constants in a gem within `::Ruby`, it would mean we would have to convert all of the constant references in the sync script, or define them all twice. I'm not sure how we would accomplish that. Furthermore, if a tool developer were to use `::Ruby::Parser` and then wanted to upgrade to get the latest APIs/bug fixes, they would immediately have to switch all of their constant references over to the gem's version. If this ended up being the case, I think I would suggest just never using `::Ruby::Parser` for tool developers because inevitably it would require that migration. So my only issue is the consistency in naming, really. If the constants in the built-in API do not match the constants in the gem API, the only way to get bug fixes and features will be to wait for the next version of Ruby. I have a couple of options that I think would work going forward that I would like to suggest: 1. We could name the gem `ruby-parser`. The advantages are that the constants would match up and there would be no difficulty in using this API from a tool author's perspective. The disadvantages would be that the gem would be defining constants under `::Ruby` and there already is a `ruby_parser` gem. 2. We could name the gem `prism` (or some other name). The advantages are the same as `ruby-parser`, but also that it does not start with the `YA`- prefix. The disadvantages are that `prism` is less clear than `ruby-parser` in what it does. (The original idea was the `prism` relates to optics, in that we are looking at Ruby source code and reflecting it in different ways through Ruby, C, and serialization APIs.) 3. We could keep the name `yarp`. The only advantage is that nothing changes. The disadvantage is that no one knows what `yarp` actually means. I am fine with any of these options, and am certainly open to more ideas if there are some! In summary the main thing I would like to keep in mind is that the Ruby API will be used by tool developers, and we should make it as easy as possible for them to maintain the tools. Thank you for the consideration! ---------------------------------------- Misc #19772: API naming for YARP compiler https://bugs.ruby-lang.org/issues/19772#change-104275 * 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/