Support importing class names in .ag files

[tomokinakamaru]

Support importing class names in .ag files

[tomokinakamaru]

Thanks! Now I will move on to the implementation and let you know when it's ready for your review :)

[bannmann]

It works great, thank you! My AG file looks way better now.

Note that I won't push that change before the next Silverchain release is published as my CI build is not (yet) configured to use snapshots. But you don't have to hurry with that, at least not for me. 😉 I have two other feature ideas that you might agree to implement and which could also be included in 0.2.0. I just have to take the time to write proper issues for them.

[tomokinakamaru]

.ag files are quite verbose because one has to use fully qualified class names.

Agree, we definitely need something like the import statements in Java.

---

I first thought that your idea was little confusing because it imports a class that is defined after the import statement:

import org.example.math.MatrixBuilder; // <- importing MatrixBuilder

MatrixBuilder<;R extends Size, C extends Size> { // <- MatrixBuilder is defined here!
  ...
}

To fix this problem, I came up with the following alternatives, but none of them is quite good.

Idea 1: Introduce package statement

My first idea is to introduce the package statement:

package org.example.mapbuilder;
import java.util.Map;
MapBuilder<;K, V> {
  Map<K, V> put(K key, V value)* build();
}

(+) This looks just like Java.

(+) Not importing a class that is defined later, while reducing the verbosity.

(-) Cannot define fluent APIs across packages. For example, if one wants to generate org.example.mapbuilder.MapBuilder and org.example.listbuilder.ListBuilder, he/she needs to create two .ag files.

Idea 2: Introduce package block

My second idea is to introduce package blocks as follows:

org.example.mapbuilder {
  import java.util.Map;
  ...
}
org.example.listbuilder {
  import java.util.List;
  ...
}

(+) Not importing a class that is defined later, while reducing the verbosity.

(+) One can define fluent APIs across packages in a file.

(-) This does not look like Java.

Idea 3: Use another word instead of import

My final idea is to use a word instead of import. I haven't come up with a good one, but for example:

use org.example.mapbuilder.MapBuilder;
use java.util.Map;
MapBuilder<;K, V> {
  Map<K, V> put(K key, V value)* build();
}

(+) Not importing a class that is defined later, while reducing the verbosity if we find a good word.

(-) This does not look like Java (but better than Idea 1 and 2).

---

After all, I found that your original idea is not so confusing and better than my ideas. What I would like to ask you is that, do you still think introducing the import statements is the best solution? My preference is (your idea) > (Idea 2) > (Idea 1) > (Idea 3), considering the similarity to the Java syntax and the clarity of new syntax.

[bannmann]

Yes, I still think that import statements are the best solution - especially in terms of similarity to Java (and thus easiness to explain it to users) and being easily memorizable.

Granted, the fact that you import a class before defining it is a little bit weird. However, I think the chance of confusion is negligible because it is quite obvious to the user that despite its syntactical similarities to Java, the AG language is an entirely different beast. Also, Java itself violates the classic "define, then use" ordering in many places: for example, it is totally valid to call a method defined later in the same file or to use a non-public top-level class that is defined in the same file, but below the current class.

Before filing this issue, I briefly considered introducing a package declaration (and/or even mandating placement of AG files in a directory hierarchy like Java files), but quickly realized that it would not work: The generated files are placed in stateX packages, outside the package that you declared, and would therefore need import statements of their own. However, given an unqualified name from the AG, Silverchain could not easily know whether you mean a class in your package (maybe one from the non-generated sources) or one from java.lang. Having imports and using them even for the class names you define(d), neatly solves this problem.

[tomokinakamaru]

@bannmann I implemented the support for importing class names in the branch import-statement, so would you check the feature with your .ag files? If it works fine, I will merge PR #64 into the main branch :)

[tomokinakamaru]

Yes, let's publish v0.2.0 after we add more features :) I appreciate your constant contribution!