npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

caml

v0.10.0

Published

Cascading YAML configuration

Downloads

36

Readme

CAML

Build Status Dependency Status devDependency Status

CAML offers you a Cascading YAML config. It's a YAML preprocessor which converts YAML to Json. This output can be written into a file or just logged to the console, or you can use it in Node as an object.

You still write valid YAML, but the output is quite a bit different.

Install

CLI

npm i -g caml

After that, run caml to see the CLI options.

e.g. caml -f a b -y config.yml will cascade a.yml and b.yml into config.yml

Omit config.yml from the command to just log to the console.

Node usage

npm i -D caml
const caml = require('caml');

# Returns a literal object constructed from the given input (see below for example configs).
caml.camlize({
    files: ['a', 'b']           # Required, will expect a.yml and b.yml as input files. Relative paths are possible.
    dir: "config/yaml"          # Optional, Caml will look into this directory for the .yml files
    overrides: ["c.d: false"]   # Optional, Will override the parameters on the given path. More info below.
});

Why cascading?

Multiple files

CAML is built out of the need for YAML to handle multiple files, with anchors and aliases defined in separate files.

So if root.yml defines the anchor &from_root, it can be used in files added after root.

The cascading concept is taken from CSS, so the last defined property wins, this means the order of the files added to CAML matters, a lot.

Besides the cascading of the files in cli, you can also do this in src, e.g.:

#@include partials/include.yml

someProperty: true

The content of partials/include.yml will be inserted 1:1 on the line of the inclusion, after that it will be parsed as usual.

Deep merge

By default, YAML only supports hash merging. There are some variations out there which support deep merging, but none in JavaScript.

This behaviour is not optional (at least not yet), meaning the output of CAML will be highly different than the default spec.

Full path declarations to a property

In CAML, it's possible to define properties with full paths like `a.b.c: 1'. These will all be merged into a single Object literal. If you need variable names with dots in them, surround them by "" or '', e.g.

a:
  b:
    d: 'indented'
a.b.d: "path to a.b.d"
a."b.d": "path to a['b.d']"

Result:

{
  "a": {
    "b": {
      "d": "path to a.b.d"
    },
    "b.d": {
      "path to a['b.d']"
    }
  }
}

Gotcha: CAML substitutes dots in variable names by _DOT_, so this cannot be used anywhere (not in keys or values).

Array handling

Arrays can be concatenated by using the following syntax:

arr: &arr
  - "one"
  - "two"
  
yarr:
  <<: *arr
  - "three"

yarr will be [ "one", "two", "three" ]

If you do not use this pattern, arrays will be handled just like simple values. The last one will overwrite all previous arrays.

Merging array elements

Array elements will be merged too. It is possible to extend array elements, but keep in mind same values will be overwritten:

it.is.an.array:
  - name: "sheep" 
    voice: "meeh"
  - name: "cat"
    voice: "miaw"

it.is.an.array[0]:
  size: "large"

it.is.an.array[1]:
  size: "small"

Which results in the following array elements:

{ name: 'sheep', voice: 'meeh', size: 'large' }
{ name: 'cat', voice: 'miaw', size: 'small' }

Variable substitution

CAML can substitute variables inline. Variables used in the CAML configuration need to be in the following form:

a:
  b: "I am a ${var.i.able}"

This will be replaced by the value of this path, e.g the following

var:
  i:
    able: 'very able one'

Will result in the following:

a:
  b: "I am a very able one"
var:
  i:
    able: 'very able one'

This means overrides will also work, so --overrides "var.i.able: very able one" will have the same effect as described above.

This can go further, for instance, running the following:

--overrides "ip: `ipconfig getifaddr en0`"`

Will allow you to use this dynamically in config:

server:
  ip: ${ip}

Usage

The following will cascade a.yml, b.yml and c.yml from the directory test/fixtures.

var caml = require('caml');

var options = {
    dir: 'test/fixtures', 
    files: ['a', 'b', 'c']
}

var result = caml.camlize(options);

Result will be the composed Object literal.

The following parameters can be set:

  • options.dir: the directory where CAML will look for files, default is the current working dir.
  • options.files: the files to merge, order matters. Properties declared in c.yml will overrule those from b.yml and a.yml
  • options.variables: variables to be replaced by their replacements.

Examples

The entire flow of CAML can be found in /examples/GENERAL.md.

CLI

There's a CLI, but it's mainly there for running a quick test. Run caml -h to check the usage.

Testing CAML

npm i
npm test

Node version compatibility

Check .travis.yml for the node versions CAML is tested against

Changelog

  • v0.9.13

    • Added node 8 to travis config
    • Removed node 0.12 from travis config
    • Updated dependencies
  • v0.9.12

    • Prevent values containing # from being stripped
    • Added yarn.lock
    • Loosened up npm dependency versions
    • Added node 7 to travis config
  • v0.9.11

    • Added --yaml and --json flags for different forms of output.
  • v0.9.4

    • Remove blank lines properly
  • v0.9.3

    • Updated npm packages
    • Handle multiple substitutions in a single line
    • Simplified .travis.yml
  • v0.9.0

    • Removed a lot of unnecessary splitting and joining to improve performance drastically (sliced parsing times in half).
    • Updated the readme
    • Improved cross platform newline splitting by using /\r?\n/ instead of "\n"

NOTICE

CAML is string / regex based. While this is not rock solid, it serves the purposes I need it for. I tried to use a proper parser but the documentation on it is very sparse, blocking this for now.