Port Vala for Java Programmers Developer Guide

source/developer-guides/documentation/vala-for-java-devs.rst

@@ -0,0 +1,13 @@
+Vala for Java Developers
+========================
+Vala is an object-oriented programming language with a syntax that is very similar to Java. As a Java developer, you will find many familiar concepts and constructs in Vala, making it easier to learn and transition to this language.
+
+Despite these similarities, there are also some differences between Vala and Java, such as Vala's use of reference counting for memory management instead of garbage collection..
+
+Throughout this guide, we will explore the similarities and differences between Vala and Java, helping you leverage your Java knowledge to quickly become proficient in Vala programming.
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   vala-for-java-devs/*

source/developer-guides/documentation/vala-for-java-devs/01-source-file-and-compilation.rst

@@ -0,0 +1,81 @@
+Source File and Compilation
+============================
+
+Source Files
+------------
+
+Java: ``*.java``
+
+Vala: ``*.vala``
+
+Compilation
+-----------
+
+Java: compiled to JVM byte code (``.class`` files)
+
+.. code-block:: bash
+
+   $ javac SourceFile1.java SourceFile2.java
+
+Vala: compiled to native code via C code as intermediate code
+
+.. code-block:: bash
+
+   $ valac source1.vala source2.vala -o program
+
+Vala's standard object system is GObject, compiled Vala libraries are valid C libraries.
+
+Using Libraries
+---------------
+
+Java: ``.jar`` files
+
+.. code-block:: bash
+
+   $ javac -classpath foo-1.0.jar;bar-3.0.jar SourceFile.java
+
+Vala: packages (C libraries with ``.vapi`` files)
+
+.. code-block:: bash
+
+   $ valac --pkg foo-1.0 --pkg bar-3.0 source.vala
+
+Java:
+
+.. code-block:: java
+
+   import javax.swing.*;
+
+   package org.foo.bar;
+
+   // ...
+
+Vala: namespaces, not related to directory hierarchy, no reverse domain name scheme
+
+.. code-block:: vala
+
+   using Gtk;
+
+   namespace Foo.Bar {
+       // ...
+   }
+
+Vala namespaces may contain methods without classes. They are implicitly static.
+
+Default Import
+--------------
+
+Java: package ``java.lang.*`` imported by default
+
+Vala: namespace ``GLib`` imported by default
+
+Main Entry Point
+----------------
+
+Java: ``public static void main(String[] args)``
+
+Vala: ``static int main (string[] args)``
+
+May be outside a class, may be private, may return ``int`` (exit code), ``args`` argument is optional
+
+INSERT IMAGE HERE

source/developer-guides/documentation/vala-for-java-devs/02-simple-data-types.rst

@@ -0,0 +1,47 @@
+Simple Data Types
+=================
+
+Basic Types
+-----------
+
+In Vala, the sizes of standard types (``int``, ``long``, etc.) are architecture-dependent. To get the size of a type in bytes, you can use the ``sizeof`` operator. For example:
+
+.. code-block:: vala
+
+   int size = sizeof (int);
+
+Vala provides additional types with architecture-independent guaranteed sizes:
+
+- Signed: ``int8``, ``int16``, ``int32``, ``int64``
+- Unsigned: ``uint8``, ``uint16``, ``uint32``, ``uint64``
+
+Note that there is no ``byte`` type in Vala. Instead, you can use ``uint8`` or ``int8``.
+
+Vala uses ``bool`` instead of ``boolean`` for boolean values.
+
+Vala also has an additional basic type called ``unichar``, which represents a Unicode character.
+
+Constant Modifier
+-----------------
+
+In Vala, the ``const`` keyword is used to declare constants, similar to ``final`` in Java.
+
+
+Methods on Basic Types
+----------------------
+
+Vala's basic types have methods that can be called directly on the values. For example:
+
+.. code-block:: vala
+
+   int a = (-4).abs ();
+   string s = a.to_string ();
+   int b = int.max (5, 7);      // static method call on 'int'
+
+In the above code:
+
+- ``(-4).abs ()`` calls the ``abs`` method on the integer value ``-4``, returning its absolute value.
+- ``a.to_string ()`` converts the integer ``a`` to a string representation.
+- ``int.max (5, 7)`` calls the static ``max`` method on the ``int`` type, returning the maximum value between ``5`` and ``7``.
+
+These are just a few examples of the methods available on Vala's basic types.

source/developer-guides/documentation/vala-for-java-devs/03-strings.rst

@@ -0,0 +1,34 @@
+Strings
+========
+
++------------------+---------------------------+
+| Java             | Vala                      |
++==================+===========================+
+| Data type: String| Data type: string (lower  |
+|                  | case)                     |
++------------------+---------------------------+
+| Equality test:   | Equality test:            |
+| str1.equals(str2)| str1 == str2              |
++------------------+---------------------------+
+
+String comparisons compare content, not reference. You can compare strings lexicographically with ``<``, ``>``, ``<=``, ``>=`` etc. Strings can be used with switch.
+
+Vala strings are UTF-8 encoded.
+
+Vala supports verbatim strings: ``"""..."""``
+
+.. code-block:: vala
+
+   string verbatim = """Verbatim strings don't evaluate escape sequences 
+   like \n, \t, ... and may span multiple lines. 
+   The line breaks are part of the string. 
+   You can use quotation marks (") and backslashes (\) 
+   inside a verbatim string without escaping them.""";
+
+Vala supports string templates: ``@"..."``. String templates may contain expressions, prefixed by a ``$`` sign.
+
+.. code-block:: vala
+
+   string name = "John";
+   stdout.printf (@"Welcome, $name!");
+   stdout.printf (@"3 + 2 = $(3 + 2)");

source/developer-guides/documentation/vala-for-java-devs/04-arrays.rst

@@ -0,0 +1,44 @@
+Arrays
+======
+
+Dynamic Growth
+--------------
+
+You can add elements to arrays dynamically by using the ``+=`` operator. The array will be reallocated with sizes of powers of two:
+
+.. code-block:: vala
+
+    int[] squares = {};
+    for (int i = 0; i < 100; i++) {
+        squares += i * i;
+    }
+
+No Boundary Checking
+--------------------
+
+However, there is no runtime boundary checking for arrays in Vala:
+
+.. code-block:: vala
+
+    int[] a = new int[10];
+    a[20] = 1;  // not safe!
+
+(Optional boundary checking is planned for a future version of Vala.)
+
+Multi-Dimensional Arrays
+------------------------
+
+Java: jagged multi-dimensional arrays ``[][]`` (arrays of arrays)
+
+.. code-block:: java
+
+    int[][] matrix = new int[3][];
+    for (int[] row : matrix) {
+        row = new int[4];
+    }
+
+Vala: rectangular multi-dimensional arrays ``[,]``, ``[,,]``, etc. (allocated as one contiguous memory block), jagged array support planned
+
+.. code-block:: vala
+
+    int[,] matrix = new int[3,4];

source/developer-guides/documentation/vala-for-java-devs/05-naming-conventions.rst

@@ -0,0 +1,44 @@
+Naming Conventions
+==================
+
+Java
+----
+
+* classes, interfaces, enums: ``CamelCase``
+* methods, local variables, fields: ``mixedCamelCase``
+* constants, enum values: ``UPPER_CASE``
+
+Example:
+
+.. code-block:: java
+
+    public class MyClass {
+        private static final int MAX_VALUE = 100;
+        private String myField;
+
+        public void myMethod() {
+            int localVariable = 42;
+        }
+    }
+
+Vala
+----
+
+* classes, interfaces, structs, enums, delegate types, namespaces: ``CamelCase``
+* methods, local variables, fields, properties, signals: ``lower_case``
+* constants, enum values: ``UPPER_CASE``
+
+Example:
+
+.. code-block:: vala
+
+    public class MyClass {
+        private const int MAX_VALUE = 100;
+        private string my_field;
+
+        public void my_method() {
+            int local_variable = 42;
+        }
+    }
+
+No non-ASCII letters for identifiers allowed. You can use Vala keywords as identifiers if you prefix them with ``@``. The at sign is not considered as part of the name.

source/developer-guides/documentation/vala-for-java-devs/06-foreach.rst

@@ -0,0 +1,16 @@
+Foreach
+=======
+
+Java:
+
+.. code-block:: java
+
+    for (int i : numbers) {
+    }
+
+Vala:
+
+.. code-block:: vala
+
+    foreach (int i in numbers) {
+    }

source/developer-guides/documentation/vala-for-java-devs/07-inheritance.rst

@@ -0,0 +1,20 @@
+Inheritance
+===========
+
+Java: ``extends``, ``implements``::
+
+    public class Demo extends Foo implements Bar {
+        public Demo() {
+            super();
+        }
+    }
+
+Vala: colon followed by comma separated list, both for super class and interfaces::
+
+    public class Demo : Foo, Bar {
+        public Demo () {
+            base ();
+        }
+    }
+
+``super`` is called ``base`` in Vala.

source/developer-guides/documentation/vala-for-java-devs/08-methods.rst

@@ -0,0 +1,77 @@
+Methods
+=========
+
+Method overloading
+-------------------
+
+Java:
+
+.. code-block:: java
+
+    public class Demo {
+        public void draw(String text) { }
+        public void draw(Shape shape) { }
+
+        /* Method overloading + chaining for convenience methods with less arguments */
+        void f(int x, String s, double z) { }
+        void f(int x, String s) {
+            f(x, s, 0.5);
+        }
+        void f(int x) {
+            f(x, "hello");
+        }
+    }
+
+Vala:
+
+.. code-block:: vala
+
+    public class Demo : Object {
+        public void draw_text (string text) {
+        }
+        public void draw_shape (Shape shape) {
+        }
+
+        /* Method with argument default values */
+        void f (int x, string s = "hello", double z = 0.5) {
+        }
+    }
+
+Vala does not support method overloading because libraries written in Vala are intended to be usable by C programmers as well with meaningful function names.
+
+
+Method overriding
+-------------------
+
+Java:
+
+.. code-block:: java
+
+    public class Super {
+        public int myMethod(int x, int y) { }
+        public final void anotherMethod() { }
+    }
+
+    public class Sub extends Super {
+        @Override
+        public int myMethod(int x, int y) {
+            super.myMethod(x, y);
+            // ...
+        }
+    }
+
+Vala:
+
+.. code-block:: vala
+
+    public class Super : Object {
+        public virtual int my_method (int x, int y) { }
+        public void another_method () { }
+    }
+
+    public class Sub : Super {
+        public override int my_method (int x, int y) {
+            base.my_method (x, y);
+            // ...
+        }
+    }