AGElint -- an AGE debugging toolkit

[berto]

Here are some useful tips.

To determine globally the differences from one AGEOD release to the next, try for example:

---

Robert@roberto /home/Robert/Games/AGEOD/agelint
$ diff -r "/cygdrive/c/Games/AGEOD/Revolution under Siege 1.06" "/cygdrive/c/Games/AGEOD/Revolution under Siege" | tee RUS_1.06_1.06a.diff

---

The '| tee RUS_1.06_1.06a.diff' "pipes" the diff command output to the tee command, which sends the output to both screen and the indicated file, RUS_1.06_1.06a.diff.

If you prefer, you could use

---

Robert@roberto /home/Robert/Games/AGEOD/agelint
$ diff -r "/cygdrive/c/Games/AGEOD/Revolution under Siege 1.06" "/cygdrive/c/Games/AGEOD/Revolution under Siege" > RUS_1.06_1.06a.diff

---

which outputs just to the file.

To determine the differences between two folders, try for example:

---

Robert@roberto /home/Robert/Games/AGEOD/agelint
$ diff -r "/cygdrive/c/Games/AGEOD/Revolution under Siege 1.06/RUS/Events" "/cygdrive/c/Games/AGEOD/Revolution under Siege/RUS/Events" | tee RUS_Events.diff

---

To determine the differences between two files, try for example (note the absence of the '-r' option):

---

Robert@roberto /home/Robert/Games/AGEOD/agelint
$ diff "/cygdrive/c/Games/AGEOD/Revolution under Siege 1.06/RUS/Events/GRNAI.sct" "/cygdrive/c/Games/AGEOD/Revolution under Siege/RUS/Events/GRNAI.sct" | tee GRNAI.sct.diff

---

A really useful option to try is -c #, as in

---

Robert@roberto /home/Robert/Games/AGEOD/agelint
$ diff -c "/cygdrive/c/Games/AGEOD/Revolution under Siege 1.06/RUS/Events/GRNAI.sct" "/cygdrive/c/Games/AGEOD/Revolution under Siege/RUS/Events/GRNAI.sct" | tee GRNAI.sct.diff

---

which shows context around the diffs of, by default, 3 extra lines. You can control the amount of context, as in

---

Robert@roberto /home/Robert/Games/AGEOD/agelint
$ diff -C 9 "/cygdrive/c/Games/AGEOD/Revolution under Siege 1.06/RUS/Events/GRNAI.sct" "/cygdrive/c/Games/AGEOD/Revolution under Siege/RUS/Events/GRNAI.sct" | tee GRNAI.sct.diff

---

which would extend the context to 9 surrounding lines, before and after.

And so on. Like most Unix/Linux commands, there are a ton of options available. If you have the so-called Cygwin "man[ual] pages" installed in your setup (in Linux, the man pages would be installed by default), you might try the command

---

$ man diff

---

It pays to learn some of this Unix/Linux stuff. You might be surprised at what you find. [;)]

[berto]

In the early stages of AGElint's development, honest differences of opinion (as I saw it) arose over which game data files to bug check, or not to check. Rather than impose one view vs. another, I implemented the file Exclude feature, thereby leaving it for each AGElint user to decide.

For each AGElint-supported AGEOD game, there is a file -- for example, excludes.wia.dat -- where you specify which files AGElint should exclude, or ignore. You can specify files by pattern match, else by listing the exact file names that should be skipped.

The AGElint file Exclude feature is detailed here:

[*]AGElint: excludes.???.dat [post 122]

At the AGEOD Forum, WIA Patch 1.10e was announced several days ago. In the patch announcement, it says:

Removed the setups for the ''original'' 1755 Campaign, 1756 Montcalm scenario, and 1759 Annus Mirablis scenario, leaving the ''COL'' faction variants intact ... the game will still include the Events files for these scenarios to allow ongoing games to be completed.

This is a perfect opportunity to demonstrate the AGElint file Excludes feature.

In excludes.wia.dat we add (added files in boldface):

---

