Re: [Vala] Vala Bugfix Hackathon

[Frederik <scumm_fredo gmx net>]

pancake wrote:
> Yes, it's really sad to see that no one of the main developers can
> review patches,
> reply mails or so...
>
> I have more unreported bugs of vala-core, because I'm really losing the
> interest
> of publishing them if there is no interest to fix them (...)
>
> I really think a hackaton can solve this situation, but we need a reply
> from Jürg
> to reorganize the current dead situation of the project where only vapi
> commits
> are appearing in mainstream.
>
> Another solution would be to create a comunity branch of the main git
> repo and
> apply all those fixes there.

Everyone can have a complete repository fork with all revision history
on Github or Gitorious (or his local machine) without losing the ability
of merging changes at a later date. That's one of the blisses of a DVCS
like Git.

> For the hackaton... well I think there are many things we can do without
> vala-core
> devels.

Yes, if core developers do not have time at the moment something like
that must wait. I remember Jürg saying on IRC that he might have more
Vala time later in December.

> It's quite fun to hack on the source of vala, and I have managed
> to fix
> some problems in this way. I dont really think that i'm good with it,
> but maybe
> sharing those issues by irc we can try to solve these problems by our own.
>
> I think that the main points for the hackaton would be:
>
>  - Complete the documentation of the language (non-c#, non-java tutorial)
>    - there are some things not explained in the tutorial, like the stack
> allocated arrays, etc..
>    - we can probably start writing a book about vala, like the
> parrot/rakudo people is doing
>      http://rakudo.org/node/58

There was a discussion on this list about a Vala book. There were many
volunteers and ideas, but no one started writing ;)

http://www.mail-archive.com/vala-list gnome org/msg01963.html

A wikibooks stub was created:
http://en.wikibooks.org/wiki/Vala_Programming

>  - Documentation for CCodes

I have started to take some notes in a plain text file some time ago,
but did not have time to complete, format and publish them on the Vala
wiki. I can share it with the mailing list (see attachment). Perhaps
someone wants to format and improve it on a Vala wiki page.

>  - Fix VAPIs (I have seen some typos like 'Ccode' and I have some local
> updates for curses.vapi f.ex..)
>  - Review/report bug reports
>  - Submit patches to solve the bugs

BTW, you must post your patches in Bugzilla as attachment, not as
comment, otherwise they don't show up in the patch queue:

https://bugzilla.gnome.org/page.cgi?id=patchreport.html&product=vala&patch-status=none

> I'm missing something here?
>
> --pancake


Best regards,

Frederik

[CCode (cheader_filename = "")]

Tells Vala which header files it should include in the generated C code when a
member of the annotated entity (namespace, class, ...) is used.

Naming
======

[CCode (cname = "")]
--------------------

This attribute allows you to influence the mapping between Vala
names and C names.

  namespace Foo {
      public class Bar {
          [CCode (cname = "something_else")]
          public void method ();
      }
  }

Without attribute this method would map to the following C function:
  foo_bar_method ();
However, with attribute it is:
  somethong_else ();

You can use this attribute for bindings of C libraries in order to make their
symbols fit into the Vala scheme (especially useful for non-GObject libraries).

[CCode (const_cname = "")]
[CCode (cprefix = "")]
[CCode (lower_case_cname = "")]
[CCode (lower_case_cprefix = "")]
[CCode (upper_case_cname = "")]

Arrays
======
[CCode (array_length = false)]

Vala represents an array in C code with two variables -- the array pointer and
the array length.  So `int[] numbers` becomes something like this:

  gint* numbers;
  gint numbers_length;

Whenever an array is passed as an argument to a function Vala will generate
two arguments in C -- the array pointer and the array length.

  // Vala function with array argument
  void print_numbers (int[] numbers)
  // translated into C code:
  void print_numbers (gint* numbers, gint numbers_length)

A function returning an array will return the length of the array by reference
as the last argument in C:

  // Vala function with array return value
  int[] get_numbers (bool foo)
  // translated into C code:
  gint* get_numbers (gboolean foo, gint* length)  /* <-- out parameter */

