org.crosswire.jsword.versification
Class VersificationToKJVMapper

java.lang.Object
  extended by org.crosswire.jsword.versification.VersificationToKJVMapper

public class VersificationToKJVMapper
extends Object

A Versification mapper allows you to a map a given verse to the KJV versification, or unmap it from the KJV versification into your own versification.

A properties-like file will contain the non-KJV versification as they key, and the KJV versification value as the target value... Duplicate keys are allowed.

i.e. Gen.1.1=Gen.1.2 means Gen.1.1 in X versification is Gen.1.2 in the KJV versification

You can specify a range on either side. If a range is present on both sides, they have to have the same number of verses, i.e. verses are mapped verse by verse to each other
Gen.1.1-Gen.1.2=Gen.1.2-Gen.1.3 means Gen.1.1=Gen.1.2 and Gen.1.2=Gen.1.3

Note: if the cardinality of the left & KJV sides are different by only one, the algorithm makes the assumption that verse 0 should be disregarded in both ranges.

Mappings can be specified by offset. In this case, be aware this maps verse 0 as well. So for example:

Ps.19-Ps.20=-1 means Ps.19.0=Ps.18.50, Ps.19.1=Ps.19.0, Ps.19.2=Ps.19.1, etc.
It does not make much sense to have an offset for a single verse, so this is not supported. Offsetting for multiple ranges however does, and operates range by range, i.e. each range is calculated separately. Offsetting is somewhat equivalent to specifying ranges, and as a result, the verse 0 behaviour is identical.

You can use part-mappings. This is important if you want to preserve transformations from one side to another without losing resolution of the verse.

For example,
if V1 defines Gen.1.1=Gen.1.1, Gen.1.2=Gen1.1
if V2 defines Gen.1.1=Gen.1.1, Gen.1.2=Gen.1.1
then, mapping from V1=>KJV and KJV=>V2 gives you Gen.1.1=>Gen.1.1=>Gen.1.1-Gen.1.2 which is inaccurate if in fact V1(Gen.1.1) actually equals V2(Gen.1.1). So instead, we use a split on the right hand-side:

For example,
V1 defines Gen.1.1=Gen1.1!a, Gen.1.2=Gen.1.1!b
V2 defines Gen.1.1=Gen1.1!a, Gen.1.2=Gen.1.1!b
then, mapping from V1=>KJV and KJV=>V2 gives you Gen.1.1=>Gen.1.1!a=>Gen.1.1, which is now accurate. A part is a string fragment placed after the end of a key reference. We cannot use # because that is commonly known as a comment in real properties-file. Using a marker, means we can have meaningful part names if we so choose. Parts of ranges are not supported.

Note: splits should never be seen by a user. The mapping from one versification to another is abstracted such that the user can simply request the mapping between 2 verse (ranges).

