Matrix Games Forums

To End All Wars: Mountain InfantryPandora: Eclipse of Nashira Announced! Deal of the Week: Command Ops goes half price!New Fronts are opening up for Commander: The Great WarCharacters of World War 1Sign of for the Pike and Shot Beta!More Games are Coming to Steam! Return to the Moon on October 31st! Commander: The Great War iPad Wallpapers Generals of the Great War
Forums  Register  Login  Photo Gallery  Member List  Search  Calendars  FAQ 

My Profile  Inbox  Address Book  My Subscription  My Forums  Log Out

AGEpp -- an AGE code beautifier

 
View related threads: (in this forum | in all forums)

Logged in as: Guest
Users viewing this topic: none
  Printable Version
All Forums >> [Current Games From Matrix.] >> [World War I] >> Revolution Under Siege >> Mods and Scenarios >> AGEpp -- an AGE code beautifier Page: [1]
Login
Message << Older Topic   Newer Topic >>
AGEpp -- an AGE code beautifier - 11/20/2012 7:14:22 PM   
berto


Posts: 4206
Joined: 3/13/2002
From: metro Chicago, Illinois, USA
Status: offline

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!

< Message edited by berto -- 11/25/2012 5:26:43 AM >


_____________________________

Early MusiChicago, http://earlymusichicago.org
PIKT, http://pikt.org
Campaign Series Lead Programmer, http://www.matrixgames.com/forums/tt.asp?forumid=226
AGElint debugging toolkit, http://www.matrixgames.com/forums/tm.asp?m=2978333
Post #: 1
AGEpp -- MUST READS & README - 11/20/2012 7:16:00 PM   
berto


Posts: 4206
Joined: 3/13/2002
From: metro Chicago, Illinois, USA
Status: offline

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

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




    < Message edited by berto -- 11/20/2012 7:28:24 PM >


    _____________________________

    Early MusiChicago, http://earlymusichicago.org
    PIKT, http://pikt.org
    Campaign Series Lead Programmer, http://www.matrixgames.com/forums/tt.asp?forumid=226
    AGElint debugging toolkit, http://www.matrixgames.com/forums/tm.asp?m=2978333

    (in reply to berto)
  • Post #: 2
    AGEpp INSTALL - 11/20/2012 7:17:15 PM   
    berto


    Posts: 4206
    Joined: 3/13/2002
    From: metro Chicago, Illinois, USA
    Status: offline

    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.




    < Message edited by berto -- 11/20/2012 7:30:55 PM >


    _____________________________

    Early MusiChicago, http://earlymusichicago.org
    PIKT, http://pikt.org
    Campaign Series Lead Programmer, http://www.matrixgames.com/forums/tt.asp?forumid=226
    AGElint debugging toolkit, http://www.matrixgames.com/forums/tm.asp?m=2978333

    (in reply to berto)
    Post #: 3
    AGEpp USAGE - 11/20/2012 7:18:24 PM   
    berto


    Posts: 4206
    Joined: 3/13/2002
    From: metro Chicago, Illinois, USA
    Status: offline

    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 '='.




    < Message edited by berto -- 11/20/2012 7:32:25 PM >


    _____________________________

    Early MusiChicago, http://earlymusichicago.org
    PIKT, http://pikt.org
    Campaign Series Lead Programmer, http://www.matrixgames.com/forums/tt.asp?forumid=226
    AGElint debugging toolkit, http://www.matrixgames.com/forums/tm.asp?m=2978333

    (in reply to berto)
    Post #: 4
    AGEpp -- What's the point? - 11/20/2012 7:19:12 PM   
    berto


    Posts: 4206
    Joined: 3/13/2002
    From: metro Chicago, Illinois, USA
    Status: offline

    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?



    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.



    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.



    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.



    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?





    < Message edited by berto -- 11/21/2012 8:50:29 AM >


    _____________________________

    Early MusiChicago, http://earlymusichicago.org
    PIKT, http://pikt.org
    Campaign Series Lead Programmer, http://www.matrixgames.com/forums/tt.asp?forumid=226
    AGElint debugging toolkit, http://www.matrixgames.com/forums/tm.asp?m=2978333

    (in reply to berto)
    Post #: 5
    AGEpp -- v1.0.1 official release - 11/22/2012 8:54:00 PM   
    berto


    Posts: 4206
    Joined: 3/13/2002
    From: metro Chicago, Illinois, USA
    Status: offline

    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!

    _____________________________

    Early MusiChicago, http://earlymusichicago.org
    PIKT, http://pikt.org
    Campaign Series Lead Programmer, http://www.matrixgames.com/forums/tt.asp?forumid=226
    AGElint debugging toolkit, http://www.matrixgames.com/forums/tm.asp?m=2978333

    (in reply to berto)
  • Post #: 6
    Page:   [1]
    All Forums >> [Current Games From Matrix.] >> [World War I] >> Revolution Under Siege >> Mods and Scenarios >> AGEpp -- an AGE code beautifier Page: [1]
    Jump to:





    New Messages No New Messages
    Hot Topic w/ New Messages Hot Topic w/o New Messages
    Locked w/ New Messages Locked w/o New Messages
     Post New Thread
     Reply to Message
     Post New Poll
     Submit Vote
     Delete My Own Post
     Delete My Own Thread
     Rate Posts


    Forum Software © ASPPlayground.NET Advanced Edition 2.4.5 ANSI

    0.072