Вредные советы при работе с ANTLR

У лексера можно переопределить обработку токенов:

  override def nextToken(): Token =
    if (hasEnqueuedTokens) dequeueToken
    else if (templateMode) nextTokenTemplate
    else nextTokenNonTemplate

  private def nextTokenNonTemplate: Token = {
    val token = _input.LA(1) match {
      case '`' => parseTemplateLiteral
      case _ => super.nextToken()
    }
    if (token.getChannel == Token.DEFAULT_CHANNEL)
      lastToken = token
    token
  }

  private def nextTokenTemplate: Token =
    if (!insideTemplate) {
      if (_input.LA(1) != '`')
        throw new IllegalStateException("Template string must start with '`' character")
      insideTemplate = true
      val token = createToken(_input.index(), 1, templateLiteralDelimiter, Token.HIDDEN_CHANNEL)
      templateStartToken()
      token
    } else if (_input.index() == closePosition) {
      if (_input.LA(1) != '}')
        throw new IllegalStateException("Close position is not at '}' character")
      val token = createToken(_input.index(), 1, templateLiteralDelimiter, Token.HIDDEN_CHANNEL)
      templateMiddleOrStopToken()
      token
    } else nextTokenNonTemplate

Это кусок кода для анализа TypeScript/JavaScript, гораздо выгоднее проанализировать собственными руками последовательность символов и сделать токен с шаблонной строкой, чем нагружать лексер, тем более, что в случае вложенности будут проблемы с анализом выражений. Для правила startTemplate токены TemplateLiteral* создавались не лексером, а руками. Код у правил удалил, потому что при просмотре превращается в кашу.

//////////////////////////////////////// Main Entry Points 
startTypeScript
    :   typeScriptStmtList EOF
    |   EOF
    ;

//////////////////////////////////////// Secondary Entry Points 
startTemplate
    :  
        TemplateLiteralStart
        // опционально, потому что TemplateLiteralStart может содержать окончание
        (
            expression[true,_yield,await] 
            (
                TemplateLiteralMiddle                
                expression[true,_yield,await] 
            )*
            TemplateLiteralStop
        )?
        EOF        
    ;

  private def parseTemplateLiteral: Token = {
    val start = _input.index()
    createToken(start, parseTemplateString(), templateLiteral)
  }

parseTemplateString — находит индекс последнего символа шаблонной строки с учетом вложенности.
Уже после этот литерал парсится отдельно. Например вот так:

    final def parse(): RLangOp = {
      val result = parseInitial()
      enqueue(result.folds ++ result.templates)
      while (jobs.nonEmpty) {
        val _j = Seq.empty ++ jobs
        jobs.clear()
        parseItems(_j)
      }
      result.op.asInstanceOf[RLangOp]
    }

Внутри parseItems все folds, templates так же добавляются в очередь jobs
Полагаю, что с комментариями можно такую же штуку провернуть.
Должно быть что-то в таком духе у вас:

methodWithMeta:
  MethodMeta?
  methodDecl[$MethodMeta]

Если поиграетесь с режимами работы лексера (mode — его можно устанавливать до выполнения), то можно все в одном уместить, и с парсером так же удастся сделать.

Правила можно легко вызывать вот таким образом:

  final def invokeRule[T](ruleName: String): T = resultOfRule[T](ruleName)

  private def resultOfRule[T](ruleName: String): T =
    resultField[T](getClass.getDeclaredMethod(ruleName).invoke(this))

  private def resultField[T](value: AnyRef): T =
    value.getClass.getDeclaredField("result").get(value).asInstanceOf[T]

Не вижу смысла использовать команду skip, выкидывать лишние токены, а тем более использовать двойной проход. Лучше помещать их в скрытый, либо какой-то кастомный канал -> channel(HIDDEN), подробней — в официально документации. В этом канале они не будут мешать парсеру, но будут доступны для обработки. Команду skip я бы использовал только в случае, если текста очень много и даже токены будут занимать много места в памяти.

Нужно ли связывать комментариями с узлами дерева разбора? Если нет — все просто, я по сути уже ответил на вопрос. Если да, то рекомендую использовать систему лидирующих (leading) и хвостовых скрытых токенов (trailing). Такое используется в Roslyn, посмотреть можно здесь: Теория и практика парсинга формальных языков. Это можно реализовать и в рамках ANTLR (реализовано в коммерческом проекте, но планирую заопенсорсить как руки дойдут).

Каким образом, просто обнулять ссылки медленно?

Неправильно выразился, парсер, если ему отдавать сразу все работает очень медленно.
А заменить в джаве final static нельзя (на самом деле можно, но это будет слабоумие и отвага).

Как это работает, как парсится. Можно поподробней?

  override def nextToken(): Token = {
    if (hasEnqueuedTokens) dequeueToken
    else super.nextToken() match {
      case x: RScanToken if x.getType == foldOpen => buildFoldToken(x)
      case x: Token => x
    }
  }

buildFoldToken рекурсивно собирает все токены начиная с { и по }, создает для них токен с адресом от { по }, внутри имеет список токенов, которые он поглотил, включая такие же фолды.
А уже в ANTLR идет так:

functionBody[boolean yield, boolean await]
    :   LBRACE stmtList[$yield, $await, true] RBRACE
    |   FoldBlock
    ;

В итоге и обычный режим работает, и оптимизация тоже пашет. Парсить токены внутри FoldBlock можно когда потребуется. А главное, что lookahead убивается на корню, потому что он не нужен для случаев, когда альтернативы быть не может, но ANTLR честно их ищет.

А какие языки? :)

Java.

В чем посредственность на конкретных примерах? Было бы интересно узнать, как это можно избежать. Ну и для этого они и открытые, чтобы сообщество могло их дорабатывать.

Они не SLL. Запускаешь эти грамматики на тестовом множестве (2000+ файлов), так половина минимум падает с ошибками.

Не увидел чего-то сложного перейдя по вашей ссылке.
То что понять что есть что на уровне лексера не выйдет, да и у парсера будут проблемы — да.
Но зачем идти по извилистой земляной дорожке в поле, если рядом есть шоссе?

Советую попробовать другие варианты работы с исходными кодами. Особенно это касается AST, он вам не нужен. UST — ближе, но все еще не то.

А есть ли у вас какой-нибудь опыт по обработке препроцессорных директив?

Писал, правда 5 дней было потрачено на него и, как говорил Костя, пару багов исправил, уже после моего увольнения. Соответствие спецификации 2011 года — 100%, но есть там нюансы со склейкой токенов, видимо на них баги и были.
Есть небольшое расхождение в части переноса строк, в GNU они уходят, в спеке говорится, что должны оставаться. Я про макросы и параметры.

Есть два способа — делать сложные стейтменты (когда у стейтмента может быть предок), либо же результаты макро-обработки мэппить на координаты исходного токена (или токенов). Что бы избежать наложения адресов советую добавить virtual — тогда каждый новый токен будет иметь свой адрес при любых раскладах. Указывать будет на точку применения макроса.

Вообще это отдельная тема и обсуждать ее тут не вижу смысла.