xpm

[![GitHub package.json version](https://img.shields.io/github/package-json/v/xpack/xpm-liquid-ts)](https://github.com/xpack/xpm-liquid-ts/blob/mater/package.json) [![license](https://img.shields.io/github/license/xpack/xpm-liquid-ts.svg)](https://github.com/xpack/xpm-liquid-ts/blob/xpack/LICENSE) [![npm (scoped)](https://img.shields.io/npm/v/@xpack/xpm-liquid.svg)](https://www.npmjs.com/package/@xpack/xpm-liquid/) # A Node.js CommonJS/ES6 module with the Liquid substitutions code used by xpm & relatives This project provides a **TypeScript** Node.js **CommonJS**/**ES6** module with the code used to perform the Liquid substitutions when parsing the xpm `package.json` file. Note: Compatibility with legacy CommonJS is required until VS Code extensions will be updated to import ES6 modules. The project is open-source and hosted on GitHub as [xpack/xpm-liquid-ts](https://github.com/xpack/xpm-liquid-ts.git). ## Maintainer & developer info This page documents how to use this module in an user application. For maintainer information, see the separate [README-MAINTAINER](https://github.com/xpack/xpm-liquid-ts/blob/master/README-MAINTAINER.md) page. ## Prerequisites A recent [Node.js](https://nodejs.org) (>=16.0.0), since the TypeScript code is compiled into ECMAScript 2020 code, and the tests use ES6 modules. ## Install The module is available as [`@xpack/xpm-liquid-ts`](https://www.npmjs.com/package/@xpack/xpm-liquid-ts) from the public [`npmjs`](https://www.npmjs.com) repository; it can be added as a dependency to any TypeScript or JavaScript project with `npm install`: ```console npm install --save @xpack/xpm-liquid-ts@latest ``` The module does not provide any executables, and generally there are no reasons to install it globally. ## User info This section is intended for those who want to use this module in their own projects. The `@xpack/xpm-liquid` module can be imported into both TypeScript and JavaScript Node.js code. In TypeScript and ECMAScript modules, use `import`: ```typescript import { XpmLiquid } from '@xpack/xpm-liquid' ``` In JavaScript with CommonJS, use `require()`: ```javascript const { XpmLiquid } = require('@xpack/xpm-liquid') ``` To use the `XpmLiquid` class, create an instance of the engine, provide the `package.json` object, possibly the name of the configuration, and call `performSubstitutions()`: ```js const xpmLiquid = new XpmLiquid(log) const xpmLiquidMap = xpmLiquid.prepareMap(packageJson, 'Debug') const str = await xpmLiquid.performSubstitutions( '{{ "build" | path_join: configuration.name | to_filename }}', xpmLiquidMap) ``` ### Available variables The entire project `package.json` is available as the `package` variable: - `package` All user defined properties (project and configuration) are grouped below the `properties` variable: - `properties` If the substitution refers to a certain build configuration, the configuration name and the entire configuration content are available separately below the `configuration` variable. Configuration properties are added to the `properties` variables, possibly overriding project properties. - `configuration.name` - `configuration.*` Variables based on the Node.js process [environment](https://nodejs.org/dist/latest-v18.x/docs/api/process.html#process_process_env): - `env` Variables based on the Node.js [os](https://nodejs.org/dist/latest-v16.x/docs/api/os.html) definitions: - `os.EOL` - `os.arch` (like 'arm', 'arm64', 'ia32', 'x64') - `os.constants` - `os.cpus` - `os.endianness` - `os.homedir` - `os.hostname` - `os.platform` (like 'darwin', 'linux', 'win32') - `os.release` - `os.tmpdir` - `os.type` - `os.version` (available since Node 12) Variables based on the Node.js [path](https://nodejs.org/dist/latest-v16.x/docs/api/path.html) definitions: - `path.delimiter` (`;` for Windows, `:` for POSIX) - `path.sep` (`\` on Windows, `/` on POSIX) - `path.win32.delimiter` (`;`) - `path.win32.sep` (`\`) - `path.posix.delimiter` (`:`) - `path.posix.sep` (`/`) Examples: - `"buildFolderRelativePath": "build{{ path.sep }}{{ configuration.name | to_filename }}"` ### Custom filters Filters based on Node.js [path](https://nodejs.org/dist/latest-v16.x/docs/api/path.html) functions: - `path_basename` - `path_dirname` - `path_normalize` - `path_join` - `path_relative` - `path_posix_basename` - `path_posix_dirname` - `path_posix_normalize` - `path_posix_join` - `path_posix_relative` - `path_win32_basename` - `path_win32_dirname` - `path_win32_normalize` - `path_win32_join` - `path_win32_relative` Filters based on Node.js [utils](https://nodejs.org/dist/latest-v16.x/docs/api/util.html) functions: - `util_format` Custom filter to convert generic names to names accepted as file names (letters, digits, dash): - `to_filename` - `to_posix_filename` - `to_win32_filename` Examples: - `"buildFolderRelativePath": "{{ "build" | path_join: configuration.name | to_filename | downcase }"` ### Lenient if's The undefined variables in tests do not trigger `undefined variable` messages and allow to use defaults, like: ``` {{ env.OPTIMIZATION | default: '-O2' }} ``` ### Reference For more details on the available class definitions, including all methods, accessors, properties, etc, please see the TypeDoc [reference pages](https://xpack.github.io/xpm-liquid-ts). ## Known problems - none ## Status The `@xpack/xpm-liquid-ts` module is fully functional and stable. The main clients for this module is the `xpm` CLI application and the [VS Code xPack C/C++ Managed Build](https://github.com/xpack/vscode-xpack-extension-ts/) extension. ## Tests The module is tested with 100% coverage and CI tested on every push via GitHub [Actions](https://github.com/xpack/xpm-liquid-ts/actions). ## Compatibility notices According to [semver](https://semver.org) rules: > Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. ### v2.0.0 The project was updated to dual ESM & CJS. ## License The original content is released under the [MIT License](https://opensource.org/license/mit/), with all rights reserved to [Liviu Ionescu](https://github.com/ilg-ul).