Elixir language reference

Questions / Help
1

Where can I find a proper Elixir language reference manual? Need it for courses. The web site is very much a tutorial, as are the books.

6 Likes
2

These seem to have all the reference documentation:


http://elixir-lang.org/docs/stable/elixir/Kernel.html

3 Likes
3

From any page of the elixir documentation you can access the Pages section of the documentation, it has 5 or 6 subsections, which one can use as ref-man, also some modules do hide some ref-man style knowledge.

What is not available (but you probably ask for) is a refman as you are used to from erlang, which you could use as a formal spec as well.

3 Likes
4

Yes, but these document the libraries but not really the language itself, either syntax or semantics.

3 Likes
5

Yes, exactly. While the erlang documentation has its faults, it is very good as a reference manual, both for syntax and semantics. And not just the language but the OTP system and libraries as well.

5 Likes
6

From the IEx shell, it is possible to obtain a concise list of spec and type info per module, via the commands ā€˜tā€™ and ā€˜sā€™:

t Enum
@type t() :: Enumerable.t()
@type element() :: any()
@type index() :: non_neg_integer()
@type default() :: any()

s Stream
@spec chunk(Enumerable.t(), pos_integer(), pos_integer(), Enumerable.t() | nil) :: Enumerable.t()
@spec drop(Enumerable.t(), non_neg_integer()) :: Enumerable.t()
@spec flat_map(Enumerable.t(), (element() -> Enumerable.t())) :: Enumerable.t()
@spec map(Enumerable.t(), (element() -> any())) :: Enumerable.t()

---- although I am not sure if this is what you are asking for.

3 Likes
7

I guess @rvirdingā€™s point is about syntax and semantics. There is no reference guide for it at all, just some tutorial guides.

3 Likes
8

I was wondering the same thing, for similar reasons that @rvirding mentioned.

When I began programming some years ago, I would use books, tutorials and fragments of information that often were either too verbose or not sufficiently to-the-point (when not flat-out misleading), when I wanted to gain some in-depth understand a specific point in the language.

Ever since I learned formal language and compiler design a couple of years ago, I tend to first search the formal spec of a language when I want to understand how a certain feature of the language works, as it is both fairly complete and fairly concise.

I am fairly new to Elixir, and having such reference could speed up my learning and understanding of specific features.

I also consider suggesting the professor who teaches distributed programming at my local university (currently taught with Erlang) to try using Elixir as an experiment for a semester. I heard that a lot of the students are struggling with the Erlang syntax and am hoping that by using Elixir they can spend more time studying the principles of distributed programming, since I, too, find its syntax and behavior much easier to understand.

4 Likes
9

Sort of, itā€™s a start anyway. Though I personally donā€™t like reading it in the shell; same with module and function documentation. At least not long long long descriptions.

2 Likes
10

@rvirding can you be more precise on what you want? I will be glad to write the missing pieces. If you have examples of other languages, that would help.

About syntax, there is no reference, and I could write one up.

About the language semantics, most of it is defined in Kernel.SpecialForms. As you know, the parser doesnā€™t know about def, case, receive, defmodule and friends. So the documentation for those will be in Kernel.SpecialForms and Kernel.

4 Likes
11

For learning purposes, awhile ago I tried to organize all the standard library modules and their functions into a spreadsheet. It is messy, but if it helps, it is up on Github:

https://github.com/gbih/elixir-functions

At the time, I thought it would be fantastic if there were a single command in Elixir that would automatically generate such a list and pull in user-contributed examples. Perhaps a nice side-project someday.

2 Likes
12

Also for learning purposes I started writing a quick reference for syntax and stuff I find useful.

https://rkma.github.io/elixir/2016/11/15/syntax.html

3 Likes
13

Robert are you looking for something in BNF? Or would that be too low level for your purposes?

1 Like
14

My personal favorite - the The Elixir Cheat Sheet.
Another version - https://www.dropbox.com/s/lr1t87rw4wfnyb3/elixir-cheat-sheet-v2.pdf?dl=0

2 Likes
15

I think you need a reference manual for the language. Now most of what most people (me anyway :slight_smile:) would consider language constructs are described in Kernel and Kernel.SpecialForms as if they are function/macro calls, not as language constructs. I know that this is what they really are, and that sometimes this is important, but for describing ā€œthe languageā€ this does not make sense. Yes, there are tutorials and books that are good but somewhere I need a reference of the language, or at least what I perceive as being ā€œthe languageā€.

The Erlang reference manual is not too bad in this respect. It is not a formal language description but it systematically goes through all the language constructs. I can find each construct, or group of constructs, and see what they should look like and what they do. For example I can see all the arithmetic operators grouped together with a simple description of what each does. I can also see the relative priorities. You can also link into the module documentation when necessary.

I think being able to group constructs is a useful thing with a reference manual. For example I could see everything about defining macros in one place and get better feeling for how they work together. Or everything about modules in one place.

Another problem with Kernel and Kernel.SpecialForms is that they differentiate between functions and macros which is generally not that interesting for users. It is correct and relevant when describing these modules but not when describing the language. For me the user it is not interesting that case is a macro.

I think the difference between a tutorial/book and a reference manual is that the reference manual is a more structured description while the tutorial/book are often more example driven. You need both but for different things.

I hope this wasnā€™t too garbled.

6 Likes
16

Only things in Kernel.SpecialForms are the things handled by the compiler. The Kernel module is implemented in Elixir itself. This makes it in some ways hard to differentiate between language constructs and syntax extensions built using macros. Should whole Kernel module be considered language constructs?

I think it might be useful to have a grouped ā€œindexā€ of sort in the Kernel module docs, similar to what we do for Ecto.Query.API. It gives a nice overview with links to the particular documentation of each macro.

About the macro/function distinction in documentation, I saw a proposal to change ex_doc to get rid of it and have it all together.

1 Like
17

In my opinion no. Iā€™m with @rvirding. A proper reference of the language is important. This is something Python does well: even though python is an ungodly mess of runtime metaprogramming, the syntax is simple and explained in the language guide. The same guide also teaches you to de.sugar things until you hit the very basics

Iā€™m starting to get comfortable with elixir (enough to build web apps, genservers, mix tasks, etc.), and it is becoming a little scary how little I know about what is syntax and what are macros.

1 Like
18

In 1.5 the docs gained some new pages (and expanded some of the old ones):

This forms a large part what I would understand as a ā€œlanguage referenceā€.

Together with the:

This covers most, if not all, things youā€™d be facing using Elixir day-to-day.

7 Likes
19

As nice as macroā€™s are being called just like functions that allows easy conversion to/from macro or def implementations, I do kind of wish that macroā€™s had to be called with, say, a bang on the end, so something!() would be calling a macro named something and something() would be a normal function call similar to how other languages do (consequently I really dislike that bang functions in elixir are used to represent throwing variants, but it is a common style now, blehg, matching should be the causes of such raises or better constructs like smarter piping). It would be easier for newbies as it makes it obvious then what is a call compared to what mutates code (similar to rust for example, bang calls are macroā€™s there as one example).

20

That would be tiresome really quickly if you consider how much of elixir is macros - and thatā€™s skipping the defmodule and def - and, or, and not operators are macros. So is the in operator and if expression. This would mean the average of ! in Elixir programs could start to match the number of $ in PHP.

3 Likes