dev.dejvokep.boostedyaml

Class YamlDocument

java.lang.Object

dev.dejvokep.boostedyaml.block.Block<Map<Object,Block<?>>>

dev.dejvokep.boostedyaml.block.implementation.Section

dev.dejvokep.boostedyaml.YamlDocument

public class YamlDocument
extends Section

Represents a YAML document.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	YamlDocument(File document, InputStream defaults, Settings... settings) Creates and loads a YAML document from the given file and loads the defaults (another YAML document, later accessible via getDefaults()) from the defaults stream, if provided.
protected	YamlDocument(InputStream document, InputStream defaults, Settings... settings) Creates and loads a YAML document from the given stream and loads the defaults (another YAML document, later accessible via getDefaults()) from the defaults stream, if provided.

Method Summary

Modifier and Type	Method and Description
static YamlDocument	create(File document, InputStream defaults, Settings... settings) Creates and loads a YAML document from the given file and loads the defaults (another YAML document, later accessible via getDefaults()) from the defaults stream.
static YamlDocument	create(File document, Settings... settings) Creates and loads a YAML document from the given file.
static YamlDocument	create(InputStream document, InputStream defaults, Settings... settings) Creates and loads a YAML document from the given stream and loads the defaults (another YAML document, later accessible via getDefaults()) from the defaults stream.
static YamlDocument	create(InputStream document, Settings... settings) Creates and loads a YAML document from the given stream.
String	dump() Dumps the contents to a string using the associated dumper and general settings.
String	dump(DumperSettings dumperSettings) Dumps the contents to a string using the given dumper and associated general settings.
YamlDocument	getDefaults() Returns the defaults associated with the document, if any were given to YamlDocument.create() method.
DumperSettings	getDumperSettings() Returns the dumper settings associated with the file.
File	getFile() Returns the file associated with this document, if any were given to YamlDocument.create() method.
GeneralSettings	getGeneralSettings() Returns the general settings associated with the file.
LoaderSettings	getLoaderSettings() Returns the loader settings associated with the file.
UpdaterSettings	getUpdaterSettings() Returns the updater settings associated with the file.
boolean	isRoot() Returns whether this section is simultaneously the root section (file).
boolean	reload() Reloads the contents from the associated file using the associated loader and general settings.
void	reload(InputStream inputStream) Reloads the contents from the given stream using the associated loader and general settings.
void	reload(InputStream inputStream, LoaderSettings loaderSettings) Reloads the contents from the given stream using the given loader and associated general settings.
boolean	save() Saves the contents to the associated file using the associated dumper and general settings, in UTF-8 charset.
void	save(File file) Saves the contents to the given file using the associated dumper and general settings, in UTF-8 charset.
void	save(OutputStream stream, Charset charset) Saves the contents to the given stream using the associated dumper and general settings, in the given charset.
void	save(OutputStreamWriter writer) Saves the contents to the given writer using the associated dumper and general settings.
void	setDumperSettings(DumperSettings dumperSettings) Deprecated. replaced by setSettings(Settings...) and subject for removal
void	setGeneralSettings(GeneralSettings generalSettings) Deprecated. replaced by setSettings(Settings...) and subject for removal
void	setLoaderSettings(LoaderSettings loaderSettings) Deprecated. replaced by setSettings(Settings...) and subject for removal
void	setSettings(Settings... settings) Sets new settings to be used by this document, overwriting the previous settings associated with this document.
void	setUpdaterSettings(UpdaterSettings updaterSettings) Deprecated. replaced by setSettings(Settings...) and subject for removal
boolean	update() Updates the contents against the associated defaults using the associated updater and general settings.
void	update(InputStream defaults) Updates the contents against the given defaults using the associated updater and general settings.
void	update(InputStream defaults, UpdaterSettings updaterSettings) Updates the contents against the given defaults using the given updater and associated general settings.
boolean	update(UpdaterSettings updaterSettings) Updates the contents against the associated defaults using the given updater and associated general settings.

Methods inherited from class dev.dejvokep.boostedyaml.block.implementation.Section