If Vala should not generate a length argument you must annotate the array with
`[CCode (array_length = false)]`.

[CCode (array_length_type = "")]

Describes the type of the array length argument (see above). By default it is
'gint'. 'gsize'

[CCode (array_null_terminated = true)]

This attribute is usually combined with [CCode (array_length = false)], because
arrays without a length variable are usually `null` terminated. This way Vala
can still determine the length of an array by counting its elements.

If an array does not have length information and if it's not `null` terminated
Vala will set its length to -1.

Classes
=======

[Compact]
---------

The [Compact] attribute marks so-called compact classes. You will most likely
use compact classes when you want to bind class-like structures of libraries
that are not GObject-based but still written in an object-oriented manner.

You can identify compact classes in the C header file of a non-GObject-based
library by the following signs:
- a data structure (struct)
- a function that allocates memory on the heap for this data structure and
  returns a pointer
- several functions that operate on this data structure ("methods")
- a function that deallocates the memory ("free function")

For example:

  typedef struct _Foo {
      /* ... fields ... */
  } Foo;

  Foo* FooCreate ();                              /* "constructor" */
  void FooSetPosition (Foo* foo, int x, int y)    /* "methods" */
  void FooWrite (Foo* foo, const char* text)
  void FooDelete (Foo* foo);                      /* "free function" */

You can bind it like this:

  [Compact]
  [CCode (free_function = "FooDelete", cprefix = "Foo")]
  public class Foo {
      [CCode (cname = "FooCreate")]
      public Foo ();
      public SetPosition (int x, int y);
      public Write (string text);
  }

If you want to 'valafiy' the method names you can do that with additional
'cname' annotations:

  [Compact]
  [CCode (free_function = "FooDelete")]
  public class Foo {
      [CCode (cname = "FooCreate")]
      public Foo ();
      [CCode (cname = "FooSetPosition")]
      public set_position (int x, int y);
      [CCode (cname = "FooWrite")]
      public write (string text);
  }

The [Compact] attribute says it's a non-GObject-based class. The free function
is specified with a separate attribute. Creation functions are usually mapped
to constructors.

Note that a 'char*' becomes 'string' in Vala when it is meant to represent a
string.

[CCode (ref_function = "")]
[CCode (unref_function = "")]
-----------------------------

Usually [Compact] classes of non-GObject-based libraries do not support
reference counting. However, some do. For example, the Cairo graphics library
which is actually not a GObject-based library. With these attributes you can
tell Vala which functions it should use for reference counting.

[CCode (ref_sink_function = "")]

To sink floating references. TODO: explain

[CCode (free_function = "")]

Specifies the function that will be called when the owning reference of a
compact class object gets out of scope.

[CCode (copy_function = "")]
[CCode (dup_function = "")]

[CCode (type_id = "")]
[CCode (has_type_id = false)]
[CCode (marshaller_type_name = "")]
[CCode (default_value = "")]
[CCode (type_signature = "")]                   // D-Bus
[CCode (param_spec_function = "")]
[CCode (set_value_function = "")]               // For types that can be boxed into a GValue
[CCode (get_value_function = "")]               // For types that can be boxed into a GValue

Structs
=======
[SimpleType]
[BooleanType]
[FloatingType (rank = 0)]
[IntegerType (rank = 6, min = 0, max = 255)]
[CCode (destroy_function = "")]
[CCode (copy_function = "")]
[CCode (has_destroy_function = false)]
[CCode (has_copy_function = false)]

Methods
=======

[CCode (instance_pos = 0.1)]
----------------------------

This attribute specifies the position of the implicit instance argument of an
instance method. Take this method for example:

  public class Demo {
      public void method (int a, int b, int c) {
      }
  }

Translated to C code it will look like this:

  void demo_method (Demo* self, gint a, gint b, gint c);

The instance is implicitly passed as first argument (often called 'self').
However, with [CCode (instance_pos = ...)] you can influence the position of
the instance argument.

