Proposed structure

bin/adlc

lib/adl/std                        -- std library
lib/adl/std/adlast.adl
lib/adl/std/types.adl
lib/adl/std/types.adl-java                  -- custom type overrides
lib/adl/std/types.adl-hs
lib/adl/std/types.adl-cpp

lib/adl/sys/                       -- implementation details
lib/adl/sys/config/java.adl
lib/adl/sys/config/haskell.adl
lib/adl/sys/config/cpp.adl

ADL can then have examples like:

/// A Map with String keys and values of type T/
///
/// Serialised as a JSON object with string keys, ie
///  JSERIALIZE{ StringMap<T> } -> JsonObject<JSERIALIZE{<Serialise<T>}> 

newtype StringMap<T> = Primitive;

and backends will fail if they need to use such a type without a custom mapping.

Over time we can consider reducing the set of hard coded builtin primitives, and replacing them with newtypes like the above.

According to this:

http://docs.oracle.com/javase/6/docs/api/java/lang/Object.html#equals%28java.lang.Object%29

x.equals(null) should always return false.

It would be useful to some intelligent truncation to the adl output or add colorisation so the messages are easier to sift through.

I'm not sure if complementary is the word here (invertible maybe?)

If I declare a union such as this:

union GraphType {
  Void area;
  Void line;
  Void zones;
  Void onoff;
};
struct Foo {
   GraphType graphType;
};

It reads it in from json as for example "graphType": "area"

but when it serialises back to json it becomes

"graphType": {
   "disc": "AREA"
}

It seems like serialisation and deserialisation should be the reverse of each other?

The idea is that void branches in a sum type will be serialised just by the name, whereas other branches will be a single field object. ie this union

union Maybe<T>
{
    Void nothing;
    T just;
};

will serialize to "nothing" or {"just" : ...}.

As opposed to alphabetical sorting

Currently, annotations of the Void type needs to specify null as the serialized value, e.g.

newtype Localizable = Void;

struct MyStruct {
    @Localizable null
    String name;
}

Since there can only be one value for a Void type, it would be good to make this implicit and allow annotations like so:

@Localizable
String name;

As an example, currently if you define an enum with a wrong value the deserialiser just throws an "IllegalStateException". It would be useful to have some more verbose error message here (i.e. which enum resulted in the error and what the value was).

Unlike other language backends it is envisaged that a javascript backend won't generate type definitions - rather it will generate records of auxiliary functions to assist with each ADL type. For example, given this ADL:

module mymodel
{
  struct User
  {
     String name;
     String address;
     Int32 age;
  };
};

We might generate code like:

//----------------------------------------------------------------------
// adl/primitives.js   (hand written library code)

var String = {
  validate : function(v) {return typeof(v) == "string";},
  default : function() {return "";},
  copy : function(v) {return v;},
  equal : function(v1, v2) {return v1 == v2;}
};

var Int32 = {
  validate : function(v) {return typeof(v) == "number";},
  default : function() {return 0;},
  copy : function(v) {return return v;},
  equal : function(v1, v2) {return v1 == v2;}
};

//----------------------------------------------------------------------
// mymodel.js (machine generated)


var primitives = require('adl/primitives.js');

var User = {
  validate : function(v) {
    return primitives.String.validate(v.name)
      && primitives.String.validate(v.address)
      && primitives.Int32.validate(v.age);
  },
  default : function() {
    return {
      name : primitives.String.default(),
      address : primitives.String.default(),
      age : primitives.Int32.default()
    };
  },
  copy : function(v) {
    return {
      name : primitives.String.copy(v.name),
      address : primitives.String.copy(v.address),
      age : primitives.Int32.copy(v.age)
    };
  },
  equals : function(v1, v2) {
    return primitives.String.equals(v1.name, v2.name)
      && primitives.String.equals(v1.address, v2.name)
      && primitives.Int32.equals(v1.age, v2.age);
  }
}

Of course, there are lots of complexities to be dealt with:

• explicit defaults in the ADL
• generic types
• custom type definitions.

etc

