TextParserLib

A light-weight Java library to parse text with identifier and then replace the identifier with its value. supports both synchronous and asynchronous mode.

As this library is very simple, it's also very easy to work with. Consider this scenario, where you need to parse this text:

     Hi, I am *(name)* and I am *(age)* years old. I am a *(occupation)*. I am a *(nationality)* 
    

So, if you closely look at this example, you will figure out that, there is four identifier (name, age, occupation, nationality)

and start tag of *( and

the end tag of )* (Sorry for Github is interpreting my text wrong, so I can't maintain good formatting)

So, this library read them by factors such as tag start, tag end and identifier text range.

So, later on, those tag with identifier will be replaced by their value passed with key value pair, for example public TextParser(String textToParse, Template template, Map<String, String> keyValuePairs)

Or passed by method reference from TextParser#putVariableNameAndValue(String variableName, String variableValue)

Okay, let's dive into implementation part, where, I will cover both asynchronous and synchronous implementation technic with code example.

Building this library

cd to the root directory of this project. This project is usages gradle 7.4, so you must have this version or later version in the PATH.

To check, which version you have installed, run

gradle --version

Now, run this command to build the project:

gradle jar

The output will be there -> build/libs/textparserlib-{version}.jar

Synchronous Implementation

So, let's parse this text:

   Hi, I am *(name)* and I am *(age)* years old. 

We want the output of

  Hi, I am Nurujjaman Pollob and I am 23 years old.  

So, let's create a variable for input String

String text = "Hi, I am *(name)* and I am *(age)* years old.";

Create a new instance of Template

     Template template = new Template("*(", ")*"); 

Create a new instance of TextParser(You can explore all constructor params to fit your needs)

In this example, we are going to use public TextParser(String textToParse, Template template)

   TextParser parser = new TextParser(text, template); 

Now, put the identifier name sets with with value by calling TextParser#putVariableNameAndValue(String variableName, String variableValue) You can so the same job passing Hashmap<String, String> keyValSets; with constructor.

   parser.putVariableNameAndValue("name", "Nurujjaman Pollob");
         parser.putVariableNameAndValue("age", "23");
  

Now, call TextParser#parseSynchronously() to get parsed text.

     String parsedText = parser.parseSynchronously() 
 

You can also skip creating a new instance of TextParser, instead, calling Template#parseSynchronously(String text, HashMap<String, String> keyValueSets) will do same job!

In case, you need to study the synchronous implementation a little more, you can check this Unit test class: TextParserSynchronousTest.java

Asynchronous implementation

asynchronous implementation works in almost same way. All you need to call TextParser#parseAsynchronously(ParseEventListener listener) with a valid new instance of ParseEventListener.java

This code fragment shows this in real action:

 	
	    
		String textToParse = "Hi, I am *(name)* and I am *(age)* years old. I am a *(occupation)*. I am a *(nationality)*";

        // Define template instance
        Template template = new Template("*(", ")*");

        // Create a NEW instance of TextParser
        TextParser textParser = new TextParser(textToParse, template);

        // put identifiers and values
        textParser.putVariableNameAndValue("name", "Nurujjaman Pollob");
        textParser.putVariableNameAndValue("age", "23");
        textParser.putVariableNameAndValue("occupation", "Student");
        textParser.putVariableNameAndValue("nationality", "Bangladeshi");

        // call parseAsynchronously() method with a ParseEventListener instance
        textParser.parseAsynchronously(new ParseEventListener() {

            /**
             * This method is invoked when {@link dev.nurujjamanpollob.textparserlib.parser.TextParser} finishes parsing the text.
             * @param result result of the parsing
             */
            @Override
            public void onParseFinished(String result) {
			
			    // Do action on call success

            }

            /**
             * This method is invoked when {@link dev.nurujjamanpollob.textparserlib.parser.TextParser} found an exception, see the exception for more information.
             */
            @Override
            public void onException(TemplateException templateException) {

                // Do action on call failed
				

            }
        });
		
	

You can also skip create a new instance of TextParser, instead calling Template#parseAsynchronously(String text, HashMap<String, String> keyValueSets, ParseEventListener parseEventListener) can do the same job!

If you want to study the asynchronous implementation a bit, you can look at this unit test class from here: TextParserAsynchronousTest.java

Define optionals

From version 2.0.0, you can define optionals using a (?) before the identifier name. You also need to define a parameter named defVal="Default Value" to define the default value of the identifier.

This library only take optional value, when you do not pass value for the identifier.
This example shows you how to do it:

 String textToParse = "Hi, I am *(?name defVal="Nurujjaman Pollob")* and I am *(?age defVal="22")* years old. 

it's safe to use optionals, If you do not pass value for the identifier, it will use the default value than.

This example, going to show you, how to use optionals with default value and override the default value.

        String text = "Hi, I am *(?name defVal=\"John Doe\")* and I am *(?age defVal=\"20\")* years old.";

        // Create template instance
        Template template = new Template("*(", ")*");
        // Create parser instance
        TextParser parser = new TextParser(text, template);
        // Override optional identifier(name) with a new value 
        parser.putVariableNameAndValue("name", "Nurujjaman Pollob");
        // Parse synchronously
        String parsedText = parser.parseSynchronously();

So, you see, it's fun to use optionals. If you noticed that, we stop read the text when we match the double quote, so what you do if you want to use double quote in optional value.

This library support the escaped character to allow you to do this, let's look at this example:

        String text = "Hi, I am *(?name defVal="*"John*"")* and I am *(?age defVal="20")* years old.";
        String matchTo = "Hi, I am "John" and I am 20 years old.";

        // Create template instance
        Template template = new Template("*(", ")*");
        // Create parser instance
        TextParser parser = new TextParser(text, template);
        // Parsed text
        String parsedText = parser.parseSynchronously();

This parsed text match with the matchTo string, so, you can see, you can use escaped character in optionals.

If you would like to learn more, look at this test class TextParserOptionalTest.java

Any contribution, suggestions are highly welcome.