{"id":23722806,"url":"https://github.com/fulminazzo/yamlparser","last_synced_at":"2026-05-05T14:08:28.930Z","repository":{"id":213281058,"uuid":"728758820","full_name":"fulminazzo/YAMLParser","owner":"fulminazzo","description":"A Java library to handle non-primitive data types in YAML files. It is built upon the Bukkit FileConfiguration system.","archived":false,"fork":false,"pushed_at":"2025-05-25T18:38:34.000Z","size":217,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-14T19:36:18.115Z","etag":null,"topics":["github-actions","java","parser","yaml"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fulminazzo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-12-07T16:21:36.000Z","updated_at":"2025-05-25T18:18:30.000Z","dependencies_parsed_at":"2024-02-13T23:25:55.962Z","dependency_job_id":"8f759406-5bd5-44ab-a19a-2435a67c6da5","html_url":"https://github.com/fulminazzo/YAMLParser","commit_stats":null,"previous_names":["fulminazzo/yamlparser"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/fulminazzo/YAMLParser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fulminazzo%2FYAMLParser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fulminazzo%2FYAMLParser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fulminazzo%2FYAMLParser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fulminazzo%2FYAMLParser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fulminazzo","download_url":"https://codeload.github.com/fulminazzo/YAMLParser/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fulminazzo%2FYAMLParser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279020651,"owners_count":26086898,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github-actions","java","parser","yaml"],"created_at":"2024-12-30T23:56:54.364Z","updated_at":"2025-10-14T19:36:18.789Z","avatar_url":"https://github.com/fulminazzo.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"**Welcome to the official documentation of YAMLParser!**\n\nThis project aims to provide a simple way of **accessing data** from **YAML files**.\nIt uses the following **libraries**: \n- [SnakeYAML](https://bitbucket.org/snakeyaml/snakeyaml/src/master/)\n- [FulmiCollection](https://github.com/fulminazzo/FulmiCollection)\n\nTo start using the project, import it with Maven or Gradle:\n- **Maven**:\n```xml\n\u003crepository\u003e\n    \u003cid\u003efulminazzo-repo\u003c/id\u003e\n    \u003curl\u003ehttps://repo.fulminazzo.it/releases\u003c/url\u003e\n\u003c/repository\u003e\n```\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eit.fulminazzo\u003c/groupId\u003e\n    \u003cartifactId\u003eYAMLParser\u003c/artifactId\u003e\n    \u003cversion\u003eLATEST\u003c/version\u003e\n\u003c/dependency\u003e\n```\n- **Gradle**:\n```groovy\nrepositories {\n    maven { url = \"https://repo.fulminazzo.it/releases\" }\n}\n\ndependencies {\n  implementation 'it.fulminazzo:YAMLParser:latest.release'\n}\n```\n\n| **Table of Contents**                                         |\n|---------------------------------------------------------------|\n| [How does it work](#how-does-it-work)                         |\n| [IConfiguration](#iconfiguration)                             |\n| [FileConfiguration](#fileconfiguration)                       |\n| [ConfigurationSection](#configurationsection)                 |\n| [YAMLParser](#yamlparser)                                     |\n| [Creating your own YAMLParser](#creating-your-own-yamlparser) |\n\n## How does it work\nThe main idea of this project comes from [Minecraft Bukkit FileConfiguration system](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/configuration/file/FileConfiguration.html),\na way of interfacing with YAML files and retrieving **non-primitive data objects**.\n\nYAMLParser mimics it by providing its own implementation (therefore becoming **independent** of the Bukkit library), while also giving a way to access [user defined objects](#yamlparser).\n\n## IConfiguration\nThe base of **YAMLParser** is [IConfiguration](https://github.com/fulminazzo/YAMLParser/blob/master/src/main/java/it/fulminazzo/yamlparser/interfaces/IConfiguration.java).\nThis interface presents a variety of **methods** and **functions** to work with data. Here are some of the most important ones:\n- ```getKeys(boolean deep)```: returns a **Set** containing every **key** in the YAML file. If ```deep``` is set to ```true```, it returns also the **keys** from every **subsection**;\n- ```getValues(boolean deep)```: returns a **Map** containing every **key-value** pair in the YAML file. If ```deep``` is set to ```true```, it returns also the **pairs** from every **subsection**;\n- ```contains(String path)```: returns **true** if the specified path **exists**;\n- ```createSection(String path, Map\u003c?, ?\u003e map)```: **creates** a **section** at the specified path and **fills** it with the given **map**;\n- ```set(String path, O o)```: **sets** the object **O** to the given **path**. If the path contains \".\", it **creates sections** accordingly. Uses [YAMLParsers](#yamlparser) for saving objects; \n- ```getConfigurationSection(String path)```: returns the **configuration section** at the given path;\n- ```isConfigurationSection(String path)```: **checks** if the object at the given path is a **configuration section**;\n- ```getEnum(String path, E def, Class\u003cE\u003e eClass)```: returns the **enum of class eClass** at the given path. If not found, return **def**;\n- ```isEnum(String path, Class\u003cE\u003e eClass)```: **checks** if the object** at the given path is an enum of class eClass;\n- ```getUUID(String path, UUID def)```: returns the **UUID** at the given path. If not found, return **def**;\n- ```isUUID(String path)```: **checks** if the object at the given path is a **UUID**;\n- ```getDate(String path, Date def)```: returns the **Date** at the given path. If not found, return **def**;\n- ```isDate(String path)```: **checks** if the object at the given path is a **Date**;\n- ```getString(String path, String def)```: returns the **String** at the given path. If not found, return **def**;\n- ```isString(String path)```: **checks** if the object at the given path is a **String**;\n- ```getInteger(String path, Integer def)```: returns the **Integer** at the given path. If not found, return **def**;\n- ```isInteger(String path)```: **checks** if the object at the given path is an **Integer**;\n- ```getDouble(String path, Double def)```: returns the **Double** at the given path. If not found, return **def**;\n- ```isDouble(String path)```: **checks** if the object at the given path is a **Double**;\n- ```getFloat(String path, Float def)```: returns the **Float** at the given path. If not found, return **def**;\n- ```isFloat(String path)```: **checks** if the object at the given path is a **Float**;\n- ```getLong(String path, Long def)```: returns the **Long** at the given path. If not found, return **def**;\n- ```isLong(String path)```: **checks** if the object at the given path is a **Long**;\n- ```getShort(String path, Short def)```: returns the **Short** at the given path. If not found, return **def**;\n- ```isShort(String path)```: **checks** if the object at the given path is a **Short**;\n- ```getBoolean(String path, Boolean def)```: returns the **Boolean** at the given path. If not found, return **def**;\n- ```isBoolean(String path)```: **checks** if the object at the given path is a **Boolean**;\n- ```getCharacter(String path, Character def)```: returns the **Character** at the given path. If not found, return **def**;\n- ```isCharacter(String path)```: **checks** if the object at the given path is a **Character**;\n- ```getByte(String path, Byte def)```: returns the **Byte** at the given path. If not found, return **def**;\n- ```isByte(String path)```: **checks** if the object at the given path is a **Byte**;\n- ```getObject(String path, Object def)```: returns the **Object** at the given path. If not found, return **def**;\n- ```isObject(String path)```: **checks** if the object at the given path is an **Object**;\n- ```getEnumList(String path, Class\u003c? extends E\u003e eClass)```: returns the **enum list of type eClass** at the given path; \n- ```getUUIDList(String path)```: returns the **UUID list** at the given path;\n- ```getDateList(String path)```: returns the **Date list** at the given path;\n- ```getStringList(String path)```: returns the **String list** at the given path;\n- ```getIntegerList(String path)```: returns the **Integer list** at the given path;\n- ```getDoubleList(String path)```: returns the **Double list** at the given path;\n- ```getFloatList(String path)```: returns the **Float list** at the given path;\n- ```getLongList(String path)```: returns the **Long list** at the given path;\n- ```getShortList(String path)```: returns the **Short list** at the given path;\n- ```getBooleanList(String path)```: returns the **Boolean list** at the given path;\n- ```getCharacterList(String path)```: returns the **Character list** at the given path;\n- ```getByteList(String path)```: returns the **Byte list** at the given path;\n- ```getObjectList(String path)```: returns the **Object list** at the given path;\n- ```getObjectList(String path, List\u003c?\u003e def)```: returns the **Object list** at the given path. If not found, return **def**;\n- ```isList(String path)```: **checks** if the object at the given path is a **List**;\n- ```getList(String path, Class\u003cT\u003e clazz)```: returns the **object of type clazz list** at the given path;\n- ```get(String path, T def, Class\u003cT\u003e clazz)```: returns the **object of type clazz** at the given path. If not found, return **def**;\n- ```print()```: **prints** the **contents** of the configuration.\n\nWhen invoking a method of type ```get```, the library will also check:\n- if the **object** is **found**, but is of **different type** from expected. This will throw an [UnexpectedClassException](https://github.com/fulminazzo/YAMLParser/blob/master/src/main/java/it/fulminazzo/yamlparser/exceptions/yamlexceptions/UnexpectedClassException.java);\n- by default, it will **ignore null objects**. However, if you use ```setNonNull(true)```, every null object will throw a [CannotBeNullException](https://github.com/fulminazzo/YAMLParser/blob/master/src/main/java/it/fulminazzo/yamlparser/exceptions/yamlexceptions/CannotBeNullException.java);.\n\nNow that we have covered the basics, we can look into some implementations of the **IConfiguration** interface.\n\n### FileConfiguration\nThis class **links** the **in memory configuration** map and the **corresponding file**.\nIt allows loading configurations from **File** or **InputStreams** and allows saving them with the ```save()``` method.\nWhen invoking the ```getRoot()``` method on a proper **IConfiguration** object, a **FileConfiguration** is always returned.\n\n### ConfigurationSection\nThis class represents any **YAML section**. Essentially:\n```yaml\nexample-section:\n  obj1: 1\n  obj2: \"String\"\n```\nwill be loaded in a **ConfigurationSection** named ```example-section``` that contains the **key-value pairs** ```obj1, 1``` and ```obj2, \"String\"```.\n\n## YAMLParser\nThe real power of this project comes from **YAMLParsers**.\nA **YAMLParser** is a class that allows **conversion** of an **object** to its **YAML form** and vice versa.\nFor example, every **primitive type** (or **String**) conversion is just the **object itself**, since YAML supports these types.\nHowever, for more **complex objects**, like UUIDs and Dates, **additional code is required**. \nThanks to **YAMLParser**, you will not have to worry about it and **only focus** on **retrieving** the **object**.\n\nHere is a list with every **YAMLParser**, its target class and how it converts it:\n\n| **YAMLParsers**                                                      | **Class**                                                                                   |\n|----------------------------------------------------------------------|---------------------------------------------------------------------------------------------|\n| [ArrayYAMLParser](#arrayyamlparser-t)                                | \u0026#60;T\u0026#62;[]                                                                               |\n| [CollectionYAMLParser](#collectionyamlparser-javautilcollection)     | [java.util.Collection](https://docs.oracle.com/javase/8/docs/api/java/util/Collection.html) |\n| [DateYAMLParser](#dateyamlparser-javautildate)                       | [java.util.Date](https://docs.oracle.com/javase/8/docs/api/java/util/Date.html)             |\n| [ListYAMLParser](#listyamlparser-javautillist)                       | [java.util.List](https://docs.oracle.com/javase/8/docs/api/java/util/List.html)             |\n| [SetYAMLParser](#setyamlparser-javautilset)                          | [java.util.Set](https://docs.oracle.com/javase/8/docs/api/java/util/Set.html)               |\n| [UUIDYAMLParser](#uuidyamlparser-javautiluuid)                       | [java.util.UUID](https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html)             |\n| [SerializableYAMLParser](#serializableyamlparser-javaioserializable) | [java.io.Serializable](https://docs.oracle.com/javase/8/docs/api/java/io/Serializable.html) |\n| [CallableYAMLParser](#callableyamlparser-t)                          | \u0026#60;T\u0026#62;                                                                                 |\n\n### ArrayYAMLParser (\u0026#60;T\u0026#62;[])\nConvert an **array** of type **T**.\n\n**WARNING**: because of how Java works, it is **not** possible to load an **empty array**.\nTherefore, the use of arrays is **discouraged**.\n\n**Conversion:**\n```yaml\n# Primitive type or String\nsimple-array:\n- t1\n- t2\n- t3\n# Other types\ncomplex-array:\n'0': t1\n'1': t1\n'2': t1\nvalue-class: rO0ABXQADGEuamF2YS5jbGFzcw==\n```\n\n### CollectionYAMLParser ([java.util.Collection](https://docs.oracle.com/javase/8/docs/api/java/util/Collection.html))\nConvert a **collection** of **any type**.\n\n**Conversion:**\n```yaml\n# Primitive type or String\nsimple-collection:\n- t1\n- t2\n- t3\n# Other types\ncomplex-collection:\n'0': t1\n'1': t1\n'2': t1\nvalue-class: rO0ABXQADGEuamF2YS5jbGFzcw==\n```\n\n### DateYAMLParser ([java.util.Date](https://docs.oracle.com/javase/8/docs/api/java/util/Date.html))\nConvert a **Date** into a valid **long**.\n\n**Conversion:**\n```yaml\ndate: 1701960652515\n```\n\n### ListYAMLParser ([java.util.List](https://docs.oracle.com/javase/8/docs/api/java/util/List.html))\nConvert a **list** of **any type**.\n\n**Conversion:**\n```yaml\n# Primitive type or String\nsimple-list:\n- t1\n- t2\n- t3\n# Other types\ncomplex-list:\n'0': t1\n'1': t1\n'2': t1\nvalue-class: rO0ABXQADGEuamF2YS5jbGFzcw==\n```\n\n### SetYAMLParser ([java.util.Set](https://docs.oracle.com/javase/8/docs/api/java/util/Set.html))\nConvert a **set** of **any type**.\n\n**Conversion:**\n```yaml\n# Primitive type or String\nsimple-set:\n- t1\n- t2\n- t3\n# Other types\ncomplex-set:\n'0': t1\n'1': t1\n'2': t1\nvalue-class: rO0ABXQADGEuamF2YS5jbGFzcw==\n```\n\n### UUIDYAMLParser ([java.util.UUID](https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html))\nConvert a **UUID** into a valid **string**.\n\n**Conversion:**\n```yaml\nuuid: dd6398ec-8461-4b20-9fa7-3dbae60c01b6\n```\n\n### SerializableYAMLParser ([java.io.Serializable](https://docs.oracle.com/javase/8/docs/api/java/io/Serializable.html))\nConvert an object that **implements Serializable** into a **Base64 string**.\n\n**Conversion:**\n```yaml\nobject: rO0ABXQAGFlvdSBzaG91bGQgbm90IHNlZSB0aGlzIQ==\n```\n\n### CallableYAMLParser (\u0026#60;T\u0026#62;)\nThis parser allows defining **custom objects** to be **parsed**. Say you have a **Person** class:\n```java\nclass Person {\n    String name;\n    int age;\n}\n```\nAll you have to do is invoke the **CallableYAMLParser** constructor:\n```java\npublic CallableYAMLParser(Class\u003cT\u003e tClass, FunctionException\u003cConfigurationSection, T, Exception\u003e function);\n```\nand pass it the **target class** and a **function** that returns an **empty Person**.\nThe parser will automatically **save every field** and **load them** from file.\n\n**Conversion:**\n```yaml\n# Vary, in the previous example:\nperson:\n  name: Alexander\n  age: 10\n```\n\n### Creating your own YAMLParser\nWhile the [CallableYAMLParser](#callableyamlparser-t) is able to cover many cases, sometimes you may want more **control** for **saving** and **loading** custom objects.\nIn this section we will look into **creating** your own **YAMLParser** and loading it.\n\nLet's start from creating a class that we are interested in:\n```java\nclass Person {\n    private final String name;\n    private final int age;\n\n    public Person(String name, int age) {\n        this.name = name;\n        this.age = age;\n    }\n}\n```\nAs you can see, this example is different from the one in [CallableYAMLParser](#callableyamlparser-t) because we cannot create an empty **Person**, nor set its variables later (since they are declared as **final**).\n\nWe can solve this problem by defining a new **PersonYAMLParser** which **extends YAMLParser**:\n```java\nclass PersonYAMLParser extends YAMLParser\u003cPerson\u003e {\n    \n}\n```\nTo complete our parser, we need three ingredients:\n- a **constructor**, that simply invokes the ```super()``` method and passes it our **class of interest**:\n```java\n    public PersonYAMLParser() {\n        super(Person.class);\n    }\n```\n- a **dumper**, which is a **function** responsible for **saving** the object that accepts **three parameters**: the **previous configuration**, the **path** where to save the object and the **object** itself.\nIn this case, we remove the previous object and stop if the new one is null. \nOtherwise, we create the corresponding section and save the desired into it:\n```java\n    @Override\n    protected TriConsumer\u003cIConfiguration, String, Person\u003e getDumper() {\n        return (configuration, path, person) -\u003e {\n            if (configuration == null || path == null) return;\n            if (person == null) return;\n            ConfigurationSection personSection = configuration.createSection(path);\n            personSection.set(\"name\", person.getName());\n            personSection.set(\"age\", person.getAge());\n        };\n    }\n``` \n- a **loader**, a **function** responsible for **loading** the object that accepts **two parameters**: the **previous configuration** and the **path**.\nIn this case, we try to retrieve the person section. If none is found, return null.\nOtherwise, load the name and the age and create a new person with these values (since we are using a **BiFunctionException**, every **exception** will be thrown as a **RuntimeException**. \n**It is up to the user to handle any exception accordingly**, for example if age was null):\n```java\n    @Override\n    protected BiFunctionException\u003cIConfiguration, String, Person, Exception\u003e getLoader() {\n        return (configuration, path) -\u003e {\n            if (configuration == null || path == null) return null;\n            ConfigurationSection personSection = configuration.getConfigurationSection(path);\n            if (personSection == null) return null;\n            String name = personSection.getString(\"name\");\n            // You should always use wrapper types.\n            // In case the getInteger method returns null, using\n            // \"int\" as type will throw an error.\n            Integer age = personSection.getInteger(\"age\");\n            return new Person(name, age);\n        };\n    }\n```\n\nNow, all you have to do is simply **add** this bit of code in your **main class**, **before loading or saving any object**:\n```java\nFileConfiguration.addParsers(new PersonYAMLParser());\n```\nIf you have **more** than one parser, but they all share the **same package**, you can also use:\n```java\nFileConfiguration.addParsers(packageName);\n```\nThat's it! You successfully created your own YAML parser, and it is now ready to use. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffulminazzo%2Fyamlparser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffulminazzo%2Fyamlparser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffulminazzo%2Fyamlparser/lists"}