Package org.daiitech.naftah.parser.time

Class NaftahDateParserHelper

java.lang.Object
org.daiitech.naftah.parser.time.NaftahDateParserHelper
public final class NaftahDateParserHelper extends Object
Helper class for parsing Arabic date expressions using ANTLR-generated lexer and parser classes.

This class provides utility methods to:

  • Create a lexer and token stream from a CharStream
  • Prepare and configure an NaftahDateParser
  • Run the parser on a string input and return an NaftahTemporal result

It supports multiple error listeners and debug output for token streams.

Author:
Chakib Daii

  • Constructor Details

    • NaftahDateParserHelper

      private NaftahDateParserHelper()
      Private constructor to prevent instantiation. Always throws a NaftahBugError when called.

  • Method Details

    • getCommonTokenStream

      public static Pair<NaftahDateLexer,org.antlr.v4.runtime.CommonTokenStream> getCommonTokenStream(org.antlr.v4.runtime.CharStream charStream, List<org.antlr.v4.runtime.ANTLRErrorListener> errorListeners)
      Creates a CommonTokenStream and associated NaftahDateLexer from a given CharStream and list of ANTLR error listeners.
      Parameters:
      charStream - the input character stream
      errorListeners - the list of ANTLR error listeners
      Returns:
      a pair containing the lexer and token stream

    • prepareRun

      public static NaftahDateParser prepareRun(org.antlr.v4.runtime.CharStream input, org.antlr.v4.runtime.ANTLRErrorListener errorListener)
      Prepares an NaftahDateParser for parsing using a single error listener.
      Parameters:
      input - the input character stream
      errorListener - the ANTLR error listener
      Returns:
      a configured NaftahDateParser instance

    • prepareRun

      public static NaftahDateParser prepareRun(org.antlr.v4.runtime.CharStream input, List<org.antlr.v4.runtime.ANTLRErrorListener> errorListeners)
      Prepares an NaftahDateParser for parsing using a list of error listeners.

      Also optionally prints token stream information if debug mode is enabled.

      Parameters:
      input - the input character stream
      errorListeners - the list of ANTLR error listeners
      Returns:
      a configured NaftahDateParser instance

    • getParser

      public static NaftahDateParser getParser(org.antlr.v4.runtime.CommonTokenStream commonTokenStream, List<org.antlr.v4.runtime.ANTLRErrorListener> errorListeners)
      Creates and returns an NaftahDateParser instance from a given CommonTokenStream and list of error listeners.
      Parameters:
      commonTokenStream - the token stream from the lexer
      errorListeners - the list of ANTLR error listeners
      Returns:
      a configured NaftahDateParser instance

    • run

      public static <T extends NaftahTemporal> T run(String arabicDate, Class<T> tClass)
      Parses an Arabic date/time expression and returns a typed temporal result.

      This method performs the full parsing pipeline:

      • Creates a lexer and parser from the input string
      • Registers the default error listener
      • Traverses the parse tree using DefaultNaftahDateParserVisitor
      • Returns the parsed result cast to the requested temporal type

      The returned object may represent:

      • A temporal point (date, time, or date-time)
      • A temporal amount (duration, period, or a combination)
      Type Parameters:
      T - the concrete NaftahTemporal subtype to return
      Parameters:
      arabicDate - the Arabic date/time expression to parse
      tClass - the expected result type
      Returns:
      the parsed temporal representation
      Throws:
      ClassCastException - if the parsed result cannot be cast to tClass
      RuntimeException - if a parsing or semantic error occurs

    • visit

      public static Object visit(NaftahDateParserBaseVisitor<?> naftahDateParserBaseVisitor, org.antlr.v4.runtime.tree.ParseTree tree)
      Visits the given parse tree using the provided Arabic date parser visitor.

      This is a convenience method that delegates directly to AbstractParseTreeVisitor.visit(ParseTree).

      Parameters:
      naftahDateParserBaseVisitor - the visitor used to traverse the parse tree
      tree - the parse tree to visit
      Returns:
      the result produced by the visitor

    • currentTime

      public static NaftahTime currentTime(NaftahDateParserBaseVisitor<?> naftahDateParserBaseVisitor, NaftahDateParser.ZoneOrOffsetSpecifierContext zoneOrOffsetSpecifier)
      Resolves and returns the current time as an NaftahTime instance.

      If a zone or offset specifier is present, it is first visited and resolved using the provided visitor, then applied when computing the current time.

      If no zone or offset specifier is provided, the system default is used.

      Parameters:
      naftahDateParserBaseVisitor - the visitor used to resolve the zone or offset
      zoneOrOffsetSpecifier - the optional zone or offset parse context
      Returns:
      an NaftahTime representing the current time

    • currentDate

      public static NaftahDate currentDate(NaftahDateParserBaseVisitor<?> naftahDateParserBaseVisitor, NaftahDateParser.CalendarSpecifierContext calendarSpecifier, NaftahDateParser.ZoneOrOffsetSpecifierContext zoneOrOffsetSpecifier)
      Resolves and returns the current date as an NaftahDate instance.

      The calendar is resolved from the provided calendar specifier if present; otherwise, the default chronology is used.

      If a zone or offset specifier is provided, it is applied when determining the current date.

      Parameters:
      naftahDateParserBaseVisitor - the visitor used to resolve calendar and zone
      calendarSpecifier - the optional calendar parse context
      zoneOrOffsetSpecifier - the optional zone or offset parse context
      Returns:
      an NaftahDate representing the current date

    • getArabicTemporalAmountBetween

      public static NaftahTemporalAmount getArabicTemporalAmountBetween(NaftahTemporalPoint left, NaftahTemporalPoint right)
      Computes the Arabic temporal amount between two NaftahTemporalPoint instances.

      The result represents the difference between left and right and can be one of the following, depending on the underlying Temporal objects:

      This method uses TemporalUtils.between(java.time.temporal.Temporal, java.time.temporal.Temporal) to calculate the raw TemporalAmount and then wraps it in the appropriate Arabic-aware type.

      Parameters:
      left - the starting temporal point
      right - the ending temporal point
      Returns:
      an NaftahTemporalAmount representing the difference between left and right