[root@berto agelint]# cat excludes.wia.dat
# wia excludes
(Test|Parse|Samples)
Scripts/Script.ini
Scens/1755 Campaign.scn
Scens/1759 Annus Mirabilis.scn
Scens/1756 Montcalm.scn
Scens/1756 Montcalm_RoiLouis.scn
Events/1755 Campaign.sct
Events/1759 Annus Mirabilis.sct
Events/1756 Montcalm.sct
Events/1756 Montcalm_RoiLouis.sct

---

AGElint will now ignore the listed files.

(Even though the Scens files above were removed, there's no harm in leaving them in excludes.wia.dat. AGElint will not complain if any excludes.???.dat references non-existent files.)

On 20121111, before the obsolete scenario setups were removed from WIA, also on 20121116, after removal of the scenario setups, I ran AGElint against the WIA game data files (using the command 'dochk wia QA'). diffing the report files, I see for example:

---

[root@berto agelint]# diff chklint_wia_QA_20121111_error_rpt.txt chklint_wia_QA_20121116_error_rpt.txt | less

...

< Events/1755 Campaign.sct, Fri Sep 7 2012 06:41:46
<
< ERROR: in Events/1755 Campaign.sct, at (or near) line 149: line-specific or other contextual syntax error: #-# (0x2d), #-1#
<
< in event evt_nam_FortEdward70:
<
< 140 StartEvent = evt_nam_FortEdward70|1|2|evt_txt_FortEdward70|Event-img2_Fort1.bmp|$Tajacook|NULL
< 141
< 142 Conditions
< 143 NotEnemy = $Tajacook
< 144
< 145 EvalRgnOwned = $Tajacook
< 146 MinDate = 1755/09/01
< 147 EvalRgnStruc = $Tajacook;FACALL;STRUCDEF $Village;NOT
< 148 EvalRgnStruc = $Tajacook;FACALL;STRUCDEF $Fort;NOT
< 149> CountUnits = $Tajacook;-1;$GBR;-1;>=;4
< 150
< 151 Actions
< 152 SelectFaction = $GBR
< 153
< 154 CreateStruc
< 155 SetType = $Fort
< 156 SetLevel = 1
< 157 SetName = Fort Edward
< 158 Apply
<
< http://www.ageod.net/agewiki/CountUnits
<
< Syntax: CountUnits = <area alias>; <region or area>; <faction>; <unit type>; <operator>; <number of units>

...

---

Interpretation: lines marked '<' are in the command's first listed file, chklint_wia_QA_20121111_error_rpt.txt, but not in the second, chklint_wia_QA_20121116_error_rpt.txt. The ERROR in Events/1755 Campaign.sct was reported before. After, it is not reported -- because the Events/1755 Campaign.sct file was excluded from the later (20121116, post excludes.wia.dat edit) AGElint error check.

(Note: This is not the place to quibble about whether the above is an actual ERROR or not. The point here is to demonstrate the AGElint Exclude feature, nothing more.)

You activate the Exclude mechanism via the '+E' command-line switch, as in:

---

./chklocals.pl +i +E +M -g wia

---

You de-activate excludes -- i.e., error check all files, including the ones specified in excludes.wia.dat -- via the '-E' command-line switch, as in:

---

./chklocals.pl +i -E +M -g wia

---

Just in case you want to error check all files for some reason.

If AGElint reports ERRORs (and WARNINGs ...) that you think are false positives because reported in obsoleted game data files (or test files or ...) -- the solution is pretty simple: Just exclude the files in the excludes.???.dat!

[berto]

I have just announced, and released, a companion utility to the AGElint toolkit: AGEpp -- an AGE code beautifier

AGEpp is a tool to reformat poorly laid out, confusing, hard to read AGE event scripting code.

In future, I will include the AGEpp programs (only; not the docs) -- agepp, agepp.pl, etc. -- in the AGElint distribution .zip file. That way, as an AGElint user, you will have the AGEpp utilities without having to do a separate AGEpp download and install.

Enjoy!

[Chilperic]

Works very well indeed.