Add Yaml Source Editor Extension
What does this MR do and why?
This MR adds a Source Editor Extension that exposes interactive methods for YAML-Files. It leverages the yaml
package.
Methods exposed by the extension:
setDataModel(value)
This function can be passed any JS Variable. The Editor's value will be set to a YAML dump of that value.
If enableComments: true
was set in the extension's options
, this supports injecting comments following the comment pattern (see below).
highlight(path)
This function will add line highlighting to the lines identified by the path. The path is a string to any object property of value
as interpreted by Lodash's pick function, e.g. foo.bar[0]
.
getDoc()
This function returns a Document
, the YAML package's AST, effectively exposing all interactive functions in conjunction with setDoc()
setDoc(doc)
Accepts a Document
as its parameter. It will set the editor's value to a stringified version of the Doc.
locate(path)
Used by highlight(path)
this function will return the first and last line number of the element identified by path
Constructor options
option | type | description |
---|---|---|
model | any | The initial data model to be used by the editor. The editor's value will be set to the stringified version of this. Can be updated after setup using setDataModel()
|
highlightPath | string | equivalent to calling highlight(path) after setup. Will add line highlighting to the element identified by this property |
enableComments | boolean | Whether data values following the comment pattern below will be converted to comments. Defaults to false
|
Comment Pattern
If enableComments
is set to true
in the Extension's options, values passed to setDataModel()
that include properties/elements that follow the below pattern, will be interpreted as comments and injected to the YAML as such.
In Objects, a key of '#' will be converted to a comment at the top of a
property. Any key follwing the pattern #|<some other key>
will be placed
right before <some other key>
.
Example:
{
foo: 'bar',
'#|baz': 'I am a comment specific to the `baz` property',
baz: 'boo',
'#': 'I am a generic comment, I will be placed at the top'
}
will be converted to:
# I am a generic comment, I will be placed at the top
foo: bar
# I am a comment specific to the `baz` property
baz: boo
In Arrays, any string that starts with #
(including the space), will
be converted to a comment at the position it was in. Example:
['foo', 123, '# I am a comment for abc', abc]
Will be converted to:
- foo
- 123
# I am a comment for abc
- abc
To Do before Merge:
-
fix an issue with locate()
when locating array instances -
complete JSDoc -
update Tests for SourceEditorExtensionBase.highlightLines
Related Issues:
Describe in detail what your merge request does and why.
Screenshots or screen recordings
Usage example:
These are strongly recommended to assist reviewers and reduce the time to merge your change.
Usage Example
import SourceEditor from "~/editor/source_editor";
import { YamlEditorExtension } from "~/editor/extensions/source_editor_yaml_creator_ext";
import wildAnimals from "./wild-animals.json"
const editor = new SourceEditor().createInstance({});
editor.use(
new YamlEditorExtension({
instance: editor,
enableComments: true,
model: wildAnimals, // initial value will be the stringified version of this
highlightPath: 'foods.birds' // initial highlighting
})
);
// update functionally
editor.setDataModel(wildAnimals)
editor.highlight('predators[2]')
editor.locate(foods.birds) // [5, 7]
import { Document } from 'yaml';
editor.getDoc() // <Document>
editor.setDoc(new Document(wildAnimals)) // when not modifying `Document`, this is equivalent to editor.setDataModel
Numbered steps to set up and validate the change are strongly suggested.
MR acceptance checklist
This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.
-
I have evaluated the MR acceptance checklist for this MR.