squidpony

Class ObText

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractList<E>

java.util.ArrayList<ObText.ObTextEntry>

squidpony.ObText

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.lang.Iterable<ObText.ObTextEntry>, java.util.Collection<ObText.ObTextEntry>, java.util.List<ObText.ObTextEntry>, java.util.RandomAccess

public class ObText
extends java.util.ArrayList<ObText.ObTextEntry>
implements java.io.Serializable

A simple format parser for String-based configuration or data files where JSON is overkill. Supports only one type, String, but allows each String to have arbitrary nested levels of String children as if in sub-lists. You can interpret the Strings however you want, and quoting each String isn't necessary if they are just one word ("bare words" are allowed). This stores its items in an inner class, ObText.ObTextEntry, which only has a "primary" String and may have a List of "associated" ObTextEntry values, each of which must have their own primary String and which may have their own associated List.
You can use this like any other List, though it will be contain ObTextEntry objects instead of Strings directly. This allows you to control whether you want to iterate through a particular primary String's associated entries, if there are any, or to skip over them and go to the next String in the current List.
This extends ArrayList of ObTextEntry and is modifiable, but it doesn't act quite like what what you might expect from an ArrayList. Chiefly, this only considers the top-level Strings to be part of the List for length and for ArrayList.contains(Object), and will ignore child strings unless you access them via the ObText.ObTextEntry.associated List on an entry that has associated entries.
A common way to use this is with parse(CharSequence) to read a String in the following format.
Format example:

 hello world
 'how are you today?' [just great thanks]
 hooray!

 complexity?
 [it is possible [yes this is a good example]
 'escapes like \[\'\] all work'
 "you can use double or single quotes to allow spaces and brackets in one string"
 ]

 comments are allowed // like this
 comments can have different forms # like this
 // block comments like in c are allowed
 / * but because this example is in javadoc, this example is not actually a comment * /
 // remove the spaces between each slash and asterisk to make the last line a comment.
 /[delimit/or block comments with delimiters/delimit]/

 '''
 raw strings (heredocs) look like this normally.
     they permit characters without escapes, ]][][[ \/\/\ ,
     except for triple quotes.
     they keep newlines and indentation intact,
 except for up to one newline ignored adjacent to each triple quote.
 '''

 [[different[
 if you may need triple quotes
     in the raw string, use a different syntax that allows delimiters.
 here, the delimiter is '''different''', just to be different.]different]]
 

Inspired strongly by STOB and its Java port , but no code is shared and the format is slightly different. The main differences are:

• We use square brackets in place of STOB's curly braces to mark children associated with a string.
• ObText supports nested block comments using the syntax /[delimiter/contents/delimiter]/ where delimiter may be empty but must match on both sides, and contents is the body of the comment.
• ObText uses Python-like "heredoc" syntax for raw strings surrounded by triple-apostrophes '''like so''' with optional initial and final newlines in the raw string ignored. An alternate raw string syntax is present that allows delimiters, using the syntax [[delimiter[contents]delimiter]], where again delimiter may be empty and contents is the body of the raw string.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ObText.ContentMatcher
static class	ObText.ObTextEntry

Field Summary

Fields

Modifier and Type	Field and Description
protected static regexodus.Matcher	bare
static int	closeId
protected static regexodus.Pattern	illegalBareWord
protected static regexodus.Matcher	m
protected static regexodus.Pattern	needsRaw
static int	openId
static regexodus.Pattern	pattern
static regexodus.Pattern	patternRelaxed
protected static regexodus.Matcher	raw
protected static regexodus.Matcher	reallyBare
protected static regexodus.Pattern	reallyIllegalBareWord
static int	stringId

Fields inherited from class java.util.AbstractList

modCount

Constructor Summary

Constructors

Constructor and Description
ObText()
ObText(java.lang.CharSequence text)

Method Summary