adaptKey, clear, contains, contains, createSection, createSection, get, get, get, get, getAs, getAs, getAs, getAs, getAsOptional, getAsOptional, getBigInt, getBigInt, getBigInt, getBigInt, getBigIntList, getBigIntList, getBigIntList, getBigIntList, getBlock, getBlock, getBoolean, getBoolean, getBoolean, getBoolean, getByte, getByte, getByte, getByte, getByteList, getByteList, getByteList, getByteList, getDouble, getDouble, getDouble, getDouble, getDoubleList, getDoubleList, getDoubleList, getDoubleList, getEnum, getEnum, getEnum, getEnum, getFloat, getFloat, getFloat, getFloat, getFloatList, getFloatList, getFloatList, getFloatList, getChar, getChar, getChar, getChar, getInt, getInt, getInt, getInt, getIntList, getIntList, getIntList, getIntList, getKeys, getList, getList, getList, getList, getLong, getLong, getLong, getLong, getLongList, getLongList, getLongList, getLongList, getMapList, getMapList, getMapList, getMapList, getName, getNameAsRoute, getNameAsString, getNumber, getNumber, getNumber, getNumber, getOptional, getOptional, getOptionalBigInt, getOptionalBigInt, getOptionalBigIntList, getOptionalBigIntList, getOptionalBlock, getOptionalBlock, getOptionalBoolean, getOptionalBoolean, getOptionalByte, getOptionalByte, getOptionalByteList, getOptionalByteList, getOptionalDouble, getOptionalDouble, getOptionalDoubleList, getOptionalDoubleList, getOptionalEnum, getOptionalEnum, getOptionalFloat, getOptionalFloat, getOptionalFloatList, getOptionalFloatList, getOptionalChar, getOptionalChar, getOptionalInt, getOptionalInt, getOptionalIntList, getOptionalIntList, getOptionalList, getOptionalList, getOptionalLong, getOptionalLong, getOptionalLongList, getOptionalLongList, getOptionalMapList, getOptionalMapList, getOptionalNumber, getOptionalNumber, getOptionalSection, getOptionalSection, getOptionalShort, getOptionalShort, getOptionalShortList, getOptionalShortList, getOptionalString, getOptionalString, getOptionalStringList, getOptionalStringList, getParent, getParent, getParent, getRoot, getRoute, getRouteAsString, getRouteMappedBlocks, getRouteMappedValues, getRoutes, getRoutesAsStrings, getSection, getSection, getSection, getSection, getShort, getShort, getShort, getShort, getShortList, getShortList, getShortList, getShortList, getString, getString, getString, getString, getStringList, getStringList, getStringList, getStringList, getStringRouteMappedBlocks, getStringRouteMappedValues, getSubRoute, hasDefaults, init, initEmpty, is, is, isBigInt, isBigInt, isBoolean, isBoolean, isByte, isByte, isDecimal, isDecimal, isDouble, isDouble, isEmpty, isEnum, isEnum, isFloat, isFloat, isChar, isChar, isInt, isInt, isList, isList, isLong, isLong, isNumber, isNumber, isSection, isSection, isSection, isShort, isShort, isString, isString, move, move, remove, remove, repopulate, set, set, setAll

Methods inherited from class dev.dejvokep.boostedyaml.block.Block

addComment, addComments, getComments, getStoredValue, init, isIgnored, removeComments, setComments, setIgnored, setValue

Methods inherited from class java.lang.Object

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

Constructor Detail

YamlDocument

protected YamlDocument(@NotNull
                       InputStream document,
                       @Nullable
                       InputStream defaults,
                       @NotNull
                       Settings... settings)
                throws IOException

Creates and loads a YAML document from the given stream and loads the defaults (another YAML document, later accessible via getDefaults()) from the defaults stream, if provided.

The provided settings will be stored and used by this document and the defaults. You can overwrite them using setSettings(Settings...)). If settings of any type are not provided, their defaults (e.g. GeneralSettings.DEFAULT) are used.

