pluie-yaml/README.md

165 lines
4.0 KiB
Markdown
Raw Normal View History

2018-08-01 13:10:12 +00:00
# pluie-yaml
2018-08-01 15:15:45 +00:00
**pluie-yaml** is a vala shared library managing yaml files (v 1.2) and yaml nodes in vala language.
As json is now a valid subset of yaml, you can use this lib to load json files too.
2018-08-01 13:10:12 +00:00
2018-08-01 15:15:45 +00:00
The purpose of this project is to make vala able to load and deal with yaml configuration files.
2018-08-02 21:44:36 +00:00
So, currently the lib deal only with one yaml document, but you can use a special `^imports` clause (nodemap)
to load a subset of yaml files in the main yaml document.
2018-08-01 15:49:01 +00:00
2018-08-02 21:44:36 +00:00
the lib does not manage yet tag directives and tag values.
2018-08-01 15:15:45 +00:00
**pluie-yaml** use the ![libyaml c library](https://github.com/yaml/libyaml) (License MIT, many thanks to Kirill Simonov) to parse and retriew related yaml events.
## License
GNU GPL v3
2018-08-01 13:10:12 +00:00
## Prerequisites
2018-08-01 15:15:45 +00:00
`valac meson ninja glib gee gobject pluie-echo`
2018-08-01 13:10:12 +00:00
## Install
2018-08-01 15:15:45 +00:00
git clone the project then cd to project directory and do :
2018-08-01 13:10:12 +00:00
```
meson --prefix=/usr ./ build
sudo ninja install -C build
```
## Compilation
```
valac --pkg gee-0.8 --pkg pluie-echo-0.2 --pkg pluie-yaml-0.3 main.vala
```
2018-08-01 15:15:45 +00:00
see https://git.pluie.org/pluie/libpluie-echo in order to install pluie-echo-0.2 pkg
you can use `./build.sh` to rebuild/install the **pluie-yaml** lib and compile samples files
2018-08-01 13:10:12 +00:00
## Api / Documentation
https://pluie.org/pluie-yaml-0.3/index.htm
(comming soon)
## Docker
2018-08-01 15:15:45 +00:00
a demo image will be available soon on docker hub. you will be able to run a container with :
2018-08-01 13:10:12 +00:00
```
docker run --rm -it pluie/libyaml
```
## Usage
2018-08-02 21:44:36 +00:00
-------------------
2018-08-01 15:49:01 +00:00
### config
2018-08-02 21:44:36 +00:00
```vala
2018-08-01 15:49:01 +00:00
var config = new Yaml.Config (path);
var node = config.get ("ship-to.address.city{0}");
if (node != null) {
of.echo (node.data)
}
```
2018-08-02 21:44:36 +00:00
-------------------
### config with ^imports clause
```yml
# | use special key word '^imports' to import other yaml config files in
# | current yaml document
# | '^imports' must be uniq and a direct child of root node
# | imported files are injected as mapping nodes at top document level
# | so you cannot use keys that already exists in the document
^imports :
# you can redefine default import path with the special key '^path'
# if you do not use it, the default path value will be the current directory
# redefined path values are relative to the current directory (if a relative path
# is provided)
^path : ./config
# you can also define any other var by prefixing key with ^
^dir : subdir
# and use it enclosed by ^
# here final test path will be "./config/subdir/test.yml"
test : ^dir^/test.yml
# here final db path will be "./config/db.yml"
db : db.yml
```
-------------------
2018-08-01 15:49:01 +00:00
2018-08-01 15:15:45 +00:00
### loader
2018-08-02 21:44:36 +00:00
load a single document.
`^imports` clause is out of effects here.
```vala
2018-08-01 15:15:45 +00:00
var path = "./config/main.yml";
// uncomment to enable debug
// Pluie.Yaml.Scanner.DEBUG = true;
var loader = new Yaml.Loader (path /* , displayFile, displayNode */);
2018-08-01 13:10:12 +00:00
if ((done = loader.done)) {
Yaml.NodeRoot root = loader.get_nodes ();
root.display_childs ();
}
```
2018-08-02 21:44:36 +00:00
-------------------
2018-08-01 13:10:12 +00:00
2018-08-01 15:15:45 +00:00
### finder
**lib-yaml** provide a `Yaml.Finder` to easily retriew a particular yaml node.
Search path definition has two mode.
2018-08-02 21:44:36 +00:00
The default mode is `Yaml.FIND_MODE.DOT`
2018-08-01 15:15:45 +00:00
- child mapping node are separated by dot
- sequence entry must be enclosed in curly brace
ex : `grandfather.father.son{2}.age`
2018-08-02 21:44:36 +00:00
The Other mode is Yaml.FIND_MODE.SQUARE_BRACKETS
- node's key name must be enclosed in square brackets
- sequence entry must be enclosed in curly brace
ex : `[grandfather][father][son]{2}[age]`
2018-08-01 15:15:45 +00:00
with singlepair node, you can retriew corresponding scalar node with {0}
2018-08-02 21:44:36 +00:00
ex yaml file :
```yml
2018-08-01 15:15:45 +00:00
product:
- sku : BL394D
quantity : 4
description : Basketball
2018-08-02 21:44:36 +00:00
```
vala code :
```vala
2018-08-01 15:15:45 +00:00
...
Yaml.NodeRoot root = loader.get_nodes ();
Yaml.Node? node = null;
2018-08-02 21:44:36 +00:00
if ((node = finder.find ("product{0}.description")) != null) {
var val = node.val ();
2018-08-01 15:15:45 +00:00
}
```
2018-08-02 21:44:36 +00:00
-------------------
2018-08-01 15:15:45 +00:00
2018-08-01 13:10:12 +00:00
### more samples
see samples files in ./samples directory
2018-08-01 15:15:45 +00:00
2018-08-02 21:44:36 +00:00
-------------------
2018-08-01 15:15:45 +00:00
### todo
2018-08-02 21:44:36 +00:00
* ~~imports clause~~
2018-08-01 15:15:45 +00:00
* fix nodes traversing
2018-08-01 15:49:01 +00:00
* dumper
2018-08-02 21:44:36 +00:00
* manage tag directives & tag
2018-08-01 15:49:01 +00:00