commit	5785b78ea8e06b6e3367dec7a60ed8e6a61c87df	[log] [tgz]
author	Federico Tomassetti <f.tomassetti@gmail.com>	Fri Sep 23 20:17:00 2016 +0200
committer	GitHub <noreply@github.com>	Fri Sep 23 20:17:00 2016 +0200
tree	d0085b094ba022908688ff0b74e22b2c0e1c2370
parent	de1a81827f176ec98a8f69e3bdd030de9fe73401 [diff]
parent	8b058a3c4cc58731755bdc1975930d53b23d4162 [diff]

tree: d0085b094ba022908688ff0b74e22b2c0e1c2370

README.md

JavaSymbolSolver

A Symbol Solver for Java built on top of JavaParser.

What can you use a Symbol Solver for?

A Symbol Solver can associate a symbol in your code to its declaration. This is necessary to verify the type of an expression or to find the usage of a symbol (like a field or a local variable):

Consider this:

int a = 0;
while (true) {
    String a = "hello!";
    Object foo = a + 1;
}

In the expression a + 1 a parser (like JavaParser) is not able to tell us to which definition of a we are referring to and consequently it cannot tell us the type of a. The JavaSymbolSolver is able to do so.

How can I use it?

Take a look at JavaParserFacade. For example you can use it to find the type of an expression:

Node node = <get this node by parsing source code with JavaParser>
TypeUsage typeOfTheNode = JavaParserFacade.get(typeSolver).getType(node);

Easy, right?

The only configuration that it requires is part of the TypeSolver instance to pass it. A TypeSolver is the mechanism that is used to find the classes referenced in your code. For example your class could import or extend a given class and the TypeSolver will find it and build a model of it, later used to solve symbols. Basically there are four TypeSolver:

JavaParserTypeSolver: look for the type in a directory of source files
JarTypeSolver: look for the type in a JAR file
JreTypeSolver: look for the type using reflection. This is needed because some classes are not available in any other way (for example the Object class). However this should be used exclusively for files in the java or javax packages
CombinedTypeSolver: permits to combine several instances of TypeSolvers

In the tests you can find an example of instantiating TypeSolvers:

CombinedTypeSolver combinedTypeSolver = new CombinedTypeSolver();
combinedTypeSolver.add(new JreTypeSolver());
combinedTypeSolver.add(new JavaParserTypeSolver(new File("src/test/resources/javaparser_src/proper_source")));
combinedTypeSolver.add(new JavaParserTypeSolver(new File("src/test/resources/javaparser_src/generated")));

Typically to analize a project you want to create one instance of JavaParserTypeSolver for each source directory, one instance of JarTypeSolver for each dependency and one JreTypeSolver then you can combine all of them in a CombinedTypeSolver and pass that around.

We plan to write soon more examples and tutorials.

Status of the project

This project is young but we have already tried it on significant projects and it is doing well so far. It supports all features of Java 8 (lambdas, generic, type inference, etc.). Of course we expect some bugs to emerge from time to time but we are committed to help users solve them as soon as possible.

TODO add link to COATI

License

This code is available under the Apache License.

Development

We use Travis to ensure our tests are passing all the time and we use Walkmod to ensure code conventions are respected. The dev-files dir contains configurations for the Eclipse and the IDEA formatters (I took them from the JavaParser project, thanks guys!).

An overview of the architecture of the project is available in Design.MD

Contributing

I would absolutely love every possible kind of contributions: if you have questions, ideas, need help or want to propose a change just open an issue. Pull-requests are greatly appreciated.

Thanks to Malte Langkabel, Matozoid, Ayman Abdelghany, Evan Rittenhouse, Rachel Pau, selslack and Simone Basso for their contributions!