Is there a definitive reference document for Ruby syntax?

I'm searching for a definitive document on Ruby syntax. I know about the definitive documents for the core API and standard library, but what about the syntax itself? For instance, such a document should cover: reserved words, string literals syntax, naming rules for variables/classes/modules, all the conditional statements and their permutations, and so forth.

I know there are many books and tutorials, yes, but every one of them is essentially a tutorial, each one having a range of different depth and focus. They will all, by necessity of brevity and narrative flow, omit certain details of the language that the author deems insignificant.

For instance, did you know that you can use a case statement without an initial case value, and it will then execute the first true when clause? Any given Ruby book or tutorial may or may not cover that particular lesser-known functionality of the case syntax. It's not discussed in the section in "Programming Ruby" about case statements. But that is just one small example.

So far the best documentation I've found is the rubyspec project, which appears to be an attempt to write a complete test suite for the language. That's not bad, but it's a bit hard to use from a practical standpoint as a developer working on my own projects.

Am I just missing something or is there really no *definitive* readable document defining the whole of Ruby syntax?

The *only* document that can be reasonably described as "definitive" is the source code of [parse.y][1] in the YARV source tree.

The [ISO Draft Specification][2] contains a 39 page appendix with a summary of the grammar. Note, however, that ISO Ruby is a minimal subset of the intersection of Ruby 1.8 and 1.9. IOW: it doesn't describe anything that is only in 1.8 or only in 1.9 (so, the syntax additions in 1.9 like stabby proc and symbol hashes aren't described), nor does it describe *everything* in that intersection. ISO Ruby is a bit like ISO HTML in that regard.

The [RubySpec][3] project contains executable specifications for the Ruby language. It doesn't contain an explicit specification of the grammar, though. The only specification of the grammar is *implicit* in the examples themselves. Also, because RubySpec is an example-based spec, it can only show you specific examples of valid Ruby code, but it cannot tell you *all* possible valid Ruby programs like a grammar spec could. And, because RubySpec is itself executable Ruby code, it can only show you valid examples, not invalid ones.

The last thing that could be considered definitive is the book [*The Ruby Programming Language*][4] by David Flanagan and Yukihiro "matz" Matsumoto.

Note, however, that "the whole of Ruby syntax" is a rather daunting task, because Ruby's syntax is *insanely* complicated with a ginormous amount of weird corner cases.

[1]:

[To see links please register here]

[2]:

[To see links please register here]

[3]:

[To see links please register here]

[4]:

[To see links please register here]

There is a draft of a Ruby standard in the works. You can get it here:

[To see links please register here]

Your example about `case` and _Programming Ruby_ is poorly chosen. When _Programming Ruby_ introduces `case` (on page 98 for the first edition; 141 for the second edition), Thomas says,

> The Ruby `case` expression is a powerful beast: a multiway `if` on steroids. And just to make it even more powerful, it comes in two flavors.

He then briefly explains both ways to use case (with an explicit target after the initial `case` and without). He actually begins with the style you say he doesn't mention.

Your larger point is not unreasonable though. It will probably be helpful to have a standard.

As the answer above suggested, there is an effort on writing a "spec" on [

[To see links please register here]

][1].

You have to be careful with that "spec". It is not done by the language designers, and they are basically documenting what they see and not the other way around. It is based on 1.8.7 therefore there may be features in 1.9 that are not covered.

I can't imagine myself remembering the syntax with a 300 page document. To have "over the table", [this cheatsheet][2] describes what you want: condensed syntax, reserved words, etc. [This is an alternative from dzone][3].


[1]:

[To see links please register here]

[2]:
[3]:

[To see links please register here]

This is a pretty good Ruby syntax resource

[To see links please register here]