Documentation

[vladdu]

Could you please add a little more information about how the meaning of basic concepts in the framework, as well as how it is supposed to work? There are a lot of interesting things going on, but it's problematic to understand what some concepts are exactly about and if they are relevant or not for my language.

For example (but not limited to):

• what is a Bundle in a language's context?
• how do I plug in my own lexer/parser?
• what's a Lang Daemon?
• why use the non-standard Indexable, Collection2, ArrayList2 etc?
• there's a lot of casting up and down. The base operations have comments saying they are very unsafe, but the methods using them don't, so it's unclear how unsafe things are...

Reading the code can give some answers, but they are guesses and it's not clear if my understanding is correct (especially when it comes to the "why"s).

[bruno-medeiros]

I've added a terminology section: https://github.com/bruno-medeiros/MelnormeEclipse/blob/master/README-MelnormeEclipse.md#terminology , it explains Bundle and Lang Daemon.

Also added an explanation to the "Merging new updates from upstream MelnormeEclipse" section (although this shouldn't be an issue for someone just starting out, only later if you start merging future updates)

As for Indexable, Collection2, these are used to introduce more type-safety to our code. Indexable is essentially a read-only version of List, a Collection2 the read-only version of Collection. They are used to make sure client code doesn't modify the underlying collections.

ArrayList2 exists then to implement Indexable, and also adds some useful utility methods (mostly syntax sugar). I'll clarify the comments for these classes/interfaces.

[bruno-medeiros]

how do I plug in my own lexer/parser?

For syntax highlighting? That would be LANGUAGE_CodeScanner, and LANGUAGE_PartitionScanner. These follow the standard Eclipse way of doings things.

As for the parser. Well, depends, for what functionality do you mean? For outline functionality, for example, that would be LANGUAGE_SourceModelManager. You then have to transform the parser output (the AST), into a simplified SourceFileStructure. This is a structure with parse errors and structure elements. A structure element is just a description of top-level source definitions, like function/type/class/global definitions. This is used for the outline. Hum, I should clarify this in the code.

there's a lot of casting up and down. The base operations have comments saying they are very unsafe, but the methods using them don't, so it's unclear how unsafe things are...

I'm not sure what you are talking about here. What do you mean?

By the way, where did you hear about MelnormeEclipse?

[vladdu]

Thank you for the answers, it helps.

My first impression is of being somewhat overwhelmed, kind of like with DLTK: there is a lot of code and it's not clear where the configurable parts are. Also, until the framework will become more stable, it's unclear how much merging will be necessary. I feel that in practice people will be somewhat reticent to do it. It would be much nicer if the framework was independent of the customizations...

Re Indexable and Indexable, one could use Collections.unmodifiableCollection and Collections.unmodifiableList to create a similar result. The difference is that write access is detected at runtime, which the tests should capture.

[bruno-medeiros]

Re Indexable and Indexable, one could use Collections.unmodifiableCollection and Collections.unmodifiableList to create a similar result. The difference is that write access is detected at runtime, which the tests should capture.

Yup, I know, I added that note to https://github.com/bruno-medeiros/MelnormeEclipse/commit/83523005bcce09d456fa8b5173f2087963f11cd2#diff-e6b2b7f67265637541b9cd2a88f51944R28

[vladdu]

Re SourceModeManager and friends: I see, it's another concept that makes sense once explained but for me it was a bit of a steep curve...

Re casting: there is for example

    /** Casts given object to whatever type is expected. Use with care, this is very unsafe. */
    @SuppressWarnings("unchecked")
    public static <T> T blindCast(Object object) {
        return (T) object;
    }

which is used by for example ArrayList2.upcastTypeParameter(), but the latter doesn't have an unsafe warning.

I found a reference to MelnormeEclipse on the Eclipse forums, there's a note in the other ticket #2.

[bruno-medeiros]

My first impression is of being somewhat overwhelmed, kind of like with DLTK: there is a lot of code and it's not clear where the configurable parts are. Also, until the framework will become more stable, it's unclear how much merging will be necessary. I feel that in practice people will be somewhat reticent to do it.

Nearly all the starting points for configurable parts are the LANGUAGE_ classes. But I agree, it could use a map or guide to say which classes one should look at for each IDE functionality. It's a matter of me adding that information to the documentation gradually. (I've added this for now: https://github.com/bruno-medeiros/MelnormeEclipse/commit/0a59573de8a958b26d811cebd7b4ab06964fcaf4 )

As for merging, well the API might be unstable, but I think the framework itself (in terms of functionality and bugs, is fairly stable). Not bug-free of course, but good enough to be used. You can always take the current version of Melnorme, start using it to create you IDE, but let months pass without merging any update from Melnorme. In fact, if Melnorme had releases, that would be similar to what would happen. You'd get a new major release every 3-6 months or so, and then you'd have to update lots of API then (although probably less API changes in total than updating to every commit individually, yes).

Adding a proper API management could add a fair amount of work (and make the code harder to clean up and improve). As such, I've been doing things the "fast and furious" way: most of the time I don't even deprecate code and then remove it later: if I want to change some API I remove the old one straight away. I would be up for doing a smoother, more stable API management if there are projects (other than mine) that are using MelnormeEclipse in a serious way. But it adds work and complexity to me, so only worth it if API changes get to the point that it's actually a problem for other projects.

[bruno-medeiros]

ArrayList2.upcastTypeParameter(), but the latter doesn't have an unsafe warning.

There is a warning, but it's in the documentation of the interface method, I think you might have missed it:

[vladdu]

I understand your choice of going "fast and furious". Once there are users, then evolution becomes more difficult. And I'm not really criticizing, but pointing out that if I want to understand the basics of the framework before committing to it.

FWIW, what I had in mind to do myself was to just provide a template with all the extension points and abstract classes needed to provide editing support. The generated code would contain info about what needs to be done and set no constraints on the implementation. This removes the tedious part of the job and for simple languages there is no need for much more.

[bruno-medeiros]

FWIW, what I had in mind to do myself was to just provide a template with all the extension points and abstract classes needed to provide editing support. The generated code would contain info about what needs to be done and set no constraints on the implementation. This removes the tedious part of the job and for simple languages there is no need for much more.

I'm not sure I understand what you mean here. A template with all the extension points and abstract classes is already what MelnormeEclipse provides, so I'm not sure what you had in mind to do. The only thing missing is:

• A bit more info/doc at some places in the source, about what one can do and how.
• A less tedious mechanism to do all the renames and string replaces of "LANGUAGE_" and the other similar strings. But this is just a one-time issue, which becomes a task of somewhat insignificant size compared to developing the actual IDE functionality.

Also, note, if you wanna try out MelnormeEclipse for now, see what it can do, etc., you can ignore all the string replace steps in https://github.com/bruno-medeiros/MelnormeEclipse/blob/master/README-MelnormeEclipse.md#modifying-the-starting-template , and just go for implementing language specific features. It will work just fine (perhaps I should have made this clearer). Only before you release you new IDE to the public, is when should you fix all the IDs strings and such with your own.

[vladdu]

What I mean is that I aimed at basically just the parts that you have in the code and ui plugins, under "src", without any implementation and without imposing any external classes or libraries (or as little as possible). Your framework has that, but also a lot more and at this moment in time I feel a bit overwhelmed. It's very possible that it's only because I have a lot of things to do right now.

Good hint about not having to rename from the start, it also helps a lot with the merging. Maybe it's possible to have a script that can do the renaming?

[bruno-medeiros]

Yeah, one could have script (for example a bash script). Pull requests welcome... :smile:

BTW, I see you are the main dev of erlide. Are checking MelnormEclipse to see if could be useful for erlide?

[vladdu]

Yes, I am developing erlide. I'm looking at MelnormeEclipse partially for that, but mostly for other smaller projects that I don't want to start from scratch. For erlide, I am doing some prototyping and it would feel cleaner to do it on a clear slate.

Now seeing that Melnorme has more to offer than a skeleton implementation, it's possible that I will use it more, but I kind of like Handly (and hope they fit together) and I still feel a bit weird about getting so much new code and concepts to build on.

[vladdu]

Handly is an Eclipse project that aims at extracting the basic handle-based model that the JDT (and others) use and make it generic.

https://projects.eclipse.org/projects/technology.handly

regards, Vlad

On Sun, Apr 3, 2016 at 11:53 PM, Laurent Petit notifications@github.com wrote:

@vladdu https://github.com/vladdu what is Handly?

— You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub https://github.com/bruno-medeiros/MelnormeEclipse/issues/3#issuecomment-205061338