Raven

Raven initializes class's fields with values provided in an external text file.

Java tool which allows to initialize class with values stored in a text file. Values in a text file are refered from classes based on field annotations. It is useful where there is necessity to parse huge number of files with different structure.

• Getting started
• Text files
• Parsing list of values
• Parsers
• Using parsers for other types than Strings
• Motivation
• Installation

Getting started

1. Annotate your class

Annotation @Parsable denotes that field should be initialized. col and row values point to position in a text file. parser is necessary if field has to be parsed from String to other type.

public class Network {
    
	@Parsable(col = 0, row = 0)
	private String name;
	
    @Parsable(col = 0, row = 1, parser = IntegerParser.class)
    private int nrOfNodes;
    
    @Parsable(col = 1, row = 1, parser = IntegerParser.class)
    private int nrOfEdges;
    
    ...
}

2. Create a text file

Create a text file network1.txt.

euro-network
10 20

3. Create/initialize your class in a code

To create class in code use Raven#create(path : String) : T method.

import com.github.piotrlechowicz.raven.FlatFileReader;
...
            
Raven<Network> raven = new Raven(Network.class);
Network network = raven.create("network1.txt");

To initialize already created class use Raven#initialize(instance : T, path : String) : T method.

Network network = new Network();
...
Raven<Network> raven = new Raven(Network.class);
raven.initialize(network, "network1.txt");

In both cases the fields of instance network will have following values:

name : "euro-network"
nrOfNodes : 10
nrOfEdges : 20

Text files

Text files is considered as two dimensional grid, where columns are separated with space sign and rows are separated with return sign. The indices are counted from top left corner, starting from value 0.

If text file has following form:

00 01 02 03 04
10 11 12 13 14
20 21 22
30 31 32

then coordinates (2nd row, 1st col) refers to value 21. File can contain different number of columns in each row.

##Parsing list of values

It is possible to parse list of values using @ManyCols and/or @ManyRows annotations.

######1. Parsing many columns

To parse many columns use @ManyCols annotation.

public class Network {
...
    @Parsable(col = 2, row = 3, parser = IntegerParser.class)
    @ManyCols(5)
    List<Integer> edgeDistances;
}

It will initialize this field with 5 values starting from 3rd row and 2nd column, and ending at 6th column.

Parsed values are marked bold in a file:

1 2 3 4
1 2 4 8
1 3 9 16 25 36 49 64 81
1 1 1 2  2  2  3  3  3

2. Parsing many rows

To parse many rows use `@ManyRows` annotation. If no argument is passed to `@ManyCols` or `@ManyRows`, it means that all values till last row/column should be taken.

public class Demands {
	@Parsable(row = 1, col = 1, coverter = IntegerParser.class)
	@ManyRows
	private List<Integer> destinationNodes;
}

It will initialize field with list of integers, starting from 1st row and 1st column, and ending on last row.

Parsed values are marked bold in a file:

1 5 20
2 4 18
2 6 10
1 2 15
9 8 4

3. Parsing matrix

It is possible to initialize matrix of values (List<List<?>>) using at the same time @ManyCols and @ManyRows annotations.

Using parsers for other types than Strings

Fields of different type than String can be parsed with parsers. There is provided set of basic parsers in com.github.piotrlechowicz.raven.parsers package:

• IntegerParser
• FloatParser
• DoubleParser
• BooleanParser
• ByteParser

To use certain parser, it has to be specified in @Parsable annotation by setting parser value. For example to use BooleanParser field should be annotated in the following way:

@Parsable(parser = BooleanParser.class)
Boolean booleanValue;

Creating new parsers

New parsers can be created to parse other types. In order to do this Parser<T> interface has to be extended. It contains abstract method parse(input : String) : T which determines how the input String will be parsed to desired value T.

public class MyParser implements Parser<String> {
    @Override
    public String parse(String input) {
        return input.substring(0, 2); 
    }
}

Motivation

Creation of algorithm with huge number of input files, configurations and properties can be a little overwhelming. Raven was created as a tool to minimize necessary effort to writing text file parsers. It provides easy to use mechanism with annotations.

Installation

The project can be downloaded from Maven repository. In your pom.xml file you have to add the following repository and dependency.

<repositories>
    <repository>
        <id>armadillo</id>
        <name>GitHub Armadillo Repository</name>
        <url>https://github.com/piotrlechowicz/armadillo</url>
    </repository>
</repositories>
...
<dependencies>
    <dependency>
        <groupId>com.github.piotrlechowicz</groupId>
        <artifactId>raven</artifactId>
        <version>1.1</version>
    </dependency>
</dependencies>