The rules are as follows: No annotation at all means the instance is passed
as first argument. A negative instance position (usually -1) means the instance
is passed as last argument. A decimal number that lies between two integer
numbers n and n + 1 (for example 1.5) means that the instance is passed as
argument between the n-th and (n+1)-th argument. Examples:

No annotation or (0 <= instance_pos < 1):
  void demo_method (Demo* self, gint a, gint b, gint c);
(1 < instance_pos < 2):
  void demo_method (gint a, Demo* self, gint b, gint c);
(2 < instance_pos < 3):
  void demo_method (gint a, gint b, Demo* self, gint c);
(3 < instance_pos < 4):
  void demo_method (gint a, gint b, gint c, Demo* self);
(instance_pos < 0):
  void demo_method (gint a, gint b, gint c, Demo* self);

If instance_pos is an integer value no instance argument will show up at all.
This is useless, since in this case you should declare the method static.

[PrintFormat]
[ScanfFormat]
-------------

These attributes mark printf-like and scanf-like functions, i.e. functions that
expect a format string argument and a variable-length list of arguments. For
example, `message (string format, ...)`.  By annotating a function with one of
these attributes you tell Vala that the function is of this nature, and Vala
will ensure at compile-time that the types of the arguments match the ones
specified in the format string.

[NoReturn]                                              // For assertions etc.
[CCode (sentinel = "")]                 // ???

[Diagnostics]
-------------

This attribute marks logging/debugging functions. Vala will prepend the Vala
source file name and the line number of the function call to the string
argument.

  [Diagnostics]
  void diag (string message) {
      stdout.printf ("%s", message);
  }

  void main () {
      diag ("FAIL\n");
  }

Will result in

  demo.vala:7: FAIL

This attribute is used for the various GLib logging functions (`message()`,
`critical()`, `error()`, ...).

[ReturnsModifiedPointer]
------------------------
This is a highly specialized attribute. It means that the returned reference
should be treated as the new instance of the object the method was called upon.

For example, if you bind this C function

  Foo* foo_bar (Foo* self);

like this:

  public class Foo {
      [ReturnsModifiedPointer]
      public void bar ();
  }

then a call of

  foo.bar ();

will modify the 'foo' reference itself to the reference returned by the C
function. This behaviour is needed for binding ''GLib.List'' and
''GLib.SList'' methods.


Construction Methods
====================
[CCode (type = "")]
[CCode (has_construct_function = false)]

Delegates
=========
[CCode (has_target = false)]

Properties
==========
[CCode (notify = false)]
------------------------
A property annotated with this attribute won't emit a `notify` signal each time
its value has changed.

[Property (nick = "", blurb = "")]

Virtual Methods
===============
[NoWrapper]

Properties
==========
[NoAccessorMethod]

Usually GObject properties have so-called accessor methods. For example,
the 'label' property of class 'GtkButton' has the C accessor methods
'gtk_button_get_label()' and 'gtk_button_set_label()'. Vala uses these methods
when accessing a property. However, sometimes these accessor methods are missing
in the C API. In this case the property must be accessed with
'g_object_set (button, "label", ...)' and 'g_object_get (button, "label", ...)'.
In order to make Vala aware of such a property that is lacking accessor methods
you must annotate it with the [NoAccessorMethod] attribute in your bindings.

Signals
=======
[HasEmitter]

Signals are usually emitted in GObject/C with
'g_signal_emit_by_name (obj, "signal-name")'. However, sometimes signals provide
their own additional emitter function. For example, the 'clicked' signal of
class 'GtkButton' has the emitter function 'gtk_button_clicked()'. If you
annotate a signal with the [HasEmitter] attribute in your bindings, Vala will
call the emitter function instead of 'g_signal_emit_by_name()' in order to emit
the signal.

Enums
=====
[Flags]

Other
=====
[ByRef] ??
[InstanceByReference]
[Immutable]
[ErrorBase]  only used for GLib.Error

Deprecated
==========
[NoArrayLength]     => [CCode (array_length = false)]
[InstanceLast]      => [CCode (instance_pos = -1)]
static delegate ... => [CCode (has_target = false)] delegate ...
[PlusOperator] ??