If any of the given objects is not an instance of GeneralSettings, LoaderSettings, DumperSettings nor UpdaterSettings, an IllegalArgumentException will be thrown. If there are multiple instances of the same settings type, the last one will take effect.

Please note that methods without an I/O parameter will not be usable. Refer to the method documentation for more information.

Parameters:

document - document

defaults - defaults

settings - settings

Throws:

IOException - an IO error

YamlDocument

protected YamlDocument(@NotNull
                       File document,
                       @Nullable
                       InputStream defaults,
                       @NotNull
                       Settings... settings)
                throws IOException

Creates and loads a YAML document from the given file and loads the defaults (another YAML document, later accessible via getDefaults()) from the defaults stream, if provided.

The provided settings will be stored and used by this document and the defaults. You can overwrite them using setSettings(Settings...)). If settings of any type are not provided, their defaults (e.g. GeneralSettings.DEFAULT) are used.

If any of the given objects is not an instance of GeneralSettings, LoaderSettings, DumperSettings nor UpdaterSettings, an IllegalArgumentException will be thrown. If there are multiple instances of the same settings type, the last one will take effect.

If the given File does not exist, the document will be loaded from a copy of the defaults. If enabled, the file will automatically be created.

Parameters:

document - document (does not need to exist)

defaults - defaults

settings - settings

Throws:

IOException - an IO error

Method Detail

reload

public boolean reload()
               throws IOException

Reloads the contents from the associated file using the associated loader and general settings.

Returns if the operation was successful - false if there is no associated file, true otherwise.

If the file does not exist, the document will be reloaded from a copy of the defaults (or empty if there are not any). Unless disabled, the file will automatically be created and saved.

Returns:

if the operation was successful (see getFile())

Throws:

IOException - an IO error

reload

public void reload(@NotNull
                   InputStream inputStream)
            throws IOException

Reloads the contents from the given stream using the associated loader and general settings.

If there is any associated file and it does not exist, unless disabled, the file will automatically be created and saved.

Parameters:

inputStream - file to reload from

Throws:

IOException - an IO error

reload

public void reload(@NotNull
                   InputStream inputStream,
                   @NotNull
                   LoaderSettings loaderSettings)
            throws IOException

Reloads the contents from the given stream using the given loader and associated general settings.

If there is any associated file and it does not exist, unless disabled, the file will automatically be created and saved.

Parameters:

inputStream - file to reload from

loaderSettings - loader settings to use

Throws:

IOException - an IO error

update

public boolean update()
               throws IOException

Updates the contents against the associated defaults using the associated updater and general settings.

Returns if the operation was successful - false if there are no defaults, true otherwise.

Returns:

if the operation was successful (see getDefaults())

Throws:

IOException - an IO error

update

public boolean update(@NotNull
                      UpdaterSettings updaterSettings)
               throws IOException

Updates the contents against the associated defaults using the given updater and associated general settings.

Returns if the operation was successful - false if there are no defaults, true otherwise.

Parameters:

updaterSettings - updater settings to use

Returns:

if the operation was successful (see getDefaults())

Throws:

IOException - an IO error

update

public void update(@NotNull
                   InputStream defaults)
            throws IOException

Updates the contents against the given defaults using the associated updater and general settings.

Please note that this involves loading a YAML document from the given stream. If you'd like to update, but don't want the defaults to be used in any other means, you can disable use of them via GeneralSettings.Builder#setUseDefaults(boolean) and provide the defaults right to the YamlDocument.create() method.

Parameters:

defaults - defaults to load and update against

Throws:

IOException - an IO error

update

public void update(@NotNull
                   InputStream defaults,
                   @NotNull
                   UpdaterSettings updaterSettings)
            throws IOException

Updates the contents against the given defaults using the given updater and associated general settings.

Please note that this involves loading a YAML document from the given stream. If you'd like to update, but don't want the defaults to be used in any other means, you can disable use of them via GeneralSettings.Builder#setUseDefaults(boolean) and provide the defaults right to the YamlDocument.create() method.

Parameters:

defaults - defaults to load and update against

updaterSettings - updater settings to use

Throws:

