PlainTextLego

Assemble plaintext files from modules (via comment lines)

This library is mainly used for the @gebruederheitz/htmodules utility to dynamically build modular .htaccess files.

Installation

npm i @gebruederheitz/plaintextlego

Usage

This library will parse a base file passed to the constructor and attempt to find "blocks" surrounded by # BEGIN ${blockName} and # END ${blockName} comments. These blocks can be replaced or appended via separate files.

Basic usage (replace source file)

Say you have the following files:

--some/path/file.txt--

Some generic content to kick us off

# BEGIN generic

some generic content that could be manipulated through a module
# it can contain comments
# it could even contain "closing tags" as long as they don't match the module
# name
# END different module

# END generic

# BEGIN module-one
I will be replaced by the content of the module file...
# END module-one

# This is another generic comment that serves only demonstration purposes.

--some/path/module-one.txt--
You have been replaced! h4xx0rZ!!

--some/etc/module-two--

# This module will be appended to the base file

#         _       _       _            _   _                  
#        | |     (_)     | |          | | | |                 
#   _ __ | | __ _ _ _ __ | |_ _____  _| |_| | ___  __ _  ___  
#  | '_ \| |/ _` | | '_ \| __/ _ \ \/ / __| |/ _ \/ _` |/ _ \ 
#  | |_) | | (_| | | | | | ||  __/>  <| |_| |  __/ (_| | (_) |
#  | .__/|_|\__,_|_|_| |_|\__\___/_/\_\\__|_|\___|\__, |\___/ 
#  | |                                             __/ |      
#  |_|                                            |___/       

You could then run the following:

import { PlainTextLego } from '@gebruederheitz/plaintextlego';

const ptl = new PlainTextLego('./file.txt');
ptl.run({
    'module-one': './module-one.txt',
    'module-two': '../etc/module-two',
});

Which would result in:

--some/path/file.txt--

Some generic content to kick us off

# BEGIN generic

some generic content that could be manipulated through a module
# it can contain comments
# it could even contain "closing tags" as long as they don't match the module
# name
# END different module

# END generic

# BEGIN module-one
You have been replaced! h4xx0rZ!!
# END module-one

# This is another generic comment that serves only demonstration purposes.

# BEGIN module-two

# This module will be appended to the base file

#         _       _       _            _   _                  
#        | |     (_)     | |          | | | |                 
#   _ __ | | __ _ _ _ __ | |_ _____  _| |_| | ___  __ _  ___  
#  | '_ \| |/ _` | | '_ \| __/ _ \ \/ / __| |/ _ \/ _` |/ _ \ 
#  | |_) | | (_| | | | | | ||  __/>  <| |_| |  __/ (_| | (_) |
#  | .__/|_|\__,_|_|_| |_|\__\___/_/\_\\__|_|\___|\__, |\___/ 
#  | |                                             __/ |      
#  |_|                                            |___/       

# END module-two

Advanced usage

In order to create a new file instead of manipulating the base file, you can pass a file path as a second parameter to the run method:

const modules = {
    mymodule: './myptlmodule.txt',
    anothermodule: '/some/path/to/another/module',
};

ptl.run(modules, './result.txt');

All of the above describes usage with ES modules. In many cases you might want to use the CommonJS builds (when building nodeJS libraries for instance):

const {PlainTextLego} = require('@gebruederheitz/plaintextlego');

Caveats

• Modules can currently not be removed. They can only be "emptied" by providing an empty module file.
• Custom ordering is currently not possible and can only be guaranteed if the module blocks exists in the base file. New blocks will always be appended to the end of the file.

Development

Please use the yarn package manager. Use eslint & prettier.

# Install dependencies implicitly...
$> yarn
# ...or explicitly
$> yarn install

# Watch sources
$> yarn watch
# or
$> make dev

# Create production builds
$> yarn build
# or
$> make build

# Run the demo: Apply example modules to example base file; print result
$> yarn run:demo

# Lint files and check if they match the code style using eslint & prettier
$> yarn lint

# Run the mocha test suite
$> yarn test

# Install dependencies, lint sources, run test suite:
$> make test