«1. Обзор

В этом руководстве мы сделаем краткий обзор генератора парсеров ANTLR и покажем некоторые реальные приложения.

2. ANTLR

ANTLR (ANother Tool for Language Recognition) — это инструмент для обработки структурированного текста.

Он делает это, предоставляя нам доступ к примитивам обработки языка, таким как лексеры, грамматики и синтаксические анализаторы, а также к среде выполнения для обработки текста по ним.

Он часто используется для создания инструментов и фреймворков. Например, Hibernate использует ANTLR для разбора и обработки HQL-запросов, а Elasticsearch — для Painless.

А Java — это всего лишь одна привязка. ANTLR также предлагает привязки для C#, Python, JavaScript, Go, C++ и Swift.

3. Конфигурация

Прежде всего, давайте начнем с добавления antlr-runtime в наш pom.xml: 

<dependency>
    <groupId>org.antlr</groupId>
    <artifactId>antlr4-runtime</artifactId>
    <version>4.7.1</version>
</dependency>

А также antlr-maven-plugin: 

<plugin>
    <groupId>org.antlr</groupId>
    <artifactId>antlr4-maven-plugin</artifactId>
    <version>4.7.1</version>
    <executions>
        <execution>
            <goals>
                <goal>antlr4</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Это плагин job для генерации кода из указанных нами грамматик.

4. Как это работает?

По сути, когда мы хотим создать синтаксический анализатор с помощью плагина ANTLR Maven, нам нужно выполнить три простых шага:

    подготовить файл грамматики сгенерировать источники создать прослушиватель

Итак, давайте посмотрим на эти шаги в действии .

5. Using an Existing Grammar

Let’s first use ANTLR to analyze code for methods with bad casing:

public class SampleClass {
 
    public void DoSomethingElse() {
        //...
    }
}

Simply put, we’ll validate that all method names in our code start with a lowercase letter.

5.1. Prepare a Grammar File

What’s nice is that there are already several grammar files out there that can suit our purposes.

Let’s use the Java8.g4 grammar file which we found in ANTLR’s Github grammar repo.

We can create the src/main/antlr4 directory and download it there.

5.2. Generate Sources

ANTLR работает, генерируя код Java, соответствующий файлам грамматики, которые мы ему даем, и плагин maven упрощает эту задачу: 

mvn package

По умолчанию это сгенерирует несколько файлов в target/generated-sources Каталог /antlr4:

    Java8.interp Java8Listener.java Java8BaseListener.java Java8Lexer.java Java8Lexer.interp Java8Parser.java Java8.tokens Java8Lexer.tokens

Обратите внимание, что имена этих файлов основаны на имени файла грамматики .

Нам понадобятся файлы Java8Lexer и Java8Parser позже, когда мы будем тестировать. Однако сейчас нам нужен Java8BaseListener для создания нашего MethodUppercaseListener.

5.3. Создание MethodUppercaseListener

На основе грамматики Java8, которую мы использовали, Java8BaseListener имеет несколько методов, которые мы можем переопределить, каждый из которых соответствует заголовку в файле грамматики.

Например, грамматика определяет имя метода, список параметров и предложение throws следующим образом: 

methodDeclarator
	:	Identifier '(' formalParameterList? ')' dims?
	;

Итак, Java8BaseListener имеет метод enterMethodDeclarator, который будет вызываться каждый раз, когда встречается этот шаблон.

Итак, давайте переопределим enterMethodDeclarator, вытащим идентификатор и проверим: 

public class UppercaseMethodListener extends Java8BaseListener {

    private List<String> errors = new ArrayList<>();

    // ... getter for errors
 
    @Override
    public void enterMethodDeclarator(Java8Parser.MethodDeclaratorContext ctx) {
        TerminalNode node = ctx.Identifier();
        String methodName = node.getText();

        if (Character.isUpperCase(methodName.charAt(0))) {
            String error = String.format("Method %s is uppercased!", methodName);
            errors.add(error);
        }
    }
}

5.4. Тестирование

Теперь давайте проведем тестирование. Во-первых, мы создаем лексер: 

String javaClassContent = "public class SampleClass { void DoSomething(){} }";
Java8Lexer java8Lexer = new Java8Lexer(CharStreams.fromString(javaClassContent));

Затем мы создаем экземпляр синтаксического анализатора: 

CommonTokenStream tokens = new CommonTokenStream(lexer);
Java8Parser parser = new Java8Parser(tokens);
ParseTree tree = parser.compilationUnit();

И затем, обходчик и слушатель: 

ParseTreeWalker walker = new ParseTreeWalker();
UppercaseMethodListener listener= new UppercaseMethodListener();

Наконец, мы говорим ANTLR пройти через наш пример класса: 

walker.walk(listener, tree);

