balanced-pairs

Balanced-Pairs

🏄 get block contents between balanced pairs, eg: {} <a></a> or code fences

Support the development of Balanced-Pairs.

Install

# NPM npm install --save balanced-pairs # Yarn yarn add balanced-pairs

Uneven Pairs

An "Uneven Pair" is a pair of varying block delimiters. For example: HTML tags.

• Uneven pairs can be nested.
• Uneven pairs return:
  • A nested tree of blocks.
  • A linear array of blocks in the order they were closed.
  • A object containing blocks mapped to their depth.
• An inside(charPos) function that returns all the nested blocks that the character is within.
• Each block contains an updateBody() function that sets the .newBody property on each block
• Result has a .flatten() method, to turn the block tree back into a string, replacing the old content with the updated content

const balance = require('balanced-pairs') const content = 'Foo <div>bar <div>baz</div></div> qux.' const result = balance(content, { open: '<div>', close: '</div>' }) console.log(result.blocks)

Result:

{ blocks: [{ start: 0, end: 37, depth: 0, body: 'Foo <div>bar <div>baz</div></div> qux.', root: true, children: [{ start: 9, end: 26, depth: 1, pre: 'Foo <div>', body: 'bar <div>baz</div>', post: '</div> qux.', root: false, delimiter: { start: 4, end: 32, pre: 'Foo ', body: '<div>bar <div>baz</div></div>', post: ' qux.' }, children: [{ start: 18, end: 20, depth: 2, pre: 'Foo <div>bar <div>', body: 'baz', post: '</div></div> qux.', root: false, delimiter: { start: 13, end: 26, pre: 'Foo <div>bar ', body: '<div>baz</div>', post: '</div> qux.' }, children: [] }] }] }], polygon: [], mode: 'odd', inside: [Function: inside], levels: { '1': [{ start: 9, end: 26, depth: 1, pre: 'Foo <div>', body: 'bar <div>baz</div>', post: '</div> qux.', root: false, delimiter: { start: 4, end: 32, pre: 'Foo ', body: '<div>bar <div>baz</div></div>', post: ' qux.' }, children: [{ start: 18, end: 20, depth: 2, pre: 'Foo <div>bar <div>', body: 'baz', post: '</div></div> qux.', root: false, delimiter: { start: 13, end: 26, pre: 'Foo <div>bar ', body: '<div>baz</div>', post: '</div> qux.' }, children: [] }] }], '2': [{ start: 18, end: 20, depth: 2, pre: 'Foo <div>bar <div>', body: 'baz', post: '</div></div> qux.', root: false, delimiter: { start: 13, end: 26, pre: 'Foo <div>bar ', body: '<div>baz</div>', post: '</div> qux.' }, children: [] }] }, list: [{ start: 18, end: 20, depth: 2, pre: 'Foo <div>bar <div>', body: 'baz', post: '</div></div> qux.', root: false, delimiter: { start: 13, end: 26, pre: 'Foo <div>bar ', body: '<div>baz</div>', post: '</div> qux.' }, children: [] }, { start: 9, end: 26, depth: 1, pre: 'Foo <div>', body: 'bar <div>baz</div>', post: '</div> qux.', root: false, delimiter: { start: 4, end: 32, pre: 'Foo ', body: '<div>bar <div>baz</div></div>', post: ' qux.' }, children: [{ start: 18, end: 20, depth: 2, pre: 'Foo <div>bar <div>', body: 'baz', post: '</div></div> qux.', root: false, delimiter: { start: 13, end: 26, pre: 'Foo <div>bar ', body: '<div>baz</div>', post: '</div> qux.' }, children: [] }] }] }

Flatten

Each block contains an updateBody() function that sets the .newBody property on each block.

Result has a .flatten() method, to turn the block tree back into a string, replacing the old content with the updated content

Note: flattening a block will remove it's delimiters within the parent.

const source = '0{1}{2}3' const result = balance(source, { open: '{', close: '}' }) result.blocks[0].children[0].updateBody('x') result.blocks[0].children[1].updateBody('y') const flattened = result.flatten() console.log(flattened) // '0xy3'

You can also flatten nested content:

const source = '0{1{2{3{4}}}}' const result = balance(source, { open: '{', close: '}' }) // result.blocks[0] = the root block const block4 = result.blocks[0] .children[0] .children[0] .children[0] .children[0] block4.updateBody('[BEEP!]') const flattened = result.flatten() console.log(flattened) // 0{1{2{3[BEEP!]}}}

Even Pairs

An "Even Pair" is a pair of identical block delimiters. For example: a markdown code-fence.

• Even pairs do not nest.
• Even pairs return a linear array of blocks.
• Even pairs return a polygon that can be used to determine whether any character position is inside or outside of a block.
• An inside(charPos) function to check whether any character is within a block.

Example:

const balance = require('balanced-pairs') const content = 'FOO ```BAR``` BAZ ```QUX```' const result = balance(content, { open: '```', close: '```' }) console.log(result.blocks)

Result:

[ { start: 7, end: 9, pre: 'FOO ```', body: 'BAR', post: '``` BAZ ```QUX```', polygon: [ [ 7, -1 ], [ 10, -1 ], [ 10, 1 ], [ 7, 1 ], [ 7, -1 ] ], delimiter: { start: 4, end: 12, pre: 'FOO ', body: '```BAR```', post: '``` BAZ ```QUX```' } }, { start: 21, end: 23, pre: 'FOO ```BAR``` BAZ ```', body: 'QUX', post: '```', polygon: [ [ 21, -1 ], [ 24, -1 ], [ 24, 1 ], [ 21, 1 ], [ 21, -1 ] ], delimiter: { start: 18, end: 26, pre: 'FOO ```BAR``` BAZ ', body: '```QUX```', post: '```' } } ], polygon: [ [ 7, -1 ], [ 10, -1 ], [ 10, 1 ], [ 7, 1 ], [ 7, -1 ], [ 21, -1 ], [ 24, -1 ], [ 24, 1 ], [ 21, 1 ], [ 21, -1 ] ], mode: 'even', inside: [Function: inside] }