This is a project to implement a parser that will support parsing most Magic
the Gathering card texts. The current goal is to parse 80% of cards
successfully. To use simply run npm i magic-card-parser
then you can include
it in your project with import { parseCard } from 'magic-card-parser'
.
parseCard
takes a single argument, card
, that must include the properties
name
and oracle_text
. It will automatically replace the cards name with ~
in the oracle text and convert to lowercase before parsing. The return value is
an object like the following:
{
"error": null,
"oracleText": "{t}: create a 1/1 white human creature token.\nfateful hour — as long as you have 5 or less life, other creatures you control get +2/+2.",
"result": [
[
{
"costs": "tap",
"activatedAbility": {
"create": {
"amount": 1,
"type": { "and": ["human", "creature"] },
"size": { "power": 1, "toughness": 1 },
"color": "w"
}
}
},
{
"asLongAs": {
"actor": "you",
"does": {
"comparison": { "lte": 5 },
"value": "life"
}
},
"effect": {
"what": {
"type": "creature",
"prefixes": ["other"],
"suffix": {
"actor": "you",
"does": "control"
}
},
"does": {
"powerToughnessMod": {
"powerMod": 2,
"toughnessMod": 2
}
}
}
}
]
],
"card": {
"name": "Thraben Doomsayer",
"oracle_text": "{T}: create a 1/1 white Human creature token.\nFateful hour — as long as you have 5 or less life, other creatures you control get +2/+2."
}
}
Most notably result
is an array of possible parses. If there is more than one
possible parse, meaning it parses to a different json value, than it will
report an error of "Ambiguous parse"
. If the parse is incomplete, meaning it
expected more input than it got, then it will return a null
result with the
error "Incomplete parse"
. Finally, if the input was invalid, meaning there is
no possible parse tree for it, you will get a null
result and an Error
object describing where the parser failed.
We do not guarantee that all the parses are correct, it is just too much work to manually review all of them at this time. We do check many of the parses and fix any errors we discover from those, so we have high confidence that the vast majority of the parses are correct.
We greatly appreciate any contributions. You can check the issue
tracker for active bugs
and TODO items. You can also run npm run assess
to get a list of cards that
are failing to parse and try getting those to parse, before running this you
need to update submodules, setup the CubeCobra .env
file according to their
README and run npm i && npm setup
in the extern/CubeCobra
folder. It is
also appreciated if you improve the JSON output to make it more machine-readable,
so our users can better utilize it. When making commits that change the number
of cards "successfully," correctly or ambiguously, parsed please include
Parses <amount>/<cardCount>.
in your commit message. If you change how the
example would parse please update the README with the new version as well.