assertThat(listener.getErrors().size(), is(1));
assertThat(listener.getErrors().get(0),
  is("Method DoSomething is uppercased!"));

6. Построение нашей грамматики

Now, let’s try something just a little bit more complex, like parsing log files:

2018-May-05 14:20:18 INFO some error occurred
2018-May-05 14:20:19 INFO yet another error
2018-May-05 14:20:20 INFO some method started
2018-May-05 14:20:21 DEBUG another method started
2018-May-05 14:20:21 DEBUG entering awesome method
2018-May-05 14:20:24 ERROR Bad thing happened

Because we have a custom log format, we’re going to first need to create our own grammar.

6.1. Prepare a Grammar File

First, let’s see if we can create a mental map of what each log line looks like in our file.

<datetime> <level> <message>

Or if we go one more level deep, we might say:

<datetime> := <year><dash><month><dash><day> …

And so on. It’s important to consider this so we can decide at what level of granularity we want to parse the text.

A grammar file is basically a set of lexer and parser rules. Simply put, lexer rules describe the syntax of the grammar while parser rules describe the semantics.

Let’s start by defining fragments which are reusable building blocks for lexer rules.

fragment DIGIT : [0-9];
fragment TWODIGIT : DIGIT DIGIT;
fragment LETTER : [A-Za-z];

Next, let’s define the remainings lexer rules:

DATE : TWODIGIT TWODIGIT '-' LETTER LETTER LETTER '-' TWODIGIT;
TIME : TWODIGIT ':' TWODIGIT ':' TWODIGIT;
TEXT   : LETTER+ ;
CRLF : '\r'? '\n' | '\r';

With these building blocks in place, we can build parser rules for the basic structure:

log : entry+;
entry : timestamp ' ' level ' ' message CRLF;

А затем мы добавим детали для метки времени: 

timestamp : DATE ' ' TIME;

For level:

level : 'ERROR' | 'INFO' | 'DEBUG';

And for message:

message : (TEXT | ' ')+;

And that’s it! Our grammar is ready to use. We will put it under the src/main/antlr4 directory as before.

6.2. Generate Sources

Recall that this is just a quick mvn package, and that this will create several files like LogBaseListener, LogParser, and so on, based on the name of our grammar.

6.3. Create Our Log Listener

Now, we are ready to implement our listener, which we’ll ultimately use to parse a log file into Java objects.

So, let’s start with a simple model class for the log entry:

public class LogEntry {

    private LogLevel level;
    private String message;
    private LocalDateTime timestamp;
   
    // getters and setters
}

Now, we need to subclass LogBaseListener as before:

public class LogListener extends LogBaseListener {

    private List<LogEntry> entries = new ArrayList<>();
    private LogEntry current;

current will hold onto the current log line, which we can reinitialize each time we enter a logEntry, again based on our grammar:

    @Override
    public void enterEntry(LogParser.EntryContext ctx) {
        this.current = new LogEntry();
    }

Next, we’ll use enterTimestamp, enterLevel, and enterMessage for setting the appropriate LogEntry properties:

    @Override
    public void enterTimestamp(LogParser.TimestampContext ctx) {
        this.current.setTimestamp(
          LocalDateTime.parse(ctx.getText(), DEFAULT_DATETIME_FORMATTER));
    }
    
    @Override
    public void enterMessage(LogParser.MessageContext ctx) {
        this.current.setMessage(ctx.getText());
    }

    @Override
    public void enterLevel(LogParser.LevelContext ctx) {
        this.current.setLevel(LogLevel.valueOf(ctx.getText()));
    }

And finally, let’s use the exitEntry method in order to create and add our new LogEntry:

    @Override
    public void exitLogEntry(LogParser.EntryContext ctx) {
        this.entries.add(this.current);
    }

Note, by the way, that our LogListener isn’t threadsafe!

6.4. Testing

And now we can test again as we did last time:

@Test
public void whenLogContainsOneErrorLogEntry_thenOneErrorIsReturned()
  throws Exception {
 
    String logLine ="2018-May-05 14:20:24 ERROR Bad thing happened";

    // instantiate the lexer, the parser, and the walker
    LogListener listener = new LogListener();
    walker.walk(listener, logParser.log());
    LogEntry entry = listener.getEntries().get(0);
 
    assertThat(entry.getLevel(), is(LogLevel.ERROR));
    assertThat(entry.getMessage(), is("Bad thing happened"));
    assertThat(entry.getTimestamp(), is(LocalDateTime.of(2018,5,5,14,20,24)));
}

7. Заключение

В этой статье мы сосредоточились на том, как создать собственный парсер для собственного языка с помощью ANTLR.

Мы также увидели, как использовать существующие файлы грамматики и применять их для очень простых задач, таких как анализ кода.