Currently a command line argument is required for each file of custom type definitions. Instead, it would be better if custom type files were given specfic suffixes, and were loaded automatically if found on the search path, ie with files

sys/types.adl
sys/types.cpp.adlmap
sys/types.hs.adlmap
sys/types.java.adlmap

importing sys.types in the java backend would automatically load the custom types from sys/types.java.adlmap

specifically documentation strings to be embedded in the generated code

currently commented out in test4:

// FIXME: Should work, but gives error:
//        Invalid override of field v8a of S: literals not allows for parameterised fields
//
//    Map<String,Int32> v8a = [
//      { "v1" : "X", "v2" : 1 },
//      { "v1" : "Y", "v2" : 2 }
//      ];
};

Optional means the field can be absent (not null).

These fail:

stack ghc -- -icompiler/src compiler/tests/test6/hs-output/ADL/Test.hs
stack ghc -- -icompiler/src compiler/tests/test4/hs-output/ADL/Test4.hs

ie get rid of Void instances being passed around.

Not sure if you're aware of this - but PaymentMethod.hashCode() currently NPE's because the value instance variable is null. Since all members are Void, then maybe we don't need a value variable? Or we can do a null check in hashCode().

Issue discovered in the test introduced in this commit: bceecc5

https://github.com/timbod7/adl/blob/44a37a7094310482e883f2ff367fdf217c62b13a/haskell/compiler/src/ADL/Compiler/Backends/Java/Json.hs#L240
https://github.com/timbod7/adl/blob/960d2c8d5b378d1efa8adf5f7a54d59f45fa933a/haskell/compiler/src/ADL/Compiler/Backends/Java.hs#L440
https://github.com/timbod7/adl/blob/960d2c8d5b378d1efa8adf5f7a54d59f45fa933a/haskell/compiler/src/ADL/Compiler/Backends/Java.hs#L489
https://github.com/timbod7/adl/blob/44a37a7094310482e883f2ff367fdf217c62b13a/java/runtime/src/main/java/org/adl/runtime/JsonBindings.java#L263
https://github.com/timbod7/adl/blob/44a37a7094310482e883f2ff367fdf217c62b13a/java/runtime/src/main/java/org/adl/runtime/JsonBindings.java#L268

It would be good to have fields that we can define as "not-null" and "not-default" which must be specified by the users (i.e. they don't have a default value). These should throw an exception if they are not specified during deserialisation.

ghc -fwarn-incomplete-patterns

The folllowing tests currently result in a stack overflow:

public class TestArrayRecursion {

   @Test
   public void testFactory(){
    Factory<Tree<String>> factory = Tree.factory(Factories.STRING);
   }

   @Test
   public void testJsonSerializer(){
     JsonBinding<Tree<String>> jbinding = Tree.jsonBinding(JsonBindings.STRING);
   }

};

(as would similar tests where the recursion is through a union).

Now that we have custom annotations, we need a file format in which we can specify annotations that get merged into the main ADL files. This will keep the ADL files clear as annotations are more widely used.

Exact format of file, and how those files get automatically discovered is yet to be determined.

• Use a FieldDetails structure akin to the java backend
• Delete the ADL/Compiler/Backends/Utils/Literals.hs using code in Processing.hs
• Consider using the IndentedCode.hs module

This would eliminate the need for the Literal type in adlast.adl along with code in the typescript backend to convert literals to json

Change from GPL to a more permissive license (BSD).

as defaults now relate to fields rather than types

Get rid of the json files for custom types, and use annotations instead.

E.g.

• @OverRide where appropriate e.g. on FACTORY & JsonBinding implementations
• Remove redundant type arguments e.g. new ArrayList() -> new ArrayList<>()

setters that return this

Inconsistency can cause name resolution to fail

i.e.

Map<String, String> foo = { "key1":"val1", "key2":"val2" };

instead of

Map<String, String> foo = [ {"v1":"key1", "v2":"val1"}, {"v1":"key2", "v2":"val2"} ];
v1/v2 rather noisy and implementation detail leaky

Issue discovered in the test introduced in this commit: bceecc5