IOException - an IO error

save

public boolean save()
             throws IOException

Saves the contents to the associated file using the associated dumper and general settings, in UTF-8 charset.

Returns if the operation was successful - false if there is no associated file, true otherwise.

Returns:

if the operation was successful (see getFile())

Throws:

IOException - an IO error

save

public void save(@NotNull
                 File file)
          throws IOException

Saves the contents to the given file using the associated dumper and general settings, in UTF-8 charset.

Parameters:

file - file to save to

Throws:

IOException - an IO error

save

public void save(@NotNull
                 OutputStream stream,
                 Charset charset)
          throws IOException

Saves the contents to the given stream using the associated dumper and general settings, in the given charset.

Parameters:

stream - stream to save to

charset - charset to use

Throws:

IOException - an IO error

save

public void save(@NotNull
                 OutputStreamWriter writer)
          throws IOException

Saves the contents to the given writer using the associated dumper and general settings.

Parameters:

writer - writer to save to

Throws:

IOException - an IO error

dump

public String dump()

Dumps the contents to a string using the associated dumper and general settings.

Returns:

the dumped contents

dump

public String dump(@NotNull
                   DumperSettings dumperSettings)

Dumps the contents to a string using the given dumper and associated general settings.

Parameters:

dumperSettings - dumper settings to use

Returns:

the dumped contents

setSettings

public void setSettings(@NotNull
                        Settings... settings)

Sets new settings to be used by this document, overwriting the previous settings associated with this document.

If you are changing GeneralSettings:

• It is required that the GeneralSettings.getKeyFormat() is the same as the one defined by getGeneralSettings() (settings currently in use by the document). Such attempt will result in an IllegalArgumentException; to update the key format, recreate the document.
• Changing the default list, map or set suppliers will only affect collections created from now on.

If any of the given objects is not an instance of GeneralSettings, LoaderSettings, DumperSettings nor UpdaterSettings, an IllegalArgumentException will be thrown. If there are multiple instances of the same settings type, the last one will take effect.

Parameters:

settings - the new settings

setLoaderSettings

@Deprecated
public void setLoaderSettings(@NotNull
                                           LoaderSettings loaderSettings)

Deprecated. replaced by setSettings(Settings...) and subject for removal

Associates new loader settings.

Parameters:

loaderSettings - the new loader settings

setDumperSettings

public void setDumperSettings(@NotNull
                              DumperSettings dumperSettings)

Deprecated. replaced by setSettings(Settings...) and subject for removal

Associates new dumper settings.

Parameters:

dumperSettings - the new dumper settings

setGeneralSettings

public void setGeneralSettings(@NotNull
                               GeneralSettings generalSettings)

Deprecated. replaced by setSettings(Settings...) and subject for removal

Associates new general settings.

WARNING!

• Never change the key format! Such attempts will result in an IllegalArgumentException.
• If the default list, map or set was changed, already existing instances will not be changed. Reload to take effect.

Parameters:

generalSettings - the new general settings

setUpdaterSettings

public void setUpdaterSettings(@NotNull
                               UpdaterSettings updaterSettings)

Deprecated. replaced by setSettings(Settings...) and subject for removal

Associates new updater settings.

Parameters:

updaterSettings - the new updater settings

getDefaults

@Nullable
public YamlDocument getDefaults()

Returns the defaults associated with the document, if any were given to YamlDocument.create() method.

If there are no defaults, returns null.

Overrides:

getDefaults in class Section

Returns:

the associated defaults

See Also:

Section.hasDefaults()

getGeneralSettings

@NotNull
public GeneralSettings getGeneralSettings()

Returns the general settings associated with the file.

Returns:

the associated general settings

getDumperSettings

@NotNull
public DumperSettings getDumperSettings()

Returns the dumper settings associated with the file.

Returns:

the associated dumper settings

getUpdaterSettings

@NotNull
public UpdaterSettings getUpdaterSettings()

Returns the updater settings associated with the file.

Returns:

the associated updater settings

getLoaderSettings

@NotNull
public LoaderSettings getLoaderSettings()

