edu.umass.cs.surveyman.input

Class AbstractParser

java.lang.Object

edu.umass.cs.surveyman.input.AbstractParser

Direct Known Subclasses:

CSVParser, JSONParser

public abstract class AbstractParser
extends Object

This class implements general parsing utility methods and contains high-level input to survey abstractions.

Field Summary

Fields

Modifier and Type	Field and Description
protected Map<String,Block>	allBlockLookUp All blocks in the survey (including sub-blocks).
static String	ANSWER The expected response column header/JSON key.
static String	BLOCK The block column header/JSON key.
static String	BRANCH The branch column/JSON key.
static String	CORRELATION The correlation column header/JSON key.
protected Map<String,List<Question>>	correlationMap A map from correlation labels to their associated set of questions.
static String	CUSTOM_ID The identifier used for ad hoc responses (e.g., timing information).
static HashMap<String,Boolean>	defaultValues Holds a map from the column name to its default value.
static String	EXCLUSIVE The exclusive column header/JSON key.
static String	FREETEXT The freetext column header/JSON key.
static String	INPUT_SCHEMA The schema against which JSON input is validated.
static String[]	knownHeaders An array of semantically meaningful column headers.
protected static org.apache.logging.log4j.spi.ExtendedLogger	LOGGER
static String	OPTIONS The options column header/JSON key.
static String	ORDERED The ordered column header/JSON key.
static String	PERMIT_BREAKOFF Whether breakoff is premitted for the survey as a whole.
static String	QUESTION The question column header/JSON key.
static String	RANDOMIZE The randomize column header/JSON key.
static String	RESOURCE Deprecated.
protected List<Block>	topLevelBlocks The top-level blocks in the survey.

Constructor Summary

Constructors

Constructor and Description
AbstractParser()

Method Summary

Methods

Modifier and Type	Method and Description
protected static void	addPhantomBlocks(Map<String,Block> blockLookUp) Creates intermediate blocks that may not have been explicitly specified.
protected static boolean	boolType(String thing, String col) Returns the internal boolean representation of a boolean-valued input to CSV or JSON.
protected void	initializeAllOneBlock(Survey survey) Initializes a block-less survey as a survey of one block.
abstract Survey	parse() The main entry point.
protected static Boolean	parseBool(Boolean bool, String col, String entry, int lineNo, int colNo) Parses the boolean input and ensures that boolean values are consistent across option entries.
static SurveyDatum	parseComponent(String contents, int row, int col, int index) Parses Question and Option column data into the internal representation.
protected void	propagateBranchParadigm(Block b) Traverses the structure of the block and its sub-blocks to ensure that the block/branch type is properly set.
protected void	propagateBranchParadigms(Survey survey) Iterates over the top-level blocks of the survey and calls propagateBranchParadigm(edu.umass.cs.surveyman.survey.Block).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

defaultValues

public static final HashMap<String,Boolean> defaultValues

Holds a map from the column name to its default value.

QUESTION

public static final String QUESTION

The question column header/JSON key.

See Also:

Constant Field Values

BLOCK

public static final String BLOCK

The block column header/JSON key.

See Also:

Constant Field Values

OPTIONS

public static final String OPTIONS

The options column header/JSON key.

See Also:

Constant Field Values

RESOURCE

@Deprecated
public static final String RESOURCE

Deprecated.

The resource column header/JSON key.

See Also:

Constant Field Values

EXCLUSIVE

public static final String EXCLUSIVE

The exclusive column header/JSON key. Used to indicate that answer options are mutually exclusive. The default value is true.

See Also:

Constant Field Values

ORDERED

public static final String ORDERED

The ordered column header/JSON key. Used to indicate that answer options' order is semantically meaningful. The default value is false.

See Also:

Constant Field Values

RANDOMIZE

public static final String RANDOMIZE

The randomize column header/JSON key. Used to indicate that the options may be shuffled. The default value is true.

See Also:

Constant Field Values

BRANCH

public static final String BRANCH

The branch column/JSON key.

See Also:

Constant Field Values

FREETEXT

public static final String FREETEXT

The freetext column header/JSON key. The default value is false.

See Also:

Constant Field Values

CORRELATION

public static final String CORRELATION

The correlation column header/JSON key.

See Also:

Constant Field Values

ANSWER

public static final String ANSWER

The expected response column header/JSON key. If the question is not freetext, this is boolean-valued.

See Also:

Constant Field Values

PERMIT_BREAKOFF

public static final String PERMIT_BREAKOFF

Whether breakoff is premitted for the survey as a whole.

See Also:

Constant Field Values

INPUT_SCHEMA

public static final String INPUT_SCHEMA

The schema against which JSON input is validated.

See Also:

Constant Field Values

knownHeaders

public static final String[] knownHeaders

An array of semantically meaningful column headers.

CUSTOM_ID

public static final String CUSTOM_ID

The identifier used for ad hoc responses (e.g., timing information).

See Also:

Constant Field Values

LOGGER

protected static final org.apache.logging.log4j.spi.ExtendedLogger LOGGER

topLevelBlocks

protected List<Block> topLevelBlocks

The top-level blocks in the survey.

allBlockLookUp

protected Map<String,Block> allBlockLookUp

All blocks in the survey (including sub-blocks).

correlationMap

protected Map<String,List<Question>> correlationMap

A map from correlation labels to their associated set of questions.

Constructor Detail

AbstractParser

public AbstractParser()

Method Detail

boolType

protected static boolean boolType(String thing,
               String col)
                           throws SurveyException

Returns the internal boolean representation of a boolean-valued input to CSV or JSON.

Parameters:

thing - The raw text being parsed.

col - The associated column/key (used for debugging).

Returns:

Internal boolean representation of the input data.

Throws:

SurveyException

parseBool

protected static Boolean parseBool(Boolean bool,
                String col,
                String entry,
                int lineNo,
                int colNo)
                            throws SurveyException

Parses the boolean input and ensures that boolean values are consistent across option entries.

Parameters:

bool - The Boolean whose data must be consistent across entries.

col - The column name.

entry - The data in that column.

lineNo - The line number (row) of the data.

colNo - The column position in the input.

Returns:

Boxed Boolean representation of the input boolean data.

Throws:

SurveyException

parseComponent

public static SurveyDatum parseComponent(String contents,
                         int row,
                         int col,
                         int index)

Parses Question and Option column data into the internal representation.

Parameters:

contents - The input data.

row - The line number (row) of the data.

col - The column position of the data.

Returns:

SurveyDatum internal representation of the data.

addPhantomBlocks

protected static void addPhantomBlocks(Map<String,Block> blockLookUp)

Creates intermediate blocks that may not have been explicitly specified. For example, a CSV following the numbering scheme 1.1, 1.2, 2.1, 2.2, ... will not have explicit top-level blocks. This method will generate blocks 1, 2, ... etc. All parent/child references are validated and/or set here.

Parameters:

blockLookUp - Map of all blocks.

propagateBranchParadigm

protected void propagateBranchParadigm(Block b)
                                throws SurveyException

Traverses the structure of the block and its sub-blocks to ensure that the block/branch type is properly set. See Block.BranchParadigm for a detailed explanation of the block/branch type lattice.

Parameters:

b - A block whose type needs to be set.

Throws:

SurveyException

propagateBranchParadigms

protected void propagateBranchParadigms(Survey survey)
                                 throws SurveyException

Iterates over the top-level blocks of the survey and calls propagateBranchParadigm(edu.umass.cs.surveyman.survey.Block). See Block.BranchParadigm for a detailed explanation of the block/branch type lattice.

Parameters:

survey - A block whose type needs to be set.

Throws:

SurveyException

initializeAllOneBlock

protected void initializeAllOneBlock(Survey survey)

Initializes a block-less survey as a survey of one block.

Parameters:

survey - A flat, fully randomizable survey.

parse

public abstract Survey parse()
                      throws SurveyException

The main entry point.

Returns:

The internal representation of the survey.

Throws:

SurveyException