decorators-parser-js v0.0.8
Decorators Parser
License
© 2023 Smartschool Inc. All rights reserved.
Installation guide
- Install NodeJS 18 or newer from https://nodejs.org/en/download
- Add NodeJS to PATH - example guide
- Run
npm install "decorators-parser-js"
in your command line
API
parse
function parse(file, data)
Parses given string or file and returns a list of dictionaries. If both file
and data
are provided, data
will be ignored.
constructor
function constructor(constraints={}, ignored=[])
Creates a new Parser object. constraints
is a dictionary of constraints for decorators. ignored
is a list of decorators to ignore.
Decorators format
Decorator name can be any string that does not contain '@' character. If decorator
does not satisfy this requirement InvalidDecoratorException
will be thrown.
Example:
@decorator(some nice value)
Standard decorators
Decorators can be used in one of three ways:
@decorator(value)
or
@decorator()
Some very long and complicated value that would be hard to read if it were in parenthesis like the value above.
or
@decorator
Some very long and complicated value that would be hard to read if it were in parenthesis like the value above.
All of these create Javascript dictionary like this:
{
'decorator': 'value'
}
@new decorator
Using @new decorator starts a new dictionary and adds it to the current list of dictionaries. In a single piece of text between two @new decorators (which correspond to a single JavaScript dictionary) there can not be two decorators with the same name. Using a same name without an appropriate @new decorator will result in DuplicateDecoratorException
being thrown.
Example:
task.txt:
@question()
Who is Lincoln?
@new
@question()
What is the purpose of the Bill of Rights?
run.js:
import { Parser } from "decorators-parser-js"
let task_parser = new Parser()
console.log(task_parser.parse('task.txt'))
result:
[
{
'question': 'Who is Lincoln?'
},
{
'question': 'What is the purpose of the Bill of Rights?'
}
]
Global decorators
In addition to standard decorators, decorators which name starts with global-
are added to each dictionary while parsing a file. Dictionary key is the decorator's suffix after global-
Example:
task.txt:
@global-topic(History)
@question()
Who is Lincoln?
@new
@question()
What is the purpose of the Bill of Rights?
run.js:
import { Parser } from "decorators-parser-js"
let task_parser = new Parser()
console.log(task_parser.parse('task.txt'))
result:
[
{
'topic': 'History',
'question': 'Who is Lincoln?'
},
{
'topic': 'History',
'question': 'What is the purpose of the Bill of Rights?'
}
]
Constraints
Decorators can use constraints on their values. If a decorator has value that does not match regular expression
provided, Parser will throw InvalidValueException
. Parser class takes optional constraints
argument in its constructor which
is a JavaScript dictionary in a format shown below (if format of the given dictionary is invalid, InvalidConstraintException
will be thrown):
let example = {
'question':
{
'regex': '^([^@]+)$',
'description': 'any non-empty string without @'
},
'correct':
{
'regex': '^([1-4])$',
'description': 'any number from 1 to 4'
}
}
Example 1
task.txt:
@correct(11)
run.js:
import { Parser } from "decorators-parser-js"
let task_parser = new Parser(example)
console.log(task_parser.parse('task.txt'))
Will result in the following output:
InvalidValueException [Error]: 'correct' should be any number from 1 to 4 but is 11
Example 2
If we take Example 1 but change task.txt file to:
correct(1)
The output will be:
[
{
'correct': '1'
}
]
Ignored decorators
If you need to use @ symbol for something else than decorator, you can specify names to exclude from the search
Example:
task.txt:
@question
Some long question with @ref in it
run.js:
import { Parser } from "decorators-parser-js"
let task_parser = new Parser({}, ["ref"])
console.log(task_parser.parse('task.txt'))
Will result in the following output:
[
{
'question': 'Some long question with @ref in it'
}
]