Info

YAML is a human-friendly data serialization standard for all programming languages including ctr. The data structure of ctr is a composition of Objects, Strings, Numbers, and Arrays which makes it a match made in heaven for YAML. Long story made short, if you are unfamiliar with YAML it is similar to JSON just with syntaxical freedom plus comments; alternatively, it can be formatted just like JSON.

Syntax

Description: The ctr parsing process of YAML is dead simple. A YAML file is a composition of Objects and ctr phrases each Object as a separate ctr style instance in which the Object key represents the root CSS selector, and the Object value represents the CSS style properties.

<#selector>:
<prop>: <value>
<#selector> {
<prop>: <value>;
}
<#selectorOne>:
<prop>: <value>
<#selectorTwo>:
<prop>: <value>
<#selectorOne> {
<prop>: <value>;
}
<#selectorTwo> {
<prop>: <value>;
}
//The JS equivalent to the above YAML
ctr.create({
'<#selectorOne>': {
'<prop>': '<value>'
},
'<#selectorTwo>': {
'<prop>': '<value>'
}
});
<#selectorOne> {
<prop>: <value>;
}
<#selectorTwo> {
<prop>: <value>;
}

Notes:

Data Structure

Description: The difference between data structures in Stylus compared to YAML is minuscule. There are three big tickets, comments, curly brackets, and Arrays.

Comments: A # in YAML denotes a comment compared to Stylus which uses //.

ctr('<#selector>', {
// My Comment
width: 200px
color: #eee
})
<#selector>:
# My Comment
width: 200px
# Gotcha, need to wrap hex values in a string
color: '#eee'

Notes

Curly Brackets Omit: Brackets can be omitted.

ctr('<#selector>', {
width: 200px
font-size: 12px
hover: {
on: {
height: 400px
}
}
})
<#selector>:
width: 200px
font-size: 12px
hover:
on:
height: 400px

Curly Brackets Keep: The conversion from Stylus is not one to one, and the typical Javascript Object syntax conventions must be followed in YAML.

ctr('<#selector>', {
width: 200px
font-size: 12px
hover: {
on: {
height: 400px
}
non: {
height: 200px
}
}
})
<#selector>: {
width: 200px,
font-size: 12px,
hover: {
on: {
height: 400px
},
non: {
height: 200px
}
}
}

Notes

Arrays: In Stylus Arrays are called Lists which allows for the omission of square brackets. However, this is not the case in YAML and to define an Array square brackets must be used.

ctr('<#selector>', {
width: 200px
hover: {
option: {
shorthand: {
//stylus automatically does this for you
height: 10s ease-in 4s
}
}
on: {
height: 400px
}
non: {
height: 200px
}
}
})
<#selector>:
width: 200px
hover:
on:
height: 400px
non:
height: 200px
option:
shorthand:
# Needs to use [ & ] to signify its an array
height: [10s, ease-in, 4s]

File Variables

Description: Currently, js-yaml does not support node anchors aka variables. Nevertheless, a variable Object can be defined through an Object with the key of $$. The variables defined in this Object are similar to variables set through the setVariable method. However, unlike global variables, the set YAML variables are only available to the YAML styles defined in the file. Also, global YAML variables can work hand-in-hand with local variables in each YAML style.

# variable Object
$$:
<propOne>: <valueOne>
<objectKey>:
<propTwo>: <valueTwo>
.test:
width: $<propOne>$
font-size: $<objectKey>.<propTwo>$
.test {
width: <valueOne>;
font-size: <valueTwo>;
}

Notes

Key Modifier

Description: There are instances in CSS when it makes sense to have key duplication although this is problematic since key duplication in an Object is not possible. To solve this issue an Object key modifier can be used in the following fashion <selector>:::<modifier> and ctr will remove the modifier upon processing the style.

.test:::one:
width: 200px
.test:::two:
height: 400px
.test {
width: 200px;
}
.test {
height: 400px;
}

Notes

yaml

Description: The yaml method alivates many of the pain points involved with having to require a YAML file which cannot be done nativley. Essentially the method is a wrapper around fs and the YAML parser js-YAML to read and convert YAML files into Javascript Objects.

Parameters

Arguments

Example

const ctr = new CTR();
// Absolute or relative file path
ctr.yaml('./<filePath>.yml');
const ctrResult = ctr.getResult();
const ctr = new CTR();
// All other ctr methods work with yaml
// Set's all hover states to have duration of 2s
ctr.setOption({
hover: {
duration: '2s'
}
});
// Any hover states will have a duration of 2s
ctr.yaml('./<filePath>.yml');
const ctrResult = ctr.getResult();

Notes

setYamlTransform

Description: The setYamlTransform method creates and sets a hook to transform the raw Object results of the parsed YAML before the data is rendered.

Parameters

Arguments

Example

//set transform
ctr.setYamlTransform(function (yamlObj) {
// uppercase selector key
return Object.keys(yamlObj).reduce(function (prv, key) {
prv[key.toUpperCase()] = yamlObj[key];
return prv;
}, {});
});
//process yaml file
ctr.yaml('./test-data.yml');
const ctrResult = ctr.getResult();
// .TEST-DATA {
// color: #f00;
// width: 200px;
// }
# The YAML style data
# filePath: ./test-data.yml
.test-data:
color: red
width: 200px

Notes