I’m an experienced programmer interested in exploring Crystal for some personal projects.
I’m working my way through the Crystal Language Reference as well as trying to understand a variety of code snippets I’ve found online (.e.g https://github.com/askn/crystal-by-example).
I find myself frustrated by the lack of documentation and explanation of basic syntax and idioms in the language reference. A few examples of this:
No where in the language reference does it explicitly say “<<” is the append operator for arrays. This page (https://crystal-lang.org/reference/syntax_and_semantics/literals/array.html) gives an example of this, but if you don’t already know the operator a search on “append” in the manual search box doesn’t help. Similarly, there is no example for such basic operations as getting the length of an array (must resort to Google to find examples)
There is inadequate explanation of the iterator syntax in the reference; to grok the iterator syntax I found I had to resort to reading a Ruby tutorial.
Short of learning Ruby, and then coming back to Crystal, is there some other tutorial or reference resource that I should be reading?
I’d suggest to checkout the API docs as well, for example https://crystal-lang.org/api/Array.html, which will show you the public API for each type. From there you could probably find your way around things as #<< is pretty much just an alias to #push which is found in other languages, such as js.
PRs to the reference documentation and/or the API docs are always welcomed, as for some types they are severely lacking. As far as I’m aware a lot of Crystal users have a Ruby background, so updating docs for those not coming from Ruby would be a good addition.
People might call this bad idea but I learned Ruby first then worked to understand the differences. Tooling and understanding compiler errors was harder than anything else TBH. Might be worth learning Ruby first and then understanding what Crystal changes.
Imagine ruby but with a new standard library and API and compiled instead of interpreted with data type enforcements and nil safety. Gross oversimplification but this’ll get the ground rolling.
I searched << on the docs page, and it worked. However, you are correct it does not work on GitBook.
Please don’t be too frustrated, I think resorting to Google is not necessarily a bad thing in the beginning. I know I relied on it a lot, but over time, I now just alt-tab to the docs page. Hang in there. It will definitely be worth it in the end.
This is the first time pmags has posted — let’s welcome them to our community!
I think it would help a lot if you went through some Ruby tutorials (since there are so many available). Your question would be answered if you knew that in Ruby/Crystal, everything is an object. Then you would know that << is a method, not an operator per se. And then you would know how to look it up in the docs as a method of Array.
You will love Ruby/Crystal. Hang in there. Check out Rosetta Code to see how to accomplish basic tasks (there was an effort a few months ago to flesh out the Crystal pieces).
I’ve now worked through some intro Ruby material and that’s definitely helped.
I think it would be useful, and minimize the frustration of new comers like myself, if it was noted somewhere in the beginning of the Language Reference that at this time a full overview of Crystal syntax isn’t available in prose form and point new users to some appropriate Ruby material, noting where the two languages differ. Once I feel comfortable enough with the Crystal and associated Ruby materials I’ll try and craft a suitable PR myself to this effect.
I think one of the main issues is that someone learning Crystal approaches it as a single entity. But in fact, there are two separate aspects to it: The language (including the compiler) and the standard library. The language and compiler are documented at crystal-lang.org/reference/, the stdlib is documented at crystal-lang.org/api/.
From a conceptual POV it makes sense to separate them. You can use the Crystal language without the standard library. Or there could be different implementations of the language, but using the same stdlib.
For a beginner eager to learn, this separation isn’t helpful. You need to learn both, the language and stdlib in order to work with Crystal. We direly need a getting started guide to help people get on board. Neither the language reference nor the API docs are meant as a tutorial.
Regarding your specific issues:
I’ve been reworking the operator section in the language reference, which also adds explanations for typical behaviour of operators such as <<. It’s pretty much finished, just needs a little bit polish here and there: https://github.com/crystal-lang/crystal-book/pull/370
What exactly do you mean with “iterator syntax”? Can you share the Ruby tutorial that helped you?
Gitbook search is a very sad experience. We should really see to replace it with a stable and maintained alternative.
By “iterator syntax” I meant the each do syntax for traversing an Enumerable (is that the right Ruby/Crystal terminology?). The explanation here, which I found by googling “Ruby iterators” set me straight: https://launchschool.com/books/ruby/read/loops_iterators#iterators
re: a “Getting Started Guide” – yes, I think that’s what I was expecting from the Crystal Language Reference.
Part of my confusion was that the “Crystal Language Reference” doesn’t read like the type of formal language reference I’m used to from other languages – for example in Python (https://docs.python.org/3/reference/) or Go (https://golang.org/ref/spec). These are typically tightly edited formal definitions of the rules of the respective languages. In contrast, the Crystal Language Reference reads like a mix of a language reference and an introduction – particularly the first few sections but also later sections like “Types and Methods”.
p.s. The only two links in a post for new members rule is very frustrating! Is this a discourse thing?
The more general concept/term is probably “block syntax”. There is a section about that in the reference: Blocks and Procs.
But if you don’t know the term, you would probably only find it when reading front to back.
Yes, the language reference started is still omnium-gatherum. There is a slow process to refine it.
I guess so… But maybe we can do something about it? /cc @bcardiff
I agree this separation isn’t helpful. Might be for someone with a lot of experience, or for implementers of the compiler and tools. For anyone fairly new, who likes the language overall but hasn’t been metaphorically up and down every street twice, it’s not obvious where to look up a feature one wants to use, such as array <<. It’s a new language, with only a few knowing about it since its creation, but many of us finding out about it and liking it for all kinds of reasons. So I don’t expect a lot of complete coherent documentation yet. At version 0.32, I’m not expecting such things. It will be a challenge to get basic things done.
Knowing what you can do and not do with an Array, or Struct, or any entity in the language, the basic examples, appending, getting the size, etc. need to be covered coherently from a new Crystal coder’s point of view. If I had $$$ I’d donate to any effort to write an open source tutorial or how-to reference.
Right now I’m using Crystal to generate my submission to a Kaggle competition. If I win, you bet I’ll put some % of the booty into Crystal documentation :)
I’m new in Crystal and I don’t know the Ruby syntax. I am at the introduction of the reference doc.
For new ones like me in Crystal, this is helpful https://exercism.io/my/tracks/crystal