Returns the loader settings associated with the file.

Returns:

the associated loader settings

getFile

@Nullable
public File getFile()

Returns the file associated with this document, if any were given to YamlDocument.create() method.

If there are no defaults, returns null.

Returns:

the associated file

isRoot

public boolean isRoot()

Description copied from class: Section

Returns whether this section is simultaneously the root section (file).

Overrides:

isRoot in class Section

Returns:

if this section is the root section

create

public static YamlDocument create(@NotNull
                                  File document,
                                  @NotNull
                                  InputStream defaults,
                                  @NotNull
                                  Settings... settings)
                           throws IOException

Creates and loads a YAML document from the given file and loads the defaults (another YAML document, later accessible via getDefaults()) from the defaults stream.

The provided settings will be stored and used by this document and the defaults. You can overwrite them using setSettings(Settings...)). If settings of any type are not provided, their defaults (e.g. GeneralSettings.DEFAULT) are used.

If any of the given objects is not an instance of GeneralSettings, LoaderSettings, DumperSettings nor UpdaterSettings, an IllegalArgumentException will be thrown. If there are multiple instances of the same settings type, the last one will take effect.

If the given File does not exist, the document will be loaded from a copy of the defaults. If enabled, the file will automatically be created.

Parameters:

document - document (does not need to exist)

defaults - defaults

settings - settings

Returns:

the created and loaded document

Throws:

IOException - an IO error

create

public static YamlDocument create(@NotNull
                                  InputStream document,
                                  @NotNull
                                  InputStream defaults,
                                  @NotNull
                                  Settings... settings)
                           throws IOException

Creates and loads a YAML document from the given stream and loads the defaults (another YAML document, later accessible via getDefaults()) from the defaults stream.

The provided settings will be stored and used by this document and the defaults. You can overwrite them using setSettings(Settings...)). If settings of any type are not provided, their defaults (e.g. GeneralSettings.DEFAULT) are used.

If any of the given objects is not an instance of GeneralSettings, LoaderSettings, DumperSettings nor UpdaterSettings, an IllegalArgumentException will be thrown. If there are multiple instances of the same settings type, the last one will take effect.

Please note that methods without an I/O parameter will not be usable. Refer to the method documentation for more information.

Parameters:

document - document

defaults - defaults

settings - settings

Returns:

the created and loaded document

Throws:

IOException - an IO error

create

public static YamlDocument create(@NotNull
                                  File document,
                                  @NotNull
                                  Settings... settings)
                           throws IOException

Creates and loads a YAML document from the given file. The returned document will not have any defaults.

The provided settings will be stored and used by this document and the defaults. You can overwrite them using setSettings(Settings...)). If settings of any type are not provided, their defaults (e.g. GeneralSettings.DEFAULT) are used.

If any of the given objects is not an instance of GeneralSettings, LoaderSettings, DumperSettings nor UpdaterSettings, an IllegalArgumentException will be thrown. If there are multiple instances of the same settings type, the last one will take effect.

If the given File does not exist, the document will be loaded from a copy of the defaults. If enabled, the file will automatically be created.

Parameters:

document - document (does not need to exist)

settings - settings

Returns:

the created and loaded document

Throws:

IOException - an IO error

create

public static YamlDocument create(@NotNull
                                  InputStream document,
                                  @NotNull
                                  Settings... settings)
                           throws IOException

Creates and loads a YAML document from the given stream. The returned document will not have any defaults.

The provided settings will be stored and used by this document and the defaults. You can overwrite them using setSettings(Settings...)). If settings of any type are not provided, their defaults (e.g. GeneralSettings.DEFAULT) are used.

If any of the given objects is not an instance of GeneralSettings, LoaderSettings, DumperSettings nor UpdaterSettings, an IllegalArgumentException will be thrown. If there are multiple instances of the same settings type, the last one will take effect.

Please note that methods without an I/O parameter will not be usable. Refer to the method documentation for more information.

Parameters:

document - document

settings - settings

Returns:

the created and loaded document

Throws:

IOException - an IO error