Re: Newbie packagers

[Ricardo Wurmus <rekado@elephly.net>]

Hi Vincent,

> - the comma operator
> - the backquote operator
> - the quote operator
> - the arobase operator (is it for list unpacking ?)

These are all about list quoting.
This is code:

    (+ 1 2 3)

It evaluates to 6.

This is quoted code (aka data):

    '(+ 1 2 3)

It doesn’t get evaluated any further.
This is pretty much the same as:

    `(+ 1 2 3)

But with the backtick (called “quasiquote”) you are permitted to
temporarily switch from “data mode” to “code mode”.  That’s what the
comma (“unquote”) does:

    `(+ 1 2 3 4 ,(+ 3 2) 6)
    ^           ^
    data mode   code mode

The result is the same as

    '(+ 1 2 3 4 5 6)

What’s nice about this is that we can use the same syntax for code that
is to be evaluated right now and for code that we want to pass somewhere
else as inert data which will be evaluated at a later point.

This allows for “staging”.  When you look at a typical package
expression you see that the value of the “arguments” field is quoted.
It is not evaluated right away but in a second stage.

The value of the inputs field is also quoted.  You see that we unquote
the values of package variables there.  Package expressions in Guix are
just Scheme values.  The inputs field does not merely hold a list of
symbols that somehow represent the packages — it actually contains the
very values themselves!

“,@” is for splicing lists:

    (let ((moo '(1 2 3)))
      `(foo bar ,@moo meh))

This binds the list '(1 2 3) to the name “moo” and then splices it into
another list.  This results in

    '(foo bar 1 2 3 meh)

Without the “@” and just a regular unquote comma it would be a nested
list:

    (let ((moo '(1 2 3)))
      `(foo bar ,moo meh))

=>  '(foo bar (1 2 3) meh)

Quoting and unquoting is a very useful feature.  I hope my explanations
above are easy to understand.

> - the percent operator

That’s no operator.  It’s part of the name.  We use the percent as a
prefix for variables that are “special”, e.g. global variables or
values that appear without having to be explicitly let-bound.

> - the #: operator

These are called keyword arguments.  They are no operators either.
Using keyword arguments allows you to specify arguments by name, not in
some fixed order.

> - the different module import things (#:use-module vs (use-modules) vs ...)

That’s probably explained in the Guile reference manual.  We use
“#:use-module” only in module definitions.  “(use-modules …)” can be
used anywhere else.

> I tried to find a good tutorial explaining all of those, but couldn't. I found
> snippets that helped me understand some of those, but they were scattered,
> and it's still blurry.
>
> Specific explanations will be more useful that a general scheme tutorial, the
> hello.scm is good as an example :
>
> (inputs `(("gawk" ,gawk)))
>
> here we use the backquote because ...
> the comma is there for ...
>
> (arguments `(#:configure-flags '("--enable-silent-rules")))
>
> here the #: means ...
> we use the simple quote because ...

Yeah, I agree.  There should be a quick crash course.  I spent half the
day yesterday to introduce all these things to a colleague who will
create a few Guix packages in the future.  It would be cool to have this
as part of the manual.

~~ Ricardo