README.adoc

November 10, 2017 ยท View on GitHub

= ec4j

https://github.com/ec4j/ec4j/blob/master/LICENSE[image:https://img.shields.io/github/license/ec4j/ec4j.svg[License]] http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22ec4j%22[image:https://img.shields.io/maven-central/v/fr.opensagres.js/ec4j.svg[Maven Central]] http://travis-ci.org/ec4j/ec4j[image:https://secure.travis-ci.org/ec4j/ec4j.png[Build Status]]

ec4j is an http://editorconfig.org/[EditorConfig] parser for Java.

== Who is using ec4j?

Here are some projects that use `ec4j:

== Basic usage

To parse a single .editorconfig file into an EditorConfig model:

[source,java]

java.nio.file.Path editorConfigFile = Paths.get("path/to/my/.editorconfig"); EditorConfigParser parser = EditorConfigParser.builder().build(); EditorConfigModelHandler handler = new EditorConfigModelHandler(EditorConfigConstants.VERSION, PropertyTypeRegistry.getDefault()); parser.parse(Resources.ofPath(editorConfigFile), StandardCharsets.UTF_8, handler); EditorConfig editorConfig = handler.getEditorConfig();

To query the properties applicable to a file in a source tree:

[source,java]

Cache myCache = ...; // e.g. Caches.none() EditorConfigLoader myLoader = ...; // e.g. EditorConfigLoader.getDefault() EditorConfigSession mySession = EditorConfigSession.builder() .cache(myCache) .loader(myLoader) .rootDirectory(ResourcePaths.ofPath(Paths.get("/my/dir"))) .build(); QueryResult result = mySession.queryProperties(Resources.ofPath(Paths.get("/my/dir1/Class1.java"))); IndentStyleValue indentStyleValue = result.getValue(PropertyType.indent_style, IndentStyleValue.space); switch (indentStyleVal) { case space: // ... break; case tab: //... break; default: throw new IllegalStateException("Huh "+ indentStyleVal +"?"); } }

== How to build

Prerequisites:

The most common build with unit tests:

[source,shell]

./mvnw clean install

On Windows:

[source,shell]

mvnw.bat clean install

A build with https://github.com/editorconfig/editorconfig-core-test[editorconfig-core-test] testsuite:

[source,shell]

git submodule init git submodule update mvn -Pcore-test clean install && ( cd core && cmake . && ctest . )

== Relationship to editorconfig-core-java

ec4j aims at offering a superset of https://github.com/editorconfig/editorconfig-core-java[editorconfig-core-java] 's functionality.

While editorconfig-core-java supports just the basic use case of querying the EditorConfig properties applicable to a given file, ec4j offers much more in addition to that:

  • A proper link:core/src/main/java/org/eclipse/ec4j/core/model/EditorConfig.java[model of an .editorconfig file]
  • link:src/main/java/org/eclipse/ec4j/core/model/Property.java[Type safe property values]
  • link:core/src/main/java/org/eclipse/ec4j/core/parser/EditorConfigParser.java[EditorConfigParser] and link:core/src/main/java/org/eclipse/ec4j/core/parser/EditorConfigHandler.java[EditorConfigHandler] interface designed to support syntax highlighting, validation, folding, etc. of .editorconfig files in IDEs.
  • ec4j will release to Maven Central
  • ec4j performs better against the https://github.com/editorconfig/editorconfig-core-test[editorconfig-core test suite]:

|=== | Library | Lib. revision | No. tests passed/total | ec4j | 4a35a29 | 181/182 | editorconfig-core-java | e3e0905 | 177/182 |=== + Testing platform: Linux, editorconfig-core-test revision: https://github.com/editorconfig/editorconfig-core-test/commit/172eb8324225f09f3e331af26454a5b45e314edb[172eb83]

ec4j took portions of code from editorconfig-core-java. Such ones are clearly marked in ec4j's JavaDoc.

== Get support and contribute

  • License and community: ec4j is a community open-source project licensed under the http://www.apache.org/licenses/LICENSE-2.0.txt[Apache License].
  • Support: You can ask questions, report bugs, and request features using http://github.com/eclipse/ec4j/issues[GitHub issues].
  • Git: This angelozerr/ec4j repository is the reference repository to contribute to ec4j
  • Build and CI: build can be performed with a simple mvn clean verify, continuous integration and deployment is performed by Travis CI