Modifier and Type	Method and Description
void	add(int index, java.lang.String text) Inserts the given String element at the specified position in this ObText's top level.
boolean	add(java.lang.String text) Appends the given String element to the end of this ObText at the top level.
static void	appendQuoted(java.lang.StringBuilder sb, java.lang.String text)
protected static void	appendQuoted(java.lang.StringBuilder sb, java.lang.String text, regexodus.Matcher bareFinder)
static void	appendQuotedObText(java.lang.StringBuilder sb, java.lang.String text)
java.util.HashMap<java.lang.String,java.lang.String>	basicMap() Gets all unique Strings from the top level of this ObText as keys in a HashMap, with the first String associated with each key as its value (or null if nothing is associated with a key String).
OrderedMap<java.lang.String,java.lang.String>	basicOrderedMap() Gets all unique Strings from the top level of this ObText as keys in an OrderedMap, with the first String associated with each key as its value (or null if nothing is associated with a key String).
static ObText	deserializeFromString(java.lang.String data) Deserializes an ObText that was serialized by serializeToString() or toString(), and will ignore the prefix and suffix that toString appends for readability (these are "ObText object: [[[[ " and " ]]]]", for reference).
long	hash64()
int	hashCode()
java.util.ArrayList<java.lang.String>	keyList() Gets all Strings from the top level of this ObText, not including any associated values, and puts them in an ArrayList of String.
OrderedSet<java.lang.String>	keyOrderedSet() Gets all unique Strings from the top level of this ObText, not including any associated values, and puts them in an OrderedSet of String.
java.util.HashSet<java.lang.String>	keySet() Gets all unique Strings from the top level of this ObText, not including any associated values, and puts them in a HashSet of String.
static ObText.ContentMatcher	makeMatcher() Can be used to help reading sequences of Strings with ObText-style quotation marking their boundaries.
static ObText.ContentMatcher	makeMatcher(java.lang.CharSequence text) Can be used to help reading sequences of Strings with ObText-style quotation marking their boundaries.
static ObText.ContentMatcher	makeMatcherNoComments(java.lang.CharSequence text) Can be used to help reading sequences of Strings with ObText-style quotation marking their boundaries, but no comments (which allows some additional characters to be used in bare words, like '#').
ObText	parse(java.lang.CharSequence text) Parses the given text (a String or other CharSequence) and appends it into this ObText.
java.lang.String	serializeToString()
java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>>	shallowMap() Gets all unique Strings from the top level of this ObText as keys in a HashMap, with any Strings associated with those keys as their values (in a possibly-empty ArrayList of String for each value).
OrderedMap<java.lang.String,java.util.ArrayList<java.lang.String>>	shallowOrderedMap() Gets all unique Strings from the top level of this ObText as keys in an OrderedMap, with any Strings associated with those keys as their values (in a possibly-empty ArrayList of String for each value).
java.lang.String	toString()

Methods inherited from class java.util.ArrayList

add, add, addAll, addAll, clear, clone, contains, ensureCapacity, forEach, get, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, removeIf, removeRange, replaceAll, retainAll, set, size, sort, spliterator, subList, toArray, toArray, trimToSize

Methods inherited from class java.util.AbstractList

equals

Methods inherited from class java.util.AbstractCollection

containsAll

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.List

containsAll, equals

Methods inherited from interface java.util.Collection

parallelStream, stream

Field Detail

pattern

public static final regexodus.Pattern pattern

patternRelaxed

public static final regexodus.Pattern patternRelaxed

stringId

public static final int stringId

openId

public static final int openId

closeId

public static final int closeId

illegalBareWord

protected static final regexodus.Pattern illegalBareWord

reallyIllegalBareWord

protected static final regexodus.Pattern reallyIllegalBareWord

needsRaw

protected static final regexodus.Pattern needsRaw

m

protected static final regexodus.Matcher m

bare

protected static final regexodus.Matcher bare

raw

protected static final regexodus.Matcher raw

reallyBare

protected static final regexodus.Matcher reallyBare

Constructor Detail

ObText

public ObText()

ObText

public ObText(java.lang.CharSequence text)

Method Detail

parse

public ObText parse(java.lang.CharSequence text)

Parses the given text (a String or other CharSequence) and appends it into this ObText.

Parameters:

text - a CharSequence (such as a String) using ObText formatting, as described in this class' JavaDocs

Returns:

this ObText object after appending the parsed text, for chaining

add

public void add(int index,
                java.lang.String text)

Inserts the given String element at the specified position in this ObText's top level. Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).

Parameters:

index - index at which the specified element is to be inserted

text - String element to be inserted, without any associated entries

add

public boolean add(java.lang.String text)

Appends the given String element to the end of this ObText at the top level.

Parameters:

text - String element to be inserted, without any associated entries

Returns:

true (this always modifies the ObText)

hash64

public long hash64()

hashCode

public int hashCode()

Specified by:

hashCode in interface java.util.Collection<ObText.ObTextEntry>

Specified by:

hashCode in interface java.util.List<ObText.ObTextEntry>

Overrides:

hashCode in class java.util.AbstractList<ObText.ObTextEntry>

appendQuoted

public static void appendQuoted(java.lang.StringBuilder sb,
                                java.lang.String text)

appendQuotedObText

public static void appendQuotedObText(java.lang.StringBuilder sb,
                                      java.lang.String text)

appendQuoted

protected static void appendQuoted(java.lang.StringBuilder sb,
                                   java.lang.String text,
                                   regexodus.Matcher bareFinder)

toString

public java.lang.String toString()

Overrides:

toString in class java.util.AbstractCollection<ObText.ObTextEntry>

serializeToString

public java.lang.String serializeToString()

deserializeFromString

public static ObText deserializeFromString(java.lang.String data)

Deserializes an ObText that was serialized by serializeToString() or toString(), and will ignore the prefix and suffix that toString appends for readability (these are "ObText object: [[[[ " and " ]]]]", for reference). This is otherwise the same as calling the constructor ObText(CharSequence).

Parameters:

data - a String that is usually produced by serializeToString or toString on an ObText

Returns:

a new ObText produced by parsing data (disregarding any prefix or suffix from toString() )

keyList

public java.util.ArrayList<java.lang.String> keyList()

Gets all Strings from the top level of this ObText, not including any associated values, and puts them in an ArrayList of String. The returned list will retain the same order the Strings were entered in, and unlike keySet() or keyOrderedSet(), duplicate keys will all be preserved. Changes to the returned List won't be reflected in this ObText.

Returns:

all top-level Strings (without associated values) as an ArrayList of String

keyOrderedSet

public OrderedSet<java.lang.String> keyOrderedSet()

Gets all unique Strings from the top level of this ObText, not including any associated values, and puts them in an OrderedSet of String. The returned set will retain the same order the Strings were entered in, and you can use OrderedSet methods like OrderedSet.getAt(int) to look up keys by index. Changes to the returned Set won't be reflected in this ObText.

Returns:

all unique top-level Strings (without associated values) as an OrderedSet of String keys

keySet

public java.util.HashSet<java.lang.String> keySet()

Gets all unique Strings from the top level of this ObText, not including any associated values, and puts them in a HashSet of String. The returned set won't be insertion-ordered or necessarily retain the same order the Strings were entered in; use keyOrderedSet() if you want this. Changes to the returned Set won't be reflected in this ObText.

Returns:

all unique top-level Strings (without associated values) as a HashSet of String keys

basicOrderedMap

public OrderedMap<java.lang.String,java.lang.String> basicOrderedMap()

Gets all unique Strings from the top level of this ObText as keys in an OrderedMap, with the first String associated with each key as its value (or null if nothing is associated with a key String). The returned map will retain the same order the keys were entered in, and you can use OrderedMap methods like OrderedMap.keyAt(int) to look up keys by index or OrderedMap.getAt(int) to look up value String by index. Changes to the returned Map won't be reflected in this ObText.

Returns:

an OrderedMap of unique String keys associated with the first associated String for each key (or null)

basicMap

public java.util.HashMap<java.lang.String,java.lang.String> basicMap()

Gets all unique Strings from the top level of this ObText as keys in a HashMap, with the first String associated with each key as its value (or null if nothing is associated with a key String). The returned map won't be insertion-ordered or necessarily retain the same order the Strings were entered in; use shallowOrderedMap() if you want this. Changes to the returned Map won't be reflected in this ObText.

