# Yamlex

The `yamlex` command-line tool is here to assist you in working with
an oversized `extension.yaml`, when developing a Dynatrace 2.0 Extension.

It can `split` your original `extension.yaml` into carefully structured 
parts, which are easier to work with. It can then `join` the individual
parts together, assembling the `extension.yaml` back from them.

The Extension Framework still only cares about the final assembled
`extension.yaml`. Any extension would be considered invalid without it.
However, it is recommended to still commit both the individual parts and
the assembled `extension.yaml` file into the code repository of your
extension, because individual parts are your "code" and the assembled 
file is your artifact. 

With `yamlex`, your development workflow changes in such a way that
you only modify the individual parts and never really touch the artificial 
`extension.yaml`. Before you build the extension, you run `yamlex join`
to assemble the parts into the main file.

## Installation

```shell
pip install yamlex
```

## Usage

### (optional) Enable YAML validation and auto-completion 

By invoking `yamlex map` you can map the extension JSON scema files to the future YAML parts of the split 
`extension.yaml`. This will ensure proper validation and auto-completion 
for each and every part and not just for the `extension.yaml`.

Before you execute the `map` command, make sure relevant JSON schema
files for extensions are downloaded and are placed in the right folder.
By default, `yamlex` expects the relevant schema folder to be placed in
the current directory under the `schema/` name.

```shell
yamlex map
```

If it's located somewhere else, you can point `yamlex` to it using the
`--json <path_to_schema>` option.

```shell
yamlex map --json <path_to_schema> 
```

### (optional) Split the `extension.yaml`

This command will split the `extension.yaml` into individual parts.
It is useful when you only just start using `yamlex` with an existing
extension.

```shell
yamlex split
```

When you first split the original file, make sure you create a base
file called `extension.base.yaml` in the extension directory, right
where the `extension.yaml` is supposed to be.

The `extension.base.yaml` must contain all the basic metadata for the extension. Example:

```yaml
name: custom:com.dynatrace.extension.postgres-data
version: 1.1.3
minDynatraceVersion: 1.279.0
author:
  name: Dynatrace
  
dashboards:
  - path: dashboards/overview_dashboard.json
```

### Assemble `extension.yaml` from parts

```shell
yamlex join
```

When assembling, the `join` command will avoid overwriting a manually
created `extension.yaml` file. The way it detects that the file is
manually created is by checking whether the file contains the following
comment: *generated by yamlex*.

In order to overwrite this safety check, you can launch the `join`
command with the `--force` flag.

If you want to assemble the file into the different path, you can
specify that using the `--output` option:

```shell
yamlex join --output <path_to_final_file>
```
