Project

General

Profile

Misc #15744

Improvement needed to documentation of 'Literals'

Added by CaryInVictoria (Cary Swoveland) 18 days ago. Updated 16 days ago.

Status:
Open
Priority:
Normal
Assignee:
-
[ruby-core:92112]

Description

Documentation of "Literals" for v2.6.0 is given here: https://docs.ruby-lang.org/en/2.6.0/syntax/literals_rdoc.html. (I don't think it has been changed for some time.) It gives examples of literals but does not provide a definition. It is comparable to defining an array by giving a few examples. I believe a definition is needed.

I would like to suggest a definition, but I confess I don't know what a Ruby literal is. A definition is attempted at this Wiki for computer programming generally: https://en.wikipedia.org/wiki/Literal_(computer_programming).

I suspect a Ruby literal is an object whose value is in some sense "known" at compile-time. For example, I would think 1, 1.0 and { a: [1, 'cat', ['dog', ['pig', ..10]]] } are literals but { v=>1, 2=>3 } in h = { v=>1, 2=>3 }, v being a variable, is not. Or is it? If the previous line of code had been v=3, Ruby could, at compile-time, infer that the line could be replaced with h = {3=>1, 2=>3}, in which case it would be "known". This example is meant to illustrate why I earlier said "in some sense".

History

Updated by shevegen (Robert A. Heiler) 18 days ago

I am not sure if your definition can be used. For example, you refer to "compile time", but what is meant with
compile time? As far as I know, ruby is not compiled in the sense of generating some binaries/binary executable,
such as when you have a .c file and compile it via gcc; perhaps we can use the term compile differently
(targeting the RubyVM and/or the JIT), but I think the term seems a bit misplaced when referring to literals.

The way I understand the documentation is that literals refers to most "entities" that you can find in a given
.rb file, like, valid syntax components. The explanation "Literals create objects you can use in your program."
probably refers to literals that can be used without any further ado, e. g. "abc" versus String.new("abc").

I guess your main point is a question as to whether a variable is a literal or not.

IF that is your question then I somewhat agree - the documentation could state whether a variable in itself
is a literal. (I assume it is not because the value is not known upfront, unlike e. g. a number such as
42). So the documentation could be changed to reflect this, if you refer to this.

I am not sure if I got all your comment - I think the ruby team is fine updating the documentation; just need
to know what has to be changed/improved, possibly why, and to also ideally provide a way for text to be
copy/pasted into it. :D

I don't know myself either but here is a start:

"Variables in ruby, such as x = 2 or y = '42', are not literals."

Or something like that, perhaps with a slightly longer explanation (I am guessing myself too).

Updated by CaryInVictoria (Cary Swoveland) 16 days ago

shevegen (Robert A. Heiler) wrote:
...I don't know myself either...

Robert,

I was only musing about a how a "literal" might be defined. My only point is that I think a definition is required, since the term is frequently used in discussing Ruby code. Alas, I don't think it's possible to define anything by example, and while I'm not convinced that a satisfactory definition is within reach, I believe it's worth a try.

Also available in: Atom PDF