AGEpp -- an AGE code beautifier

Post new mods and scenarios here.
Post Reply
User avatar
berto
Posts: 21461
Joined: Wed Mar 13, 2002 1:15 am
Location: metro Chicago, Illinois, USA
Contact:

AGEpp -- an AGE code beautifier

Post by berto »


Here, for your coding pleasure, is AGEpp.

What is AGEpp? AGEpp is akin to a common programmer's tool, the code beautifier, or "pretty printer". (See http://en.wikipedia.org/wiki/Pretty_printer.) AGEpp is a tool to reformat poorly laid out, confusing, hard to read AGE event scripting code.

Why does this matter? What's the point? For answers, please see the AGEpp README (BACKGROUND section) in post #2 following, also the before-and-after code examples in post #5 below.

(Standard disclaimer: I offer no judgment about AGEOD, or its games. Nothing asserted, nothing implied. AGEpp is a tool, not a weapon. We use it to build better games, not to tear down any company or anybody. Please let's keep our discussions positive and constructive, shall we?)

In the spirit of empowering modders, and bettering the gaming experience, I give you AGEpp.

Here is the second "official" AGEpp version, 1.0.1 (20121122): See also: AGElint -- an AGE debugging toolkit

Modders of the world unite! You have nothing to lose but your confusion!
Campaign Series Legion https://cslegion.com/
Campaign Series Lead Coder https://www.matrixgames.com/forums/view ... hp?f=10167
Panzer Campaigns, Panzer Battles Lead Coder https://wargameds.com
User avatar
berto
Posts: 21461
Joined: Wed Mar 13, 2002 1:15 am
Location: metro Chicago, Illinois, USA
Contact:

AGEpp -- MUST READS & README

Post by berto »


AGEpp MUST-READS

Here are some must-read docs for installing and making best use of AGEpp:
AGEpp README

===============================================================================

Here, for your coding pleasure, is AGEpp.

What is AGEpp? AGEpp is akin to a common programmer's tool, the code beautifier, or "pretty printer". (See http://en.wikipedia.org/wiki/Pretty_printer.) AGEpp is a tool to reformat poorly laid out, confusing, hard to read AGE event scripting code.

(Standard disclaimer: I offer no judgment about AGEOD, or its games. Nothing asserted, nothing implied. AGEpp is a tool, not a weapon. We use it to build better games, not to tear down any company or anybody. Please let's keep our discussions positive and constructive, shall we?)

In the spirit of empowering modders, and bettering the gaming experience, I give you AGEpp.

Modders of the world unite! You have nothing to lose but your confusion!

===============================================================================

In order to install and run AGEpp, you will need to use (a) Linux (or some other suitable Unix-like OS, such as FreeBSD); and/or (b) Cygwin for Windows (or some other Unix-like environment for Windows).

AGEpp, at least as currently constituted, is firmly rooted in Unix/Linux. (Note: after this, I will mostly cease referring to Unix/Linux, Cygwin, and qualifying the terms. Henceforth, I will mostly just use "Linux". You should take that to mean Linux, but also any of the alternative compatible host environments. I will only qualify as necessary.)

I make no apologies for that. AGEpp works on the vast amounts of AGEOD game text file data. And Linux, in countless ways, is a superior OS to Windows for raw data processing. (If you doubt that, just consider this one fact: Most of the world's financial exchanges are now Linux-based. But also: Linux is at the heart of many well known cutting edge technology companies, such as Google. And if not Linux, one form or another of Unix. Windows is okay as a consumer and gaming OS, but for back-end production work, Unix/Linux is king.)

To install and run AGEpp, it's easiest simply to do it on Linux, with AGEOD game installations to process copied to your Linux filesystem (using rsync or scp/WinSCP over the network, for example), else installed on a USB stick (the method I preferred).

If you are not prepared to run this in Linux, there is at least one Windows-based Unix environment alternative -- Cygwin for Windows. See

http://cygwin.com/

From the Cygwin home page:

Cygwin is:

* a collection of tools which provide a Linux look and feel environment for Windows.
* a DLL (cygwin1.dll) which acts as a Linux API layer providing substantial Linux API functionality.

Cygwin is not:

* a way to run native Linux apps on Windows. You must rebuild your application from source if you want it to run on Windows.
* a way to magically make native Windows apps aware of UNIX® functionality like signals, ptys, etc. Again, you need to build your apps from source if you want to take advantage of Cygwin functionality.

I have installed and used Cygwin for Windows over the years on multiple Windows systems. It is easy to install. It's a nice way to get your feet wet with Unix, short of diving right into Unix/Linux.

If you are handy with Linux, indeed if you are "just" a Windows power user, installing Cygwin is not that hard. It's certainly no harder than (following the "official" AGEOD modding procedure):

--installing OpenOffice
--installing the AGE CSV splitter
--editing the "official" AGEOD DB/.xls files
--saving those files as .csv files
--running those saved .csv files through the CSV splitter
--placing the resulting game data files in their appropriate folders
--running the AGEOD game in special edit mode
--saving the game
--etc.

I will have nothing more to say about the "difficulty" of installing/running Linux/Cygwin. You decide how far your comfort zone extends.

For installing AGEpp itself, please see the INSTALL_AGEPP file.

===============================================================================

BACKGROUND

Turning away from my AGElint project for a while, and with the intent to begin modding, I begin to read the game Event files -- this time, not with an eye for syntax, but rather for *meaning*. I find the Event script layout to be confusing, hard to read. It

[*]has inconsistent line spacing
[*]has inconsistent indentation
[*]runs together in one continuous stream, doesn't clearly demarcate independent sections of code
[*]has gratuitous NULL lines
[*]is littered with duplicate, redundant SelectFaction & SelectRegion statements
[*]suffers from other deficiencies

that detract from the clarity and that obscure logic and meaning.

It seems to me that the mangled formatting in the default event scripting code is the result of (a) problems in the source DB (.xls) files, (b) CSV Splitter quirks, and (c) careless human text file edits.

I don't know about you, but being the visual thinker that I am, I really need to reformat, beautify, "pretty print" the "ugly" event scripting code.

AGEpp

[*]applies consistent line spacing
[*]applies consistent indentation
[*]demarcates events and other code sections with horizontal rules
[*]removes gratuitous, pointless NULL lines (while retaining legitimate comments)
[*]combines and consolidates SelectFaction & SelectRegion statements
[*]other

that, in their totality, make AGE event script code easier to read and understand.

Please refer to the distribution USAGE file to see how, using AGEpp, we accomplish that.

Refer to the INSTALL_AGEPP file for instructions on how to install AGEpp on your Windows (or Linux) PC. See the INSTALL_CYGWIN file, if you intend to run this in Windows.

Like AGElint, AGEpp is yet one more example of thinking outside the box. Indeed, for modding, the text file paradigm can be quite liberating.

At present, AGEpp only reformats event scripting code -- the Events/*.sct and Includes/*.inc files (and perhaps also the Scripts/*.ini files). We can tweak it, add more bells and whistles, and apply it to other AGE game data files in future as needed.

I would think that for anybody, easier to read and comprehend Events etc. files will lead to (a) fewer mistakes and (b) faster coding.

Good luck, and happy pretty printing!

Robert Osterlund
aka Berto
20121120

===============================================================================

Campaign Series Legion https://cslegion.com/
Campaign Series Lead Coder https://www.matrixgames.com/forums/view ... hp?f=10167
Panzer Campaigns, Panzer Battles Lead Coder https://wargameds.com
User avatar
berto
Posts: 21461
Joined: Wed Mar 13, 2002 1:15 am
Location: metro Chicago, Illinois, USA
Contact:

AGEpp INSTALL

Post by berto »


AGEPP INSTALL

Firstly:

Before attempting anything, *make proper backups first* (e.g., of your test Events directory).

Secondly:

--If Windows is your working environment, you must have installed Cygwin beforehand. See the INSTALL_CYGWIN file for details.

--If Linux is your working environment, you should make sure you have installed

perl
less
zip/unzip

If anything is missing, just use your standard Linux software update facility.

Thirdly:

Open a Cygwin Terminal (or Linux terminal, depending), if you haven't done so already.

cd (change directory) to the folder where you have downloaded the agepp .zip file. I recommend that you download to the directory where you will run the agepp utilities from, e.g., ~/bin, /usr/local/bin, or perhaps your agelint directory (if you have installed AGElint on your system).

Unzip the agepp .zip file, for example as I have done here:

Robert@roberto ~/bin
$ pwd
/home/Robert/bin

Robert@roberto ~/bin
$ unzip agepp.windows.official.zip
Archive: agepp.windows.official.zip
inflating: AGEpp_1.0.20121120
inflating: Makefile
inflating: README
...
inflating: agepp.pl
inflating: agepp
...

Now run the commands

$ ./agepp -h
Usage: agepp [-h] [-b] [-a <agepp.pl path>] [-c <char>] [-f] <file>

and

$ ./agepp.pl -h
Usage: agepp.pl [-c <char>] [-h]

to see those programs' usage summaries.

If you see that, congratulations! You should have a working AGEpp.

(If you don't; if something went wrong, just post at the forum, else send me a PM or private e-mail: robert.osterlund@comcast.net)

(FYI: agepp is typically the program you will run at the command line. agepp is a "wrapper" program that calls the agepp.pl Perl script. It is agepp.pl that does that actual code reformatting.)

See the USAGE file, and/or the forum, for instructions on how to make use of AGEpp.

Campaign Series Legion https://cslegion.com/
Campaign Series Lead Coder https://www.matrixgames.com/forums/view ... hp?f=10167
Panzer Campaigns, Panzer Battles Lead Coder https://wargameds.com
User avatar
berto
Posts: 21461
Joined: Wed Mar 13, 2002 1:15 am
Location: metro Chicago, Illinois, USA
Contact:

AGEpp USAGE

Post by berto »


AGEPP USAGE

Before attempting anything, *make proper backups first* (e.g., of your test Events directory).

Then cd to the Events directory of your choice, for example as I have here (for official RUS):

Robert@roberto ~
$ cd "/cygdrive/c/Games/AGEOD/Revolution under Siege/RUS/Events"

To reformat a single event file:

Robert@roberto /cygdrive/c/Games/AGEOD/Revolution under Siege/RUS/Events
/home/Robert/bin/agepp "GRNAI.sct"

For '/home/Robert/bin/agepp', substitute your actual path to the agepp program, of course.

(FYI: agepp is typically the program you will run at the command line. agepp is a "wrapper" program that calls the agepp.pl Perl script. It is agepp.pl that does that actual code reformatting.)

For the converted file, open it in NotePad (or whatever). Verify that things appear to be agepp processed.

To convert all of the events files in the current Events directory, try for example as I have done here (the quote marks are essential):

Robert@roberto /cygdrive/c/Games/AGEOD/Revolution under Siege/RUS/Events
$ for f in *.sct; do echo "$f"; /home/Robert/bin/agepp "$f"; done
01Tutorial.sct
03Tutorial.sct
1-IceMarch1917.sct
3-November1918.sct
4-May1919.sct
5-Finland1918.sct
6-Poland1920.sct
7-Drang1921.sct
AI Training.sct
AIAggro_Red.sct
AIAggro_WH3.sct
AIAggro_WHI.sct
...

For '/home/Robert/bin/agepp', substitute your actual path to the agepp program, of course.

For any of the converted files, open them in NotePad (or whatever). Verify that things appear to be agepp processed.

Then launch the game, and test as needed.

For help:

Robert@roberto ~/bin
$ ./agepp -h
Usage: agepp [-h] [-b] [-a <agepp.pl path>] [-c <char>] [-f] <file>

The '-b' option makes .bak backups *in the same directory*. It should be quite safe, but you may want to move (using the mv command) the .bak files to another directory before launching and running the game.

To reformat a single event file, with backup:

Robert@roberto /cygdrive/c/Games/AGEOD/Revolution under Siege/RUS/Events
/home/Robert/bin/agepp -b "GRNAI.sct"

To convert all of the events files in the current Events directory, with backups, try for example as I have done here (the quote marks are essential):

Robert@roberto /cygdrive/c/Games/AGEOD/Revolution under Siege/RUS/Events
$ for f in *.sct; do echo "$f"; /home/Robert/bin/agepp -b "$f"; done

Use the '[-a <agepp.pl path>]' only if, for some strange reason, you have installed the agepp.pl program in a directory different from where you have installed agepp.

The [-c <char>] arguments override the default '=' as the HR (horizontal rule) character for NULL section dividers.

In AGEpp, the standard, default code divider (the default HR) is:

NULL ==========================================================================

For a variant of that, if you prefer, try instead

Robert@roberto /cygdrive/c/Games/AGEOD/Revolution under Siege/RUS/Events
$ for f in *.sct; do echo "$f"; /home/Robert/bin/agepp -c X "$f"; done

which would render the code HRs as

NULL = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

With some exceptions, you can use just about any -c character you wish. But you will probably want to stick with the default '='.

Campaign Series Legion https://cslegion.com/
Campaign Series Lead Coder https://www.matrixgames.com/forums/view ... hp?f=10167
Panzer Campaigns, Panzer Battles Lead Coder https://wargameds.com
User avatar
berto
Posts: 21461
Joined: Wed Mar 13, 2002 1:15 am
Location: metro Chicago, Illinois, USA
Contact:

AGEpp -- What's the point?

Post by berto »


AGEpp -- What's the point?

(In all examples following, the left-hand version is original code. The right-hand version is AGEpp-processed, reformatted code.)

Take a look at this screenshot. Of the two alternatives, which version of (RUS') Various Events.sct file is easier to read?

Image

In the left-hand version, line spacing is random. Indentation is inconsistent. SelectFaction & SelectRegion statements and code run together. Where do events begin (StartEvent) and end (EndEvent)? It's all hard to see.

Look at the right-hand version. Line spacing and indentation are consistent. SelectFaction & SelectRegion statements stand out. NULL horizontal rules separate events one from another. Is not the right-hand version easier to follow?

Now take a look at another screenshot.

Image

To the left, see the annoying, and seemingly useless, 'NULL = NULL' statement in line 4? See the duplicate, redundant 'SelectFaction = $CMN' statements in lines 6 & 8? Further down, see the repeated 'SelectFaction = $CMN' & 'SelectRegion = $Ekaterinburg' couplets? Again, where do events begin and end? Not clear at all, is it?

To the right, see how the NULL horizontal rules clearly demarcate events one from another. Notice the three include statements at the beginning, clearly set off from the event blocks following. The duplicate, redundant SelectFaction & SelectRegion statements? They're gone!

Another screenshot.

Image

To the left, code just streams along. Again, it's hard to distinguish one event from another.

To the right, events, Conditions and Actions blocks are clearly set apart. The code is neat and orderly. Easier to read and comprehend, I wager.

Another screenshot.

Image

In the right-hand version, don't the CreateGroup and CreateUnit code blocks stand out better? (And again, note how the right side combines and consolidates the duplicate, repeating SelectFaction & SelectRegion statements just before the StartEvent.)

Here are two final screenshots. Between the left-hand versions and the right-hand versions, which do you prefer?

Image

Image
Campaign Series Legion https://cslegion.com/
Campaign Series Lead Coder https://www.matrixgames.com/forums/view ... hp?f=10167
Panzer Campaigns, Panzer Battles Lead Coder https://wargameds.com
User avatar
berto
Posts: 21461
Joined: Wed Mar 13, 2002 1:15 am
Location: metro Chicago, Illinois, USA
Contact:

AGEpp -- v1.0.1 official release

Post by berto »


Here is the second "official" AGEpp version, 1.0.1 (20121122): Just a minor change from AGEpp 1.0:

Changes from AGEpp_1.0 (20121120) to AGEpp_1.0.1 (20121122)

[*]For symmetry with the opening NULL section divider, ensured NULL section divider to end all files (especially Includes .inc files).

Enjoy!
Campaign Series Legion https://cslegion.com/
Campaign Series Lead Coder https://www.matrixgames.com/forums/view ... hp?f=10167
Panzer Campaigns, Panzer Battles Lead Coder https://wargameds.com
Post Reply

Return to “Mods and Scenarios”