mtgtool
This is a primitive "Magic: The Gathering" card data viewer for the console. It uses the card data from http://mtgjson.com.
basic usage
On the first run, mtgtool.py
pulls the card data from http://mtgjson.com/,
and builds below ~/.mtgtool/
an sqlite DB from it.
This DB can be queried for card data by passing the precise original English
card name with the -c
option:
$ ./mtgtool.py -c 'Black Lotus'
There are multiple printings of this card in different sets. Showing the printing of newest set: VMA
NAME: Black Lotus
NAMES:
LAYOUT: normal
MANA COST: {0}
CONVERTED MANA COST: 0
CURRENT TYPE: Artifact
PRINTED TYPE: Artifact
POWER: None
TOUGHNESS: None
MAX HAND SIZE MODIFIER: None
STARTING LIFE TOTAL MODIFIER: None
FLAVOR:
ORACLE TEXT:
{T}, Sacrifice Black Lotus: Add three mana of any one color to your mana pool.
PRINTED TEXT:
{T}, Sacrifice Black Lotus: Add three mana of any one color to your mana pool.
RARITY: Special
COLOR:
COLOR IDENTITY:
SUPERTYPES:
TYPES: Artifact
SUBTYPES:
PRINTINGS: LEA, LEB, 2ED, CED, CEI, VMA
RULINGS:
LEGALITIES:
Commander: Banned
Legacy: Banned
Vintage: Restricted
FOREIGN NAMES:
If a card is available in more than one set, then the printing from the newest
set is selected by default (see example above). A specific set can be selected
by its acronym via the -p
option (in the example, note the differences in the
rarity and the printed types and texts):
$ ./mtgtool.py -c 'Black Lotus' -p LEA
NAME: Black Lotus
NAMES:
LAYOUT: normal
MANA COST: {0}
CONVERTED MANA COST: 0
CURRENT TYPE: Artifact
PRINTED TYPE: Mono Artifact
POWER: None
TOUGHNESS: None
MAX HAND SIZE MODIFIER: None
STARTING LIFE TOTAL MODIFIER: None
FLAVOR:
ORACLE TEXT:
{T}, Sacrifice Black Lotus: Add three mana of any one color to your mana pool.
PRINTED TEXT:
Adds 3 mana of any single color of your choice to your mana pool, then is discarded. Tapping this artifact can be played as an interrupt.
RARITY: Rare
COLOR:
COLOR IDENTITY:
SUPERTYPES:
TYPES: Artifact
SUBTYPES:
PRINTINGS: LEA, LEB, 2ED, CED, CEI, VMA
RULINGS:
LEGALITIES:
Commander: Banned
Legacy: Banned
Vintage: Restricted
FOREIGN NAMES:
To identify the original name for translated cards, a translated name can be
passed to the -t
option:
$ ./mtgtool.py -t Seelenfeuer
'Seelenfeuer' is the German name for: Soul Burn
'Seelenfeuer' is the German name for: Soul's Fire
card data formatting
templating
The card data output format in the examples above is not fixed. A template
string can be provided with the -f
option. The string may enclose certain
keywords in %
symbols, to be replaced with the respective card data:
$ ./mtgtool.py -c 'Thermo-Alchemist' -f 'Card name: %name% (%mana_cost%)'
Card name: Thermo-Alchemist ({1}{R})
Some card data is iterable (cards may have more than one name, color, etc.;
certain card texts consist of multiple lines). Here, the formatting can be
further refined with a format name appended to a data key after a |
separator.
The available formats are comma
(separate items by ,
) and indent
(each
item its own line, indented with two whitespaces):
$ ./mtgtool.py -c 'Thermo-Alchemist' -f '%subtypes|comma%'
Human, Shaman
$ ./mtgtool.py -c 'Thermo-Alchemist' -f '%subtypes|indent%'
Human
Shaman
If no format is selected for such items, the default is separation by comma.
The following card data keys are legal and accept the formatting suffixes
|comma
and |indent
:
names
flavor
oracle_text
printed_text
color
color_identity
supertypes
types
subtypes
sets
rulings
legalities
foreign_names
The following card data keys are legal, but accept no formatting suffix:
name
layout
mana_cost
converted_mana_cost
current_type
printed_type
power
toughness
max_hand_size_mod
start_life_total_mod
rarity
To put a literal %
into a template string, escape it with another %
:
$ ./mtgtool.py -c 'Thermo-Alchemist' -f '%%%name%%%'
%Thermo-Alchemist%
suppressing non-essential messages
The -q
option suppresses some non-essential messages such as "there are
multiple printings of this card" warnings.
deck browser
Text files that contain descriptions of card collections or decks in readable
format can be opened for browsing in an ncurses interface with the -d
option.
In the browser, cards are sorted alphabetically, and multiple lines of the
source file counting the same card are combined into single lines with the card
sums added together, except where they differ in their belonging to the
sideboard or not.
The following formats are readable:
deck file format 1
The deck file parser ignores lines that contain only whitespace, or where the
first non-whitespace characters are //
. On non-ignored lines, whitespace
sequences on the start and the end of the line are ignored. The first
non-whitespace token per line must be either SB:
(which marks the entry as
cards belonging to a sideboard), or an integer; if the first token is SB:
, it
must be followed by any (or no) amount of whitespace, and an integer as the
second token. The integer describes the amount of cards described by the line.
After the integer, a positive number of whitespace characters must follow, and
after those a positive number of characters (the first of which must be
non-whitespace) that ought to match an English MTG card name.
In short, each line must match this regex: ^\s*(//.*|(SB:)?\s*\d+\s+\S.*)?$
As an example, the following is valid to the parser:
4 Act of Treason
1 Advice from the Fae
//in the browser, the upper and lower line will be combined to "3 Advice from the Fae"
2 Advice from the Fae
// another comment followed by an empty line
3 4 Altar's Reap
2 Ancient Crab
// the following line is not empty, but only contains whitespace
SB:2 Ancient Crab
SB: 1 Assassinate
SB:1 Assassinate
// the following line contains lots of trailing whitespace
999 Cinder Glade
deck file format 2
Mostly the same parsing rules apply as for format 1. The difference affects the
sideboard marker: An SB:
token is not accepted, whereas a single line whose
non-whitespace consists of the string Sideboard
is. All cards below this line
are counted as belongig to the sideboard, and a file which contains this
sideboard marker but no cards listed below it is invalid.
Each line must match this regex: ^\s*(//.*|Sideboard\s*|\d+\s+\S.*)?$
As an example, the following is valid to the parser:
4 Act of Treason
1 Advice from the Fae
//in the browser, the upper and lower line will be combined to "3 Advice from the Fae"
2 Advice from the Fae
// another comment followed by an empty line
3 4 Altar's Reap
2 Ancient Crab
// the following line is not empty, but only contains whitespace
// the following line contains lots of trailing whitespace
999 Cinder Glade
Sideboard
2 Ancient Crab
1 Assassinate
1 Assassinate
testing
Just run ./test.sh
.
updating
When a new set is released, the card data retrieved from http://mtgjson.com/
should be updated. To do so, just trigger a rebuild of the database by deleting
~/.mtgtool/db.sqlite
.
bugs
As of 2017-01-16, the data from http://mtgjson.com/ is somewhat incomplete in regards to translated names. Some examples: German "Zwang" should not only be "Duress", but also "Coercion"; German "Sturmgeist" should be "Storm Spirit"; German "Dominieren" should not only be "Domineer", but also "Dominate".
todo
Make DB updating a command line option.
Make card name search more tolerant (case-insensitive?).
Don't write browser error_log into current directory, rather into ~/.mtgtool/; and output its content on browser closing.