Returns:

a HashMap of unique String keys associated with the first associated String for each key (or null)

shallowOrderedMap

public OrderedMap<java.lang.String,java.util.ArrayList<java.lang.String>> shallowOrderedMap()

Gets all unique Strings from the top level of this ObText as keys in an OrderedMap, with any Strings associated with those keys as their values (in a possibly-empty ArrayList of String for each value). The returned map will retain the same order the keys were entered in, and you can use OrderedMap methods like OrderedMap.keyAt(int) to look up keys by index or OrderedMap.getAt(int) to look up the ArrayList of value Strings by index. Changes to the returned Map won't be reflected in this ObText.

Returns:

an OrderedMap of unique String keys associated with ArrayList values containing associated Strings

shallowMap

public java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>> shallowMap()

Gets all unique Strings from the top level of this ObText as keys in a HashMap, with any Strings associated with those keys as their values (in a possibly-empty ArrayList of String for each value). The returned map won't be insertion-ordered or necessarily retain the same order the Strings were entered in; use basicOrderedMap() if you want this. Changes to the returned Map won't be reflected in this ObText.

Returns:

a HashMap of unique String keys associated with ArrayList values containing associated Strings

makeMatcher

public static ObText.ContentMatcher makeMatcher()

Can be used to help reading sequences of Strings with ObText-style quotation marking their boundaries. This returns a ObText.ContentMatcher object that you must call setTarget on before using it. The argument(s) to setTarget should be the text that might contain quotes, heredoc-style quotes, or just bare words. Calling Matcher.find() will try to find the next String, returning false if there's nothing left or returning true and advancing the search if a String was found. The String might be a special term in some cases, like "[" and "]" without quotes being syntax in ObText that don't contain usable Strings. That's why, after a String was found with find(), you should check ObText.ContentMatcher.hasMatch() to verify that a match was successful, and if that's true, then you can call ObText.ContentMatcher.getMatch() to get the un-quoted contents of the next String in the target.

Returns:

a ObText.ContentMatcher that must have one of its setTarget() methods called before it can be used

makeMatcher

public static ObText.ContentMatcher makeMatcher(java.lang.CharSequence text)

Can be used to help reading sequences of Strings with ObText-style quotation marking their boundaries. This returns a ObText.ContentMatcher object that is already configured to read from text. The text should contain Strings that may be surrounded by quotes, heredoc-style quotes, or just bare words. Calling Matcher.find() will try to find the next String, returning false if there's nothing left or returning true and advancing the search if a String was found. The String might be a special term in some cases, like "[" and "]" without quotes being syntax in ObText that don't contain usable Strings. That's why, after a String was found with find(), you should check ObText.ContentMatcher.hasMatch() to verify that a match was successful, and if that's true, then you can call ObText.ContentMatcher.getMatch() to get the un-quoted contents of the next String in the target.

Parameters:

text - the target String that should probably have at least one sub-string that might be quoted

Returns:

a ObText.ContentMatcher that can be used immediately by calling Matcher.find()

makeMatcherNoComments

public static ObText.ContentMatcher makeMatcherNoComments(java.lang.CharSequence text)

Can be used to help reading sequences of Strings with ObText-style quotation marking their boundaries, but no comments (which allows some additional characters to be used in bare words, like '#'). This returns a ObText.ContentMatcher object that is already configured to read from text. The text should contain Strings that may be surrounded by quotes, heredoc-style quotes, or just bare words. Calling Matcher.find() will try to find the next String, returning false if there's nothing left or returning true and advancing the search if a String was found. Unlike the ContentMatcher produced by makeMatcher(CharSequence), you can call ObText.ContentMatcher.getMatch() after any successful call to Matcher.find(), which will get the un-quoted contents of the next String in the target.

Parameters:

text - the target String that should probably have at least one sub-string that might be quoted

Returns:

a ObText.ContentMatcher that can be used immediately by calling Matcher.find()