tablab
v1.0.0
Published
A javascript library to write tablatures
Downloads
242
Maintainers
Readme
Tablab
Tablab is a javascript library to write tablatures. It provides two different ways for writing them:
- Step by step: With this strategy, you must create a tablature instance and specify each operation to write the desired tablature;
- From a text input of instructions: In this case, you must create a parser instance to read these instructions. Once read, the resulting parsed instructions can be used with an instruction writer factory to determine and perform the corresponding writing operations to a tablature instance.
Table of Content
Install
With node installed, run
npm install tablab
Usage
Writing a tablature step by step
The Tab
class provides the functionalities to write a tablature step by step. With it, you can write notes, header messages, footer messages, change its spacing and add new blocks to your tablature. Once done writing your tablature, you can format it as intended.
Check out the Tab
class usage documentation for more information about:
- The available options to customize your tablature;
- The available methods to perform the writing operations.
Below, an example of how the Tab
class can be used to write a tablature:
const { Tab, Note } = require('tablab');
const cMajorChord = [
new Note(1, '0'),
new Note(2, '1'),
new Note(3, '0'),
new Note(4, '2'),
new Note(5, '3'),
];
const eMajorChord = [
new Note(1, '0'),
new Note(2, '0'),
new Note(3, '1'),
new Note(4, '2'),
new Note(5, '2'),
new Note(6, '0'),
];
const tab = new Tab();
tab
.writeHeader('Simple Notes Example')
.writeNote(new Note(1, '0'))
.setSpacing(2)
.writeNote(new Note(2, '1'))
.writeNote(new Note(3, '2'))
.writeNote(new Note(4, '1/3'))
.writeNote(new Note(5, '3'))
.writeNote(new Note(6, '1'))
.writeNote(new Note(5, '2'))
.writeNote(new Note(4, '3'))
.writeNote(new Note(3, '1h3'))
.writeNote(new Note(2, '3p1'))
.writeNote(new Note(1, '2'))
.writeFooter('x2')
.addBlock()
.setSpacing(5)
.writeHeader('Chord Example (C Major)')
.writeParallelNotes(cMajorChord)
.writeParallelNotes(cMajorChord)
.addBlock()
.writeHeader('Chord Example (E Major)')
.writeParallelNotes(eMajorChord)
.writeParallelNotes(eMajorChord);
console.log(tab.format(50));
outputs
[
[
' | Simple Notes Example | ',
'---|---0-----------------------------------2--|---',
'---|------1---------------------------3p1-----|---',
'---|---------2-------------------1h3----------|---',
'---|------------1/3-----------3---------------|---',
'---|-----------------3-----2------------------|---',
'---|--------------------1---------------------|---',
' | x2 | '
],
[
' | Chord Example (C Major) ',
'-----|-----0-----0--------------------------------',
'-----|-----1-----1--------------------------------',
'-----|-----0-----0--------------------------------',
'-----|-----2-----2--------------------------------',
'-----|-----3-----3--------------------------------',
'-----|--------------------------------------------',
' | '
],
[
' | Chord Example (E Major) ',
'-----|-----0-----0--------------------------------',
'-----|-----0-----0--------------------------------',
'-----|-----1-----1--------------------------------',
'-----|-----2-----2--------------------------------',
'-----|-----2-----2--------------------------------',
'-----|-----0-----0--------------------------------',
' | '
]
]
Writing a tablature from a text input of instructions
As in the strategy step by step, the Tab
class is responsible for managing the tablature. The difference from this strategy is that instead of calling each method direct from a tablature instance, the writing operations will be determined from a text input of instructions.
Tablab
provides the Parser
class to read the given text input of instructions and determine the writing operation to be performed over the tablature for each parsed instruction.
Check out the Parser
class usage documentation for more information about:
- The accepted instructions;
- How to write a tablature with the parsed instructions;
- The available options to customize the parser;
- The available methods to parse instructions.
Below, an example of how the Parser
class can be used with the Tab
class to write a tablature:
const { Tab, Parser } = require('tablab');
const instructions =
'header(Simple Notes Example) 1-0 spacing(2) ' +
'2-1 3-2 4-1/3 5-3 6-1 5-2 4-3 3-1h3 2-3p1 1-2 footer(x2) break spacing(5) ' +
'header(Chord Example (C Major)) merge{ 1-0 2-1 3-0 4-2 5-3 } ' +
'merge{ 1-0 2-1 3-0 4-2 5-3 } break header(Chord Example (E Major)) ' +
'merge{ 1-0 2-0 3-1 4-2 5-2 6-0 } merge{ 1-0 2-0 3-1 4-2 5-2 6-0 }';
const tab = new Tab();
const parser = new Parser();
parser.parseAll(instructions).forEach((parsedInstruction) => {
const writeResult = parsedInstruction.writeOnTab(tab);
if (!writeResult.success) {
console.log(
`Failed to write instruction < ${parsedInstruction.value} > at position ` +
`${parsedInstruction.readFromIndex}. (${writeResult.failureReasonIdentifier}) ` +
`- ${writeResult.failureMessage} `
);
}
});
console.log(tab.format(50));
outputs
[
[
' | Simple Notes Example | ',
'---|---0-----------------------------------2--|---',
'---|------1---------------------------3p1-----|---',
'---|---------2-------------------1h3----------|---',
'---|------------1/3-----------3---------------|---',
'---|-----------------3-----2------------------|---',
'---|--------------------1---------------------|---',
' | x2 | '
],
[
' | Chord Example (C Major) ',
'-----|-----0-----0--------------------------------',
'-----|-----1-----1--------------------------------',
'-----|-----0-----0--------------------------------',
'-----|-----2-----2--------------------------------',
'-----|-----3-----3--------------------------------',
'-----|--------------------------------------------',
' | '
],
[
' | Chord Example (E Major) ',
'-----|-----0-----0--------------------------------',
'-----|-----0-----0--------------------------------',
'-----|-----1-----1--------------------------------',
'-----|-----2-----2--------------------------------',
'-----|-----2-----2--------------------------------',
'-----|-----0-----0--------------------------------',
' | '
]
]
Acknowledgments
The Tablab's parser was highly inspired by the Latex project, a text preparation system. It provides a creative solution that decouples the document operations of writing them and designing them. If you have already struggled with writing documents, and adjusting their layout, make sure to check it out.