classbuilder.py
classbuilder.py works by reading a definition file to determine where its data is stored, then putting it together in the properly boilerplated format. The definition file is a series of entries, one per line, of the form "field: value", where field and value are each strings. Some fields are literal: the value gets used directly during formatting. Others are indirect: the value specifies one or more files to load, and the values inside those files are used instead of the value itself. When loading files, the filename used is the value, followed by the name of the mode currently in use, followed by ".txt"; if no file exists, then the program uses just the filename and ".txt". If that doesn't exist, the program crashes. For example, when in bbcode mode, the line "Rants: rant1" would first try to load a rant from rant1.bbcode.txt; if that failed, the program would try rant1.txt, and then it would crash if that didn't exist.
When possible, examples are taken from the Test Class.
Class Descriptor File
Meaningful fields in all formats are as follows.
- Name: The name of the class: "Test Class". This will be used exactly as typed, with leading and trailing whitespace trimmed.
- Names: As above, but plural: "Test Classes"
- Name's: As above, but possessive: "Test Class's"
- Names': As above, but plural possessive: "Test Classes'"
- AAn: Whether to use a or an: a Test Class versus an Enchanter. Should be "a" or "an", must be lowercase (unless you want all instances of it to be uppercase).
- Quote: The filename of a quote that gets displayed right under the class name up top.
- Description: The filename of a longer description for the class, giving an overall view of what the class does and some of its strengths and weaknesses.
- How to Play: The filename of a blurb on how to build and play the class, possibly including a few useful hints and some information about how hard the class is to play and how the class behaves in general.
- Races/People: The filename of a blurb about the kinds of people one would expect to take this class in-world. For example, elves are classically rangers, and stereotypical rogues grow up as orphans in dark alleys.
- Rants: Each word on this line specifies a filename for a rant.
- Prereqs: A filename for a file specifying the prerequisites for taking levels in the class, if any.
- HD: How large the class's hit dice are. Include the d in this: "d6".
- Skills: The filename of the file containing the list of the class's skills
- Skill Points: How many skill points per level the class gets.
- BAB: The class's base attack bonus progression. Can be one of "Good", "Moderate", or "Poor". Other values will work, but will cause major problems when in wiki mode.
- Fort:
- Ref: The class's save progressions. Can be either "Good" or "Poor". Same warning about over values as with the BAB.
- Will:
- Columns: The filenames of any special columns the class has on its table, such as the rogue's sneak attack damage or the monk's AC bonus.
- Profs: The filename of the file describing the class's weapon and armor proficiencies.
- Spellcasting: The first word on the line specifies the filename for the spellcasting blurb.
- Spells/Day: Specifies the filename of the file containing the spells/day chart.
- Spell List: Specifies the filename of the file containing the class's spell list.
- Spell Sources: Specifies the filename of the file containing the formats for citations for spells on the spell list.
- post: Specifies any postscripts. These are like rants, but they're placed at the very end of the class.
- A number: Specifies which abilities the class gets at that level. These are each filenames specifying that ability's text. To steal a line from the Tome Summoner, "1: rapidsummoning, summonedcohort, armoredcasting, aura" would mean that the class gets the abilities held in rapidsummoning.txt, summonedcohort.txt, armoredcasting.txt, and aura.txt all at level 1. Note that the same ability can be put on the list at different levels under different names, which makes it easier to do things like the SRD Fighter's bonus feats or the Rogue's Evasion and Improved Evasion.
These fields are used for extra formatting for the wiki's extra metadata, such as authorname and creation date. All of these are technically optional, but DNDwiki will complain at you if you leave any of them off.
- Author: The class's author.
- Creation Status: How far along the class is. For example, "Complete".
- Editing: What kind of edits you'd like. For example, "Please edit Constructively!", or "Spelling and Grammar only".
- Balance: The class's balance point. See http://dungeons.wikia.com/wiki/Dungeons ... nce_Points
- !Summary: A filename for a short summary of the class, to be displayed in the "all classes" list.
- Primary Ability: The class's primary ability type. See http://dungeons.wikia.com/wiki/Property:Class_Ability
- Ability Progression: The progression that the class has with its primary ability
- Minimum Level: Not entirely sure. The minimum level you have to be to take this class, maybe? Ask the wiki.
- !Alignment Rant: A filename for a rant about alignments and so on.
- Starting Gold: Starting gold for the class.
- Starting Age: Starting age for the class.
Some of these fields are optional, others are required. Of the required ones, some are automatically filled if they're not included (though if you include them but leave them blank they'll be specifically
excluded).
- Absolutely required:
- Name
- Names
- HD
- Skill Points
- BAB
- Fort
- Ref
- Will
- Automatically filled if not included, and how they get filled:
- Aan: defaults to "a"
- Name's: The program will attempt to construct it by adding "'s". This succeeds once in a while.
- Names': Same as above, by adding "'". Again, this succeeds once in a while.
- Quote: loaded from a file (quote)
- Description: loaded from a file (descript)
- How to Play: loaded from a file (playing)
- Races/People: loaded from a file (races)
- Skills: loaded from a file (skills)
- Profs: loaded from a file (profs)
- Completely optional:
- Rants
- Prereqs
- Columns
- post
- Spellcasting
- Spells/Day
- Spell List
- Spell Sources
File formats
Naturally, this is all useless if you don't know how to organize the files in question. Therefore, the various filetypes, and how they're parsed.
Quote:
Nothing special here. The entire contents of the file is pasted straight into the output with no processing whatsoever.
Description:
As with the quote, the entire contents of the file is pasted into the output. However, it's processed for token replacement and to for bbcode-->wiki format conversion.
How to Play:
The same as description. A "Playing the $class:" header is added before the contents of the file, so you don't need to add that yourself. It's processed for token replacement and to for bbcode-->wiki format conversion.
Races/People:
Exactly the same as both of the above. It's processed for token replacement and to for bbcode-->wiki format conversion.
Rants:
The first line of the file is the name of the rant, and everything after that is the body. The body is processed for token replacement and to for bbcode-->wiki format conversion.
Prereqs:
Same as before.
Skills:
Here we start getting into things that are slightly more complex. Each line of the skills file corresponds to a single skill. The last word on the line is the three-letter contraction of the skill's key ability (Str, Dex, Con, Int, Wis, Cha), and everything else is the skill name. To prevent the classbuilder from attempting to automatically link to the wiki's page for a skill when in wiki mode, prepend a "!" to the line, so that it looks like this: "!This skill doesn't exist Int". The skills will be automatically alphabetized before being output. In wiki mode, any knowledge skills will be pointed to the Knowledge Skill page to prevent redlinks. For example, the first few lines of a skill list might look like this:
Code: Select all
!Autohypnosis Wis
Concentration Con
Craft Int
Decipher Script Int
Knowledge [dungeoneering] Int
:
These are fun. The first line in the file is the column header. Every line after that is what goes on the level corresponding to that line. For example, a column devoted to the Rogue's sneak attack bonus would look like this:
Code: Select all
Sneak Attack
+1d6
+1d6
+2d6
+2d6
...
:
This is another simple one. It behaves like the simple description blurbs above. The body is processed for token replacement and to for bbcode-->wiki format conversion.
Spellcasting:
As the description and everything.
Spells/Day:
This is simply a table of spells per day, in the standard format. Rows are levels, columns are separated by spaces and - means "no spells of this spell level available at this level". The spells/day file for a Cleric would start off looking like this:
Code: Select all
3 1+1 - - - - - - - -
4 2+1 - - - - - - - -
4 2+1 1+1 - - - - - - -
5 3+1 2+1 - - - - - - -
5 3+1 2+1 1+1 - - - - - -
5 3+1 3+1 2+1 - - - - - -
6 4+1 3+1 2+1 1+1 - - - - -
6 4+1 3+1 3+1 2+1 - - - - -
:
Another tricky one. This file defines the class's custom spell list if it has one. Each line of the file is a spell level, starting with zero (there currently isn't a way to tell the classbuilder to start with SL1). Each spell level is composed of spells, which are separated by semicolons. Each spell has two parts: a source number and the spell name. These two are separated by a !, and the source number goes in front of the name: "0!Fireball". Leaving off the source number and the ! ("Fireball" alone) causes the program to assume that the spell comes from source 0. WARNING: the wiki's links to internal spells are insanely fragile. They are case-sensitive and the capitalization is somewhat messed up. If your spellbook is entirely redlinks, you need to go through your spell list and fix it.
Spell Sources:
This is by far the most complex part of the classbuilder. In fact, it requires you to know a very, very small amount of python (at least until I get around to adding shortcuts or macros for you). Every line of the sources file is a single source, and can be linked to from the spell list using its line number.
For those of you that aren't programmers, here's a heavily simplified explanation. Each source is actually a tiny chunk of python code that gets run inside the classbuilder. This chunk of python is given access to the spell's name (held in a variable called "value"), and its task is to encase that name in stuff until it's a cited and formatted properly. You can do this by adding strings together. When you type stuff in between quotation marks ("like this" or 'like this' or '''like this''' or """like this"""), that becomes an element that you can add to other elements (like value) with the + sign.
For those of you that
are programmers, a more detailed explanation. Each line is read into a buffer and then passed to python's eval() function. This causes it to execute exactly as if it were part of the source code, down to variables and working directory. What I do is run the proper line of code from the sources file, then stick the output directly into the spell list. The variable "value" is a string containing the name of the class, exactly as it's typed after the ! in the spell list file.
Now for some examples.
To start, we'll try something simple: simply italicizing the spell name in bbcode. Doing this is pretty simple:
There are three basic elements to this: the open tag, the spell name, and the close tag. All we have to do is add them all together, remembering that our spell name is "value".
Code: Select all
"[i]" + value + "[/i]"
Let's try something a bit more complicated. The standard citation format for the wiki is as follows: "[[SRD:Fireball|Fireball]]" or "[[SRD:Detect Magic|Detect Magic]]. To do this, note that this is constructed of a few basic parts: "[[SRD:", then the name of the spell, the a "|", then the name of the spell again, then "]]". So that's exactly what we put together:
Code: Select all
"[[SRD:" + value + "|" + value + "]]"
For those of you that know a lot of python, we can get really crazy. I'm only including this because a bunch of you will want it and as a demonstration of the kinds of things you can do with this system. This snippet of code turns a spell name into a link from a bbcode page to the hypertext SRD's spell pages.
Code: Select all
"[i][url=http://www.d20srd.org/srd/spells/" + re.sub(r"[ ,'/*]", "", value) + ".htm]" + spell.title() + "[/url][/i]"
The basic order in which this went together:
Code: Select all
[*] re.sub(r"[ ,'/*]", "", value) takes value and runs it through a regex substitution. This replaces all instances of space, comma, apostrophe, slash, and asterisk characters with "", in effect deleting them. This turns "Spell Name, Lesser" into "spellnamelesser", which is what the hypertext SRD likes.
[*] The url for the SRD goes like "http://www.d20srd.org/srd/spells/spellname.htm", so we take the first part of the url tag "[url=", append the value that we got out of the regex (spellname), and then cap it off with with a ".htm]".
[*] spell.title() makes the spell name Title Case. It then gets appended to our [url=] tag.
[*] We then close both of our tags with the "[/url][/i]", and our formatting is complete.
:
Posts behave exactly like rants; they're just placed differently. First line is title, body is processed and posted.
Abilities:
Abilities are the other complex format. An ability definition has three parts: names, type, and body. The names take up the first line, the type takes up the second if it's present, and the body is everything else.
The first line of an ability file defines its names. The name provided in the class definition file is simply a pointer to the file; it has no effect on the actual output. This line, on the other hand, does. In its most basic form, this line is just the name of the ability: "Ability Name". In complexly recurring abilities (like the Rogue's Uncanny Dodge line), this line actually defines several names, which are used in order as the ability appears multiple times in the class's table. These names all go on the same line, and are separated by "|"s. For example, given "Uncanny Dodge|Improved Uncanny Dodge", the first time the ability is given in the class it will show up as "Uncanny Dodge", but on the second (and further) appearances it'll be "Improved Uncanny Dodge". The first name is the one used to head the ability block.
If the second line of the ability file is a single word (no spaces at all), it will be interpreted as an ability type (such as Ex, Su, or Ps), and the classbuilder will take this into account and provide the proper links.
If the second line has any spaces on it, then the body of the ability starts on the second line; otherwise, it starts on the third. The body is processed heavily for replaceable tokens and for bbcode-->wiki formatting, and is then pasted into the output in the appropriate location.
Summary:
The full text of the file is processed and put directly into the output.
Text Processing
Before being output, most of the larger chunks of text in the program get fed through some code that processes them to make building classes easier. It also provides tools for building source code that works for multiple output formats without modification.
- $#lev, where # is a number, is replaced with the level at which the ability is gained for the #th time. The first time the ability is gained is at $1levth. The output of this replacement is a numeral digit; it isn't written out. Using the Test Class as an example, the ability "Ability 1" is gained at levels 1, 4, and 7. To generate that string ("the ability... 7."), you would write "the ability "Ability 1" is gained at levels $1lev, $2lev, and $3lev".
- $lev is equivalent to $1lev
- $levth and $#levth work like $lev and $#lev, but instead of a basic number, the output is the corresponding ordinal number. For example, on Ability 1, $2levth becomes "4th", and $levth becomes "1st".
- $abname is replaced with the name of the ability that's being defined. For example, in an ability named "Ability 1", $abname will be replaced with "Ability 1".
- $cn is replaced with the value of the Name field in the definition file (the name of the class).
- $cnplu is replaced with the value of the Names field in the definition file (the plural version of the class's name)
- $cnpos is replaced with the value of the Name's field (the possessive)
- $cnplupos is replace with the value of the Names' field (the plural possessive)
- $a and $A are replaced with the correspondingly capitalized value of the AAn field. This is used for the indefinite article corresponding to the class's name. For example, in a class named "Test Class", to create "A Test Class.", you would type "$A $cn.". If you decided to change the name of the class to, say, "Enchanter", then you would change the AAn value to "an", and your ability source would still work without modification: "$A $cn" would generate "An Enchanter".
- <ifdef $mode>Text</ifdef> is deleted unless you're in output mode $mode, in which case the output is simply the text between the tags. To draw an example from the Test Class's ability1, this can be used to define differences between wiki and bbcode source without replacing the entire ability. This is useful with links, because the wiki's link format and bbcode's link formats are incompatible. When in bbcode mode, this resolves to [ url=www.google.com]a link in bbcode mode[/url], but in dndwiki mode this resolves to [http://www.google.com a link in wiki mode].
Code: Select all
<ifdef bbcode>[url=www.google.com]a link in bbcode mode[/url]</ifdef><ifdef dndwiki>[http://www.google.com a link in wiki mode]</ifdef>
- When in dndwiki mode, all instances of and [/i ] are converted to '' (but not the other way around!). This enables you to write your class with bbcode italics formatting and be able to use it in wiki mode without being changed.
- The same is done with the tags for bold: and [/b ] are converted to '''.
- All instances of
- and [/list ] are deleted.
- All instances of
- at the beginning of lines are replaced with *. If you're careful about how you format your lists, these two substitutions means that lists that are written in bbcode format are automatically converted to wiki formatting.