Unmapped verses can be specified by inventing ids, either for whole sections, or verse by verse (this would come in handy if two versifications have the same content, but the KJV doesn't). A section must be preceded with a '?' character indicating that there will be no need to try and look up a reference. Gen.1.1=?NewPassage

Since not specifying a verse mappings means there is a 1-2-1 unchanged mapping, we need a way of specifying absent verses altogether:
?=Gen.1.1
?=Gen.1.5
means that the non-KJV book simply does not contain verses Gen.1.1 and Gen.1.5 and therefore can't be mapped.

We allow some global flags (one at present):
!zerosUnmapped : means that any mapping to or from a zero verse

TODO(CJB): think about whether when returning, we should clone, or make things immutable.

Author:
chrisburrell
See Also:
The GNU Lesser General Public License for details.

Field Summary
private  Passage absentVerses
           
private  Map<QualifiedKey,Passage> fromKJVMappings
           
private  boolean hasErrors
           
private static Versification KJV
           
private static org.slf4j.Logger LOGGER
           
private  Versification nonKjv
           
private  OsisParser osisParser
           
private  Map<VerseKey,List<QualifiedKey>> toKJVMappings
           
 
Constructor Summary
VersificationToKJVMapper(Versification nonKjv, FileVersificationMapping mapping)
           
 
Method Summary
private  void add1ToManyMappings(Verse leftHand, QualifiedKey kjvHand)
          A simple two way entry between 2 1-1 entries.
private  void addForwardMappingFromSingleKeyToRange(Verse leftHand, QualifiedKey kjvHand)
          Adds a forward mappings from left to KJV.
private  void addKJVToMapping(QualifiedKey kjvVerses, Verse leftKey)
          If leftKey is non-null (i.e.
private  void addManyToMany(QualifiedKey leftHand, QualifiedKey kjvVerses)
          Adds a many to many mapping, mappings all the verses on the left hand side to all the verses on the right hand side.
private  void addMappings(QualifiedKey leftHand, QualifiedKey kjvVerses)
          Adds a 1-Many mapping, by simply listing out all the properties.
private  void addReverse1ToManyMappings(Verse leftHand, QualifiedKey kjvHand)
          Adds the data into the reverse mappings.
private  Passage createEmptyPassage(Versification versification)
          Simplify creation of an empty passage object of the default type, with the required v11n.
 void dump(PrintStream out)
          Dump a debug representation of this map to the output stream.
private  QualifiedKey getAbsentQualifiedKey(Versification versification, String versesKey)
          Deals with absent markers, whether absent in the KJV or absent in the current versification.
private  QualifiedKey getExistingQualifiedKey(Versification versification, String versesKey)
          Deals with real keys found in the versification.
private  VerseKey getNonEmptyKey(Map<QualifiedKey,Passage> mappings, QualifiedKey key)
          Gets a non-empty key list, either new or the one existing in the map already.
private
<T,S> List<S>
getNonEmptyMappings(Map<T,List<S>> mappings, T key)
          Gets a non-empty list, either new or the one existing in the map already
private  QualifiedKey getOffsetQualifiedKey(Versification versification, String versesKey, VerseKey offsetBasis)
          Deals with offset markers, indicating a passage is +x or -x verses from this one.
private  List<QualifiedKey> getQualifiedKeys(Key leftKey)
           
private  QualifiedKey getRange(Versification versification, String versesKey, VerseKey offsetBasis)
          Expands a reference to all its verses
(package private)  boolean hasErrors()
          Returns whether we initialised with errors
 List<QualifiedKey> map(QualifiedKey qualifiedKey)
          Maps the full qualified key to its proper equivalent in the KJV.
private  void processEntry(KeyValuePair entry)
           
private  void processMappings(FileVersificationMapping mappings)
          This is the crux of the decoding facility.
private  void reportCardinalityError(VerseKey leftKeys, VerseKey kjvKeys)
          If for some reason cardinalities of keys are different, we report it.
private  void trace()
          Outputs the mappings for debug purposes to the log file.
 VerseKey unmap(QualifiedKey kjvVerse)
          Converts a KJV verse to the target versification, from a qualified key, rather than a real key
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

nonKjv

private Versification nonKjv

absentVerses

private Passage absentVerses

toKJVMappings

private Map<VerseKey,List<QualifiedKey>> toKJVMappings

fromKJVMappings

private Map<QualifiedKey,Passage> fromKJVMappings

hasErrors

private boolean hasErrors

osisParser

private OsisParser osisParser

KJV

private static final Versification KJV

LOGGER

private static final org.slf4j.Logger LOGGER
Constructor Detail

VersificationToKJVMapper

public VersificationToKJVMapper(Versification nonKjv,
                                FileVersificationMapping mapping)
Parameters:
nonKjv - a versification that is not the KJV
mapping - the mappings from one versification to another
Method Detail

processMappings

private void processMappings(FileVersificationMapping mappings)
This is the crux of the decoding facility. The properties are expanded.

Parameters:
mappings - the input mappings, in a contracted, short-hand form

processEntry

private void processEntry(KeyValuePair entry)
                   throws NoSuchKeyException
Throws:
NoSuchKeyException

addMappings

private void addMappings(QualifiedKey leftHand,
                         QualifiedKey kjvVerses)
                  throws NoSuchVerseException
Adds a 1-Many mapping, by simply listing out all the properties. There is probably a better way for storing this, perhaps in a tree - but for simplicity, we're going to list them out.

Parameters:
leftHand - the left hand side operand
kjvVerses - the verses that are mapped by the left hand side
Throws:
NoSuchVerseException

addManyToMany

private void addManyToMany(QualifiedKey leftHand,
                           QualifiedKey kjvVerses)
Adds a many to many mapping, mappings all the verses on the left hand side to all the verses on the right hand side. We support 2 types: Many-to-1 and Many-to-Many.

Parameters:
leftHand - is assumed to be many
kjvVerses - could be 1 or many

reportCardinalityError

private void reportCardinalityError(VerseKey leftKeys,
                                    VerseKey kjvKeys)
If for some reason cardinalities of keys are different, we report it.

Parameters:
leftKeys - the left hand key
kjvKeys - the kjv qualified key

addKJVToMapping

private void addKJVToMapping(QualifiedKey kjvVerses,
                             Verse leftKey)
If leftKey is non-null (i.e. not attached to a simple specifier, then adds to the kjvTo mappings

Parameters:
kjvVerses - the kjv verses
leftKey - the left-hand key, possibly null.

add1ToManyMappings

private void add1ToManyMappings(Verse leftHand,
                                QualifiedKey kjvHand)
                         throws NoSuchVerseException
A simple two way entry between 2 1-1 entries.

Parameters:
leftHand - the verse on the left side, left is assumed to be 1 verse only
kjvHand - the KJV reference
Throws:
NoSuchVerseException

addReverse1ToManyMappings

private void addReverse1ToManyMappings(Verse leftHand,
                                       QualifiedKey kjvHand)
Adds the data into the reverse mappings. Caters for 1-2-1 and 1-2-Many mappings

Parameters:
leftHand - the reference of the left hand reference
kjvHand - the kjv reference/key, qualified with the part

addForwardMappingFromSingleKeyToRange

private void addForwardMappingFromSingleKeyToRange(Verse leftHand,
                                                   QualifiedKey kjvHand)
Adds a forward mappings from left to KJV.

Parameters:
leftHand - the left hand reference (corresponding to a non-kjv versification)
kjvHand - the kjv reference (with part if applicable).

getNonEmptyKey

private VerseKey getNonEmptyKey(Map<QualifiedKey,Passage> mappings,
                                QualifiedKey key)
Gets a non-empty key list, either new or the one existing in the map already.

Parameters:
mappings - the map from key to list of values
key - the key
Returns:
the non-empty mappings list

getNonEmptyMappings

private <T,S> List<S> getNonEmptyMappings(Map<T,List<S>> mappings,
                                          T key)
Gets a non-empty list, either new or the one existing in the map already

Type Parameters:
T - the type of the key
S - the type of the value
Parameters:
mappings - the map from key to list of values
key - the key
Returns:
the separate list of verses

getRange

private QualifiedKey getRange(Versification versification,
                              String versesKey,
                              VerseKey offsetBasis)
                       throws NoSuchKeyException
Expands a reference to all its verses

Parameters:
versesKey - the verses
Returns:
the separate list of verses
Throws:
NoSuchKeyException

getOffsetQualifiedKey

private QualifiedKey getOffsetQualifiedKey(Versification versification,
                                           String versesKey,
                                           VerseKey offsetBasis)
                                    throws NoSuchKeyException
Deals with offset markers, indicating a passage is +x or -x verses from this one.

Parameters:
versification - the versification of the passed in key
versesKey - the text of the reference we are trying to parse
Returns:
the qualified key representing this
Throws:
NoSuchKeyException

getExistingQualifiedKey

private QualifiedKey getExistingQualifiedKey(Versification versification,
                                             String versesKey)
Deals with real keys found in the versification.

Parameters:
versification - the versification of the passed in key
versesKey - the text of the reference we are trying to parse
Returns:
the qualified key representing this

getAbsentQualifiedKey

private QualifiedKey getAbsentQualifiedKey(Versification versification,
                                           String versesKey)
Deals with absent markers, whether absent in the KJV or absent in the current versification.

Parameters:
versification - the versification of the passed in key
versesKey - the text of the reference we are trying to parse
Returns:
the qualified key representing this

getQualifiedKeys

private List<QualifiedKey> getQualifiedKeys(Key leftKey)
Returns:
the qualified keys associated with the input key.

map

public List<QualifiedKey> map(QualifiedKey qualifiedKey)
Maps the full qualified key to its proper equivalent in the KJV.

Parameters:
qualifiedKey - the qualified key
Returns:
the list of matching qualified keys in the KJV versification.

unmap

public VerseKey unmap(QualifiedKey kjvVerse)
Converts a KJV verse to the target versification, from a qualified key, rather than a real key

Parameters:
kjvVerse - the verse from the KJV
Returns:
the key in the left-hand versification

trace

private void trace()
Outputs the mappings for debug purposes to the log file.


dump

public void dump(PrintStream out)
Dump a debug representation of this map to the output stream.

Parameters:
out -

hasErrors

boolean hasErrors()
Returns whether we initialised with errors


createEmptyPassage

private Passage createEmptyPassage(Versification versification)
Simplify creation of an empty passage object of the default type, with the required v11n.

Parameters:
versification - required v11n for new Passage
Returns:
empty Passage

Copyright ยจ 2003-2015