crystal-lang / crystal-book Goto Github PK
View Code? Open in Web Editor NEWCrystal reference with language specification, manuals and learning materials
Home Page: https://crystal-lang.org/reference
License: Other
Crystal reference with language specification, manuals and learning materials
Home Page: https://crystal-lang.org/reference
License: Other
The section Passing a closure to a C function contains example code that does not compile.
See crystal-lang/crystal#5528 for initial report.
At the end of this page it says:
When a method specifies a splat (explained in the next section), named arguments can't be used. The reason is that understanding how arguments are matched becomes very difficult; positional arguments are easier to reason about in this case.
but then in the next section it says:
Arguments past the splat argument can only be passed as named arguments.
Since it seems that named arguments can be used with a splat, I think the last paragraph of the first page I linked should either be removed, or changed to say that positional named arguments cannot be used with a splat but non-positional named arguments still can.
The current section Types and Methods - Classes and Methods
is muddy.
Since methods can exist on their own, outside of classes, methods should be their own chapter. Classes as a following chapter can expand on methods.
Now that we're referring to this book as "language reference" instead of "documentation" (#78), we could reflect the change in the URI. This will hopefully reduce a frequent source of confusion for newcomers to the community: many expect to find under /docs
what we put under /api
.
The documentation on requiring files need to be changed to lib
instead of libs
.
I have a push request for this in the works that also clarifies how to get require
to use the right path since it took me a while to get it right.
For reference, see crystal-lang/crystal#321 and crystal-lang/crystal/pull/2788.
The current file does not explain what the difference is between blocks and procs.
I get the impression that a Block is a more primitive thing than a Proc. If that's true, at what point does a block become a proc?
How are these two things related?
I found that there is no content about spec, I have no idea about what spec is, is it like something about test module? Maybe it is better to have something about that. :)
Hi,
I'm willing to contribute helping to translate the Official Docs to Brazilian Portuguese (pt-br). Where can I find the repo for that translation http://br.crystal-lang.org/ ?
Review the whole book and change any mention to itself to "Language Reference"
The page Global Variables is obsolete and has been removed from the repository (e8d4843) but is still displayed on the public website.
It seems like the deployment to S3 doesn't take care of removed pages and leaves them accessible forever.
In the book it says that the following code does not work:
class Parent
@@counter = 0
end
class Child < Parent
def self.counter
# Error, can't infer the type of class variable
# '@@counter' of Child
@@counter
end
end
However, since v18 this is not the case anymore.
There is this example in the book:
if a.is_a?(String) && b.is_a?(Number)
# here a is a String and b is a Number
end
But what about using ||
in this scenario with the same variable?
if a.is_a?(String) || a.is_a?(Number)
# There is no guarantee that a is bound to anything?
end
In crystal-book/syntax_and_semantics/c_bindings/type.md one finds the following note:
Thus, a type declaration is useful for opaque types that are created by the C library you are wrapping. An example of this is the C FILE type, which you can obtain with fopen.
Any chance of some elaboration or clarification on that? I ran against this while (sigh) trying to make use of the OpenLDAP library, which has an opaque LDAP struct, and... I had and have no idea how to deal with that, despite this note. Just me?
ensure
must come after else
, but this is not specified on the exception handling page. In fact, that page actually defines ensure
before else
.
Related discussion with @RX14 on gitter
Andy Fleming @andyfleming 16:14
I say we break "Methods and instance variables” into “Instance Variables” and “Instance Methods”. Then we start with manual getters and setters, then introduce the shorthand and the
property
concept. It would be nice and clean. Then in the “Instance Methods” page, we can use the shorthand.
@RX14 16:14
hmm
i think "new, initialize and annlocate" should be merged into "methods and instance variables" somewhat too
that area of docs keeps coming up as a pain point
Andy Fleming @andyfleming 16:16
Yeah
allocate
seems like an advanced topic that shouldn’t be mixed in with creation of class instances
(though a mention/link might be appropriate)
Error: ENOENT: no such file or directory, lstat '/home/chun/.cache/mozilla/firefox/mwad0hks.default/cache2/entries/E4499943457122601C382ABE781A0BE6FE3585DF'
Just a heads up that the "Documenting Code" page still uses doc
instead of docs
. I was wondering why crystal doc
wasn't working! Also note that the default directory doc/
has been changed to docs/
as well.
I used ag to search for other occurrences of doc
and plan to submit a pull request that fixes this.
See original request: crystal-lang/crystal#4365
(Moved here from crystal-lang/crystal#3135)
I just noticed the documentation seems to be missing the description of the getter
/setter
macros. The property
macro is used in the Structs page though.
Also, I saw in source code that obj.@var
is valid, and I guess it's field access without "method call" (even if there was a getter method that might do something else in addition)? This syntax isn't explained either in the documentation.
Of course one can learn these things through other ways too. Just putting it out there so it won't get forgotten in case the documentation is supposed to be comprehensive. If wanted, and if my assumptions are correct, I could describe it somewhere. But I doubt my writing style is as beautiful as the one in Crystal's documentation. :)
The crystal book chapter on hooks doesn't include finished
:
Special macros exist that are invoked in some situations as hooks: inherited, included, extended and method_missing.
Should it?
I got the following messages when building the documentation.
I run it on ubuntu on windows 10 (WSL).
How to resolve this?
Live reload server started on port: 35729
Press CTRL+C to quit ...
info: 10 plugins are installed
info: loading plugin "ga"... OK
info: loading plugin "edit-link"... OK
info: loading plugin "offline"... OK
info: loading plugin "livereload"... OK
info: loading plugin "highlight"... OK
info: loading plugin "search"... OK
info: loading plugin "lunr"... OK
info: loading plugin "sharing"... OK
info: loading plugin "fontsettings"... OK
info: loading plugin "theme-default"... OK
info: found 132 pages
info: found 5 asset files
error: error while generating page "syntax_and_semantics/macros.md":
Template render error: (/mnt/c/p/crystal-book/syntax_and_semantics/macros.md) [Line 243, Column 9]
unknown block tag: end
Installation on Debian unlike on Ubuntu raises a few issues that is unique to only itself. Like the need for apt-transport-https. I personally had to Google a lot to install crystal. Would be great if the documentation be made more elaborate to suit a beginner .
I am willing to work on it. Should I?
While working with the amber framework, specifically reading the granite orm code I ran across the property keyword.
Searching the language docs I came up empty with much of an explanation as to what is going on. The search results point to two articles which use the keyword (Attributes and Structs) and three articles matched on stemming ("properties") but still did not give a concrete definition of the keyword and its purpose.
Crystal for Rubyists does clarify the meaning with it's table comparing it to Ruby's #attr_accessor, but I don't see this mirrored in the official documentation anywhere.
This seems like a hole in the documentation but I'd like to get a sign off from someone marked as a contributor about where and what the documentation should say about the keyword before submitting a doc pull request.
IMO It would be great it at the footer of each page an "edit page" link would link to the .md
source.
It will help for this repo discovery and will engage people to contribute.
The command literals `whoami`
and %x(whoami)
need to be documented.
In the Regex page, show an example of a regex literal scanning unicode.
Hey all, so far I have seen a vim plugin and a sublime text plugin. I think there should be a section on editor support in the docs. Happy to write it in.
$ gitbook build --gitbook=2.3.2
Installing GitBook 2.3.2
SOLINK_MODULE(target) Release/.node
CXX(target) Release/obj.target/fse/fsevents.o
SOLINK_MODULE(target) Release/fse.node
Error: Command failed: git clone --template=[[redacted]]/.npm/_git-remotes/_templates --mirror git://github.com/anthonny/opal-npm-wrapper.git [[redacted]]/.npm/_git-remotes/git-github-com-anthonny-opal-npm-wrapper-git-1727a7b3
Cloning into bare repository '[[redacted]]/.npm/_git-remotes/git-github-com-anthonny-opal-npm-wrapper-git-1727a7b3'...
fatal: repository 'https://github.com/github.com/anthonny/opal-npm-wrapper.git/' not found
See title.
Is there any available alternative to the --with-llvm
flag in the Homebrew installation of Crystal?
I'm currently working on translation of this repo to Korean. I'll keep working on that even if you won't accept the PR, mainly because I really love this language, but I want to make sure if my translations would be merged to this official repo.
I acknowledge that Crystal lang is still developping and therefore there are many changes to the document. I've updated with 5 commits made to the original repo after I forked it.
My former open source translation contributions include timeago.js, Learn X in Y minutes, Shattered Pixel Dungeon, and Latern. The forked repo is https://github.com/linterpreteur/crystal-book.
Thanks.
How does immutability work with constants?
Constants can invoke methods / expressions? So they can be assigned something at runtime, but cannot be re-assigned something?
Include more examples for this.
It would be helpful to have all the keywords of crystal language in a page.
Examples:
It would be helpful for people coming from other ecosystems to get the idea of available keywords.
this page doesn't seem to document then
.
For a new user of crystal, if they goto the website and click "LEARN", they are taken to this page: https://crystal-lang.org/docs/overview/
The flow of pages from there is:
puts
statement with some explanationThere are a few ways this could be improved. It may be that "LEARN" links somewhere else, instead of changing crystal-book
itself or these changes may improve the experience:
It may be best to have a different place for "LEARN" that is more tutorial style, similar to https://tour.golang.org
Until that can happen, perhaps improving the flow for this part of the guides is low-hanging fruit.
Right now it says "There are four signed integer types: Int8, Int16, Int32 and Int64, being able to represent numbers of 8, 16, 32 and 64 bits respectively."
I think it would be much better to show the range of values that can be represented with those classes. It makes for a far better explanation. I'm happy to write the revision myself, I just want to run it by the core team first.
When crystal-lang/crystal@e872c71 is released, the section should be removed.
The following command are needed for installing on Debian 9:
sudo apt-get install apt-transport-https dirmngr libssl-dev zlib1g-dev gcc
dirmngr is used by the current setup.sh script but is not default installed. Without this the shell script breaks and you can not even install crystal as a trusted source.
apt-transport-https and libssl-dev are used by the webserver example compilation
gcc is needed for the linker, no gcc = error during compilation
zlib1g-dev ... fixes compile error.
With any of them missing, its impossible to compile crystal on a fresh installed Debian 9 installation.
For WSL on Windows ( This may also apply to the Ubuntu installation seeing as WSL = Ubuntu ):
sudo apt-get install libssl-dev
If they are missing from the setup.sh script, Crystal will fail to install or compile for instance the web example on Debian/WSL/Ubuntu.
I need a better explanation of
local ||= 1 # same as: local || (local = 1)
local &&= 1 # same as: local && (local = 1)
Wouldn't this example code make more sense as
local ||= 1 # same as: local = local || 1
local &&= 1 # same as: local = local && 1
I'm still not sure of the use case for &&=
, but I'm pretty sure my comments make more sense than the original.
Am I way off here?
Hi, I found it spend lots of time on page changing (because they are different html page), can you provide one page version? Thanks.
The fresh_vars_sample(*names)
on https://crystal-lang.org/docs/syntax_and_semantics/macros/fresh_variables.html does not output
# Declaring: __temp_255
# Declaring: __temp_256
# Declaring: __temp_257
# __temp_255: 0
# __temp_256: 1
# __temp_257: 2
as the example claims, but instead output
Declaring: %name{index}
Declaring: %name{index}
Declaring: %name{index}
%name{index}: 0
%name{index}: 1
%name{index}: 2
(crystal 23)
Firstly thank you for the wonderfully thought out and designed resource.
I noticed that in methods_and_instance_variables.md there's a code snippet:
class Person
def initialize(@name : String)
@age = 0
end
end
Followed by:
Right now, we can't do much with a person: create it with a name, ask for its name and for its age, which will always be zero. So lets add a method that makes a person become older:
But - really - we can't query the state of @age
or @name
without using getter :age, :name
.
If you feel like this is big enough to address I can send a PR...perhaps...
Right now, we can't do much with a person aside from create it with a name. Its age will always be zero. So lets add a method that makes a person become older.
Continuing discussion from: crystal-lang/crystal#5002
See: https://crystal-lang.org/docs/syntax_and_semantics/literals.html
The regex section is causing the third column to be added. A quick workaround is to change the example to one that doesn't use |
.
Search usually works fine but for some search terms it fails and there are no results nor error messages on the page. For example, search for char
The JavaScript console shows this error:
lunr.min.js:7 Uncaught TypeError: Cannot read property 'tf' of undefined
at t.Index.documentVector (lunr.min.js:7)
at t.Index.<anonymous> (lunr.min.js:7)
at Array.map (<anonymous>)
at t.SortedSet.map (lunr.min.js:7)
at t.Index.search (lunr.min.js:7)
at LunrSearchEngine.search (search-lunr.js:34)
at Object.query (search-engine.js:31)
at launchSearch (search.js:79)
at handleUpdate (search.js:121)
at HTMLInputElement.<anonymous> (search.js:142)
According to olivernn/lunr.js#243 this might be caused by lunr.js having issues with unicode codepoints like emojis. There is an emoji (🔮) in the book on both pages about char and string literals and it fails to search for any terms that appear on one of these pages. I am not 100% sure about it, but this looks like strong evidence.
This failure should be fixed in lunar.js but until then, we should try to find a workaround for Crystal Book.
I think we could just remove the emojis from the pages. It's nice to have them there but they're not essential. Perhaps we could also manually remove them from the search index.
I believe it would be beneficial if the crystal reference had a section that explains how to use shards in a project. I tried searching shards update
, for example, and couldn't find any relevant information.
It may also help to:
shards --help
. This would also make it consistent with crystal --help
.My initial question: What is the difference between shards update
and shards install
? When I tested them, they both functioned identically to me so I wanted to know what they actually do.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.