Text is a huge part of any programming language. A lot of data stored as text. But text need to be parsed to use it. And data needs to be formatted to treat it as text. This package provides abstracts for how the parsing and formatting process should be performed.


Classifier

GitHub Javadoc

---

An abstract of how classifiers should be. The class is based on tokens concept. Each classifying operation should have a token that have all the variables of that operations.

• classify(CharSequence) classify(Reader) returns the clazz of the text provided.
  
  

    CharSequence sequence = //the sequence
    //Reader reader = //the reader, as a replacement of 'sequence'
  
    //the returned clazz is the result from classifying the text
    Clazz klazz = classifier.classify(sequence);
  

  
  

• classify(ClassifyToken) performs the classifying operation of the token given.
  
  

    ClassifyToken token = //a token with the classifying parameters
  
    classifier.classify(token);
  
    //now token.output has the result of the classification
  

Parser

GitHub Javadoc

---

An abstract of how parsers should be. The class is based on tokens concept. Each parsing operation should have a token that have all the variables of that operation.

• parse(CharSequence, Object) parse(Reader, Object) parses the provided text to the object given.
  
  

    CharSequence sequence = //the sequence
    //Reader reader = //the reader, as a replacement of 'sequence'
    Object instance = //the object to output to
  
    Object out = parser.parse(sequence, instance);
  
    //now, if 'instance' is valid, then 'out' will be 'instance'
    //and 'instance' have the value from parsing 'sequence'.
    //otherwise, 'out' will not be 'instance' and 'instance'
    //have not been changed meanwhile 'out' will have the value from
    //parsing 'sequence'
  

  
  

• parse(ParseToken) performs the parsing operation of the token given.
  
  

    ParseToken token = //a token with the parsing parameters
  
    parser.parse(token);
  
    //now token.output has the result of the parsing
  

Formatter

GitHub Javadoc

---

An abstraction of how formatters should be. The class is based on tokens concept. Each formatting operation should have a token that have all the variables of that operation.

• format(Object) formats the provided instance into a string.
  
  

    Object instance = //the instance to format
  
    //the returned string is the result from formatting the instance
    String text = formatter.format(instance);
  

  
  

• format(Object, Writer) formats the provided instance and write the results to the given writer.
  
  

    Object instance = //the instance to format
    Writer writer = //the writer to write the text to
  
    //the results will be written directly to the writer
    formatter.format(instance, writer);
  

  
  

• format(FormatToken) performs the formatting operation of the token given.
  
  

    FormatToken token = //a token with the formatting parameters
  
    //the results will be written directly to the writer
    formatter.format(token);
  

Format

GitHub Javadoc

---

Is a class that is a classifier, parser, and a formatter at the same time. A text language could be represented by a one class.

• cparse(CharSequence) cparse(Reader) classifies the provided text then parses it to a new instance depending on the result of the classification.
  
  

    CharSequence sequence = //the sequence
    //Reader reader = //the reader, as a replacement of 'sequence'
  
    //the returned object is the result from c-parsing the text
    Object instance = format.cparse(sequence);
  

  
  

• cparse(CharSequence, Object) cparse(Reader, Object) classifies the provided text then parses it to the provided instance (unless it is not valid) depending on the result of the classification.
  
  

    CharSequence sequence = //the sequence
    //Reader reader = //the reader, as a replacement of 'sequence'
    Object instance = //the instance to try parsing to it
  
    Object out = format.cparse(sequence, instance);
  
    //now, if 'instance' is valid, then 'out' will be 'instance'
    //and 'instance' have the value from parsing 'sequence'.
    //otherwise, 'out' will not be 'instance' and 'instance'
    //have not been changed meanwhile 'out' will have the value from
    //parsing 'sequence'
  

AbstractFormat

GitHub Javadoc

---

An abstract that manages and organize the methods of the class inheriting it. The sub-class had to just focus on providing classifying, formatting, and parsing methods and this class will manage everything else using reflection.

• ClassifyMethod ParseMethod FormatMethod is an annotations to be annotated to every classifying, parse, format methods in the sub-class. The methods annotated with one of these annotations will be used by the super-class based on the parameters given to the annotations.
  
  

    @ClassifyMethod
    protected boolean classifyTypeA(ClassifyToken<TypeA> token) {
        //here is the code that classifies the input
        return true; //continue the classification
        //return false; //end the classification
    }
  

    @ParseMethod(@Filter(includeAll = TypeA.class))
    protected void parseTypeA(ParseToken<TypeA> token) {
        //here is the code that parses the input
    }
  

    @FormatMethod(@Filter(includeAll = TypeA.class))
    protected void formatTypeA(FormatToken<TypeA> token) {
        //here is the code that formats the input to the output
    }
  

  
  

• classifyPre(...) parsePre(...) formatPre(...) get invoked before any classifying, parsing, or formatting operation to give the sub-class control over what should happen before doing the operations.
  

• classify0(...) parse0(...) format0(...) are the invokers of the classifying, parsing, and formatting methods. It manages what arguments to pass to the methods, how to extract the exceptions, and what method is illegal and what not.
  

• classifyElse(...) parseElse(...) formatElse(...) get invoked when no method found matching the requirements of a token.
  

• getClassifyMethods() returns all the classifying methods in the class.
  

• getParseMethod(...) getFormatMethod(...) search for a method that matches the requirements of the token.

SyntaxTracker

GitHub Javadoc

---

Is one of the ways to manage the position of the text when dealing with readers.

• construct to construct a syntax-tracker first the syntax to be tracked should be specified. The ‘nestable’ syntax is a fence syntax that can have inner fence syntax. The ‘literal’ syntax is a fence that can’t have inner fence syntax. The ‘escapable’ syntax is a list of sequences to be skipped when seen in a literal fence.
  
  

    //this is just an example
    Map nestable = new HashMap();
  
    //brackets is just a wrapper and can have inner fences
    //the key is the starting fence
    //the value is the ending fence
    nestable.put("[", "]");
  
    Map literal = new HashMap();
  
    //quotes is sign of a sequence of text and can't have inner fences
    //the key is the starting fence
    //the value is the ending fence
    literals.put("\"", "\"");
  
    List escapable = new ArrayList();
  
    //backslash is an escaping character and when followed with quote
    //it means that the quote should be treated as a plain text
    //the string should contain the escaped string
    escapable.add("\\\"");
  
    new SyntaxTracker(nestable, literal, escapable);
  

  
  

• append(...) provides the tracker with the next text. When using a reader this should be called to update the position of the tracker.
  
  

    Reader reader = //... a reader;
    SyntaxTracker tracker = //... a tracker
  
    int i;
    while((i = reader.read()) != -1) {
        //tracking the previous fences position
        tracker.append((char) i);
        //tracking the current fences position
    }
  

  
  

• depth() returns how many fences is applied currently tracked by the tracker.
  

• fenceStart() fenceEnd() returns the syntax that started the last applied fence and the syntax that will end it.