Skip to content

Latest commit

 

History

History
290 lines (237 loc) · 7.09 KB

README.md

File metadata and controls

290 lines (237 loc) · 7.09 KB

Kyaml

Kyaml is a simple, flexible, and forgiving YAML parser for Android.

Kotlin implementation YAML file 
Kyaml(
    activity = this,
    yamlResourceIdInRaw = R.raw.test,
    // Or if in assets: yamlFileNameInAssets = "test.yaml",
    onEachItem = { key, value ->
        when (key) {
            "foo" -> value // "Kyaml!"
            "bar" -> value // 123
            // ...
        }
    }
)
 
# /app/src/main/res/raw/test.yaml

foo: Kyaml!
bar: 123
baz: true

Pass a YAML file from /assets/ or /res/raw/ to return parsed key/values for each item. Each value returned will be casted as the type found.

  Examples of value types returned from Kyaml:

  • key1: test! = String
  • key2: 123 = Int
  • key3: 2147483648 = Long
  • key4: [ 1, 2, 3 ] = List of Integers

Check out the example app for Kyaml!


Table of Contents


Usage / Examples

Ex 1: YAML in raw directory gathering primative types and key nesting.

Kotlin implementation YAML file 
Kyaml(
    activity = this,
    yamlResourceIdInRaw = R.raw.ex1,
    onEachItem = { key, value ->
        when (key) {
            "isExample1" -> value // true
            "strings.name" -> value // "example1"
            "strings.location" -> value // "raw"
            "numbers.intNum" -> value // 123
            "numbers.floatNum" -> value // 987.65
        }
    }
)
 
# /app/src/main/res/raw/ex1.yaml

isExample1: true
strings:
  name: example1
  location: "raw"
numbers: { intNum: 123, floatNum: 987.65 }

Ex 2: YAML in assets directory gathering sequences.

Kotlin implementation YAML file 
Kyaml(
    activity = this,
    yamlFileNameInAssets = "ex2.yaml",
    onEachItem = { key, value ->
        when (key) {
            "tags" -> {
                (value as? List<*>)?.let {
                    value.forEach {
                        // it = "foo"
                        // it = "bar"
                        // it = "baz"
                    }
                }
            }
            "intervals" -> {
                (value as? List<*>)?.let {
                    value.forEach {
                        // it = 15
                        // it = 30
                        // it = 45
                    }
                }
            }
        }
    }
)
 
# /app/src/main/assets/ex2.yaml

tags:
  - foo
  - bar
  - baz
intervals: [ 15, 30, 45 ]

Ex 3: YAML file note found. Error cancels Kyaml.

Kotlin implementation YAML file 
Kyaml(
    activity = this,
    yamlFileNameInAssets = "not_found.yaml",
    onEachItem = { key, value ->
        // Error loading YAML file.
        // contents in onEachItem
        // will never be called.
    },
    onError = {
        when (it) {
            is IllegalArgumentException -> 
                // "Could not open not_found.yaml"
                it.message
            else -> it.message
        }
    }
)
 
"not_found.yaml" does not exist in the project.

Syntax

Usage is simply calling Kyaml() passing up to four arguments (3 required and 1 optional) into its constructor. There are 2 public constructors that vary only by 1 argument:

  • activity - Activity / Required
    • Active Activity.
  • yamlResourceIdInRaw or yamlFileNameInAssets - Only 1 Required

    • yamlResourceIdInRaw - Int (@RawRes) / Required

      • YAML file located in /res/raw/ to consume.

      OR

    • yamlFileNameInAssets - String / Required

      • YAML file name located in /assets/ to consume. Optionally the extension can be included with the file name.
  • onEachItem - (String, Any?) -> Unit / Required
    • Called on every item parsed from the YAML file. Included will be the key and value. The key is always of type String. The value will be of the detected type when parsed. This may include Int, Long, Float, Double, Boolean, String, or null. The value may also be a List of any of these types.
  • onError - (Exception) -> Unit / Optional
    • Any exception caught within Kyaml will stop the process and pass the exception here. An IllegalArgumentException will be thrown if yamlFileNameInAssets contains a file name that could not be found. It is not known if any other exception will be thrown when using Kyaml.

Installation

Install with JitPack

  1. Add JitPack to your project's root build.gradle at the end of repositories:
  • dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
        maven { url 'https://jitpack.io' }
  }
}
  1. In the build.gradle of the module(s) you wish to use Kyaml with, add the following to dependencies:
  • dependencies {
    // Required: Installs the .aar without any documentation.
    implementation 'com.github.digidemic:kyaml:1.1.0'
    
    // Optional: Displays documentation while writing coding. 
    implementation 'com.github.digidemic:kyaml:1.1.0:javadoc'

    // Optional: Displays documentation (more comprehensive than javadoc in some cases) and uncompiled code when stepping into library.
    implementation 'com.github.digidemic:kyaml:1.1.0:sources'
}
  1. Sync gradle successfully.
  2. Done! Your Android project is now ready to use Kyaml. Go to Examples or Syntax for Kyaml usage!

Versioning

  • SemVer is used for versioning.
  • Given a version number MAJOR . MINOR . PATCH
    1. MAJOR version - Incompatible API changes.
    2. MINOR version - Functionality added in a backwards-compatible manner.
    3. PATCH version - Backwards-compatible bug fixes.

License

Kyaml created by Adam Steinberg of DIGIDEMIC, LLC

Copyright 2024 DIGIDEMIC, LLC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.