Code-Formatierung mit Artistic Style

Transkript

1 Code-Formatierung mit Artistic Style Steffen Schäfer Michael Velten 29. März 2004 Reihe Berichte zur Softwaretechnik Herausgeber: Prof. Dr. Ulrich Eisenecker, Fachhochschule Kaiserslautern, Standort Zweibrücken, Institut für Componentware und Window-Oberflächen

2 Copyright-Vermerk Das Copyright für diesen Bericht liegt bei den Autoren und dem Herausgeber. Der Bericht darf ganz oder in Teilen nur mit schriftlicher Zustimmung der Autoren und des Herausgebers verwendet werden. Jede kommerzielle Nutzung ist ausgeschlossen. Die Autoren und der Herausgeber, Zweibrücken, den 16. März 2004 Haftungsausschluss Weder die Autoren noch der Herausgeber haften für die Richtigkeit der in diesem Bericht gemachten Angaben oder für Folgen oder Schäden, die aus der Verwendung dieses Berichts resultieren. Auch falls in diesem Bericht Warenzeichen nicht als solche gekennzeichnet sind, kann nicht davon ausgegangen werden, dass die entsprechenden Begriffe und Bezeichnungen frei von Rechten Dritter sind.

3 Vorwort des Herausgebers Die Berichte zur Softwaretechnik behandeln Themen, die in der Vorlesung Software-Technik aus Zeitgründen nur gestreift oder nicht vermittelt werden konnten, aber für die Praxis der Softwareentwicklung dennoch von Bedeutung sind. Sie richten sich an Studierende der Informatik oder der Wirtschaftsinformatik, die sich beispielsweise im Rahmen ihres Praxissemesters oder ihrer Diplomarbeit mit den betreffenden Themen auseinander setzen müssen, oder an sonstige interessierte Personen, die sich auf diesen Gebieten autodidaktisch weiter bilden wollen. Wir freuen uns über Ihre Korrekturvorschläge, Verbesserungshinweise und auch Anregungen für Themen, die im Rahmen dieser Reihe aufgegriffen werden können. Diese richten Sie bitte an den Herausgeber, dessen -Adresse Sie auf der Home Page eisenecker finden. Ulrich W. Eisenecker, Zweibrücken, den 16. März 2004

4 Inhaltsverzeichnis 1 Einleitung 1 2 Installation Allgemein Linux-Installation Windows-Installation Verwendung 2 4 Optionen Syntax Beschreibung Styles Beispiele Konfiguration Ablauf Dateiformat Beispiele Literatur 9

5 1 Einleitung Jeder Programmierer folgt bei der Formatierung von Quelltext seinem eigenen Stil. Manche Entwickler rücken zusammenhängende Codeblöcke mit Leerzeichen ein, andere verwenden statt dessen Tabulatoren. Manche Editoren ersetzen die Eingabe eines Tabulators auch durch Leerzeichen und umgekehrt. Öffnet man diese Dateien mit einem anderen Editor stimmt die Formatierung nicht mehr. Der Quelltext wirkt nun sehr durcheinander. Dies könnte beispielsweise der Fall sein, wenn eine datei mit vim geschrieben wurde und mit emacs geöffnet wird. Artistic Style, kurz astyle ist ein Satz von Filtern, programmiert in C++, der nach bestimmten Kriterien Quelltext einheitlich formatiert. Für die Verwendung von astyle gibt es zwei Möglichkeiten. Üblicherweise startet man astyle von der Konsole aus und übergibt die gewünschten Parameter. Es ist jedoch auch möglich, astyle über die Verwendung von Klassen direkt in Programme einzubinden. Dies funktioniert jedoch ausschließlich mit C++-Programmen. Im Folgenden wird nur die Verwendung von astyle als Kommandozeilenprogramm erläutert. Alle hier verwendeten Beispiele und Programmfragmente wurden unter Debian GNU/Linux erstellt und getestet. 2 Installation 2.1 Allgemein astyle wurde von Tal Davidson entwickelt und kann von der Home Page bezogen werden. Artistic Style kann unter der GPL (siehe [2]) oder der Artistic License (siehe [3]) benutzt werden. 2.2 Linux-Installation Für die Installation unter Linux benötigt man die Datei astyle zip. Zunächst wird ein neues Verzeichnis erstellt, in welches dann astyle entpackt wird. Wird astyle nicht in diesen Ordner entpackt, landet der gesammte Archivinhalt im aktuellen Verzeichnis, was unter Umständen nicht erwünscht ist. $ mkdir astylesrc $ unzip -d astylesrc astyle_ zip Da die später noch benötigten Optionen -t bzw. --indent=tab= und -T bzw. --force-indent=tab= von astyle nicht korrekt erkannt werden, muss die Datei astyle main.cpp gepatcht werden. Der Patch kann von [4] bezogen werden. Kopieren Sie die soeben heruntergeladene Datei astyle main.cpp.patch in das oben erstellte Verzeichnis astylesrc. Mit folgendem Befehl wird astyle entsprechend gepatcht: 1

6 $ patch -p0 < astyle_main.cpp.patch $ make Nun übersetzen Sie mit make den Quelltext von astyle. Im aktuellen Verzeichnis liegt anschließend die ausführbare Datei astyle vor. Das Programm kann nun mit./astyle gestartet werden. Da dies nur im aktuellen Verzeichnis funktioniert, muss entweder die ausführbare Datei in das Verzeichnis /usr/local/bin kopiert oder der Pfad entsprechend geändert werden. Unter Debian kann astyle mit dem Befehl $ apt-get install astyle installiert werden. 2.3 Windows-Installation Für die Installation unter Windows wird die Datei astyle win32.zip benötigt. In dieser Datei befindet sich bereits das vorkompilierte ausführbare Programm astyle.exe. Diese Datei kann man nach c:\windows kopieren oder den Pfad entsprechend ändern. Unter Cygwin erfolgt die Installation analog zu Linux. 3 Verwendung Es gibt zwei Möglichkeiten astyle zu benutzen, nämlich durch Übergabe von Kommandozeilenparametern oder durch die Umlekung der Standardein- und -ausgabe. Hier die erste Möglichkeit: astyle [OPTIONEN] [DATEI1] [DATEI2] [...] Dem Programm werden ein oder mehrere Dateinamen als Parameter übergeben. Außerdem kann man Optionen angeben, die das Ergebnis der Ausgabedatei beeinflussen. Hierbei ist zu beachten, dass dem Namen der ursprünglichen Quelltextdatei das Suffix.orig angehängt wird. Diese Vorgabe können Sie mit der Option -Suffix verändern. Die neu formatierte Datei erhält den ursprünglichen Dateinamen. astyle [OPTIONEN] < Quelltextdatei > Ausgabedatei Hier werden die Möglichkeiten der Shell genutzt. Die Quelltextdatei wird (durch die verwendete Shell) zum Lesen unter dem Dateideskriptor 0 (Standardeingabe) geöffnet (<), so dass astyle beim Lesen von der Standardeingabe von der Quelltextdatei liest. Die Ausgabedatei wird analog unter dem Dateideskriptor 1 (Standardausgabe) zum Schreiben geöffnet, so dass alle Ausgaben auf die Standardausgabe in die angegebene Ausgabedatei geschrieben werden. Dies funktioniert sowohl unter den üblichen Unix-Shells (Bourne Shell, C Shell) als auch unter Windows im Konsolenfenster. 2

7 4 Optionen Das Verhalten von astyle kann durch eine Vielzahl von Optionen an die jeweiligen Bedürfnisse des Benutzers angepasst werden. Wird das Programm ohne Optionen aufgerufen, werden laut Dokumentation folgende Standardeinstellungen für C/C++-Dateien verwendet: Vier Leerzeichen pro Einrückungsebene Keine Formatierung des Quelltextes Diese Einstellungen gelten darüberhinaus auch für Java-Dateien, da astyle als Standardvorgabe nicht zwischen C, C++ und Java unterscheidet. Desweiteren können die Quelltextdateien eine beliebige Dateierweiterung (wie etwa.cpp oder.java ) besitzen. Das Standardverhalten von astyle kann über die Konfigurationsdatei ~/.astylerc und die Umgebungsvariable ARTISTIC STYLE OPTIONS angepasst werden. Dies wird ausführlich in dem Abschnitt 5 beschrieben. 4.1 Syntax astyle hält sich an die sogenannte GNU command line syntax, wobei Optionen entweder ausgeschrieben oder als Kürzel angegeben werden können. Ausgeschriebene Optionen beginnen mit zwei Bindestrichen, --, Options-Kürzel mit einem Bindestrich, -. Im letzteren Fall können die Optionen verkettet werden. 4.2 Beschreibung Im Folgenden werden die wichtigsten Optionen und ihre Verwendung beschrieben. Weitere Optionen können der Dokumentation entommen oder mit dem Aufruf astyle --help 1 in Erfahrung gebracht werden. Falls die Ausgabe der zweiten Variante mittels Filter an ein Anzeigeprogramm wie etwa more oder less weitergeleitet wird, sollte astyle mit der Option --errors-to-standard-output bzw. -X aufgerufen werden, da sonst der Hilfetext auf die Standardfehlerausgabe (stderr) ausgegeben wird. Zuerst betrachten wir die wohl wichtigste Option, nämlich die einheitliche Einrückung entweder durch Tabulatoren oder durch Leerzeichen. Wie bereits in der Einleitung erwähnt, besitzt bei der Einrückung des Codes jeder Programmierer andere Präferenzen beziehungsweise jeder Editor andere Einstellungen. Die Meinungen über die beste Vorgehensweise gehen hier weit auseinander. Mittels der folgenden Option kann man den Quelltext in den für sich bevorzugten Einrückungsstil konvertieren. 1 Aufgrund der höheren Aktualität wird die Benutzung dieser Variante empfohlen 3

8 Zunächst die Option, um Leerzeichen in Tabs zu konvertieren: --force-indent=tab=# -T# Beachten Sie, dass die Option --force-indent=tab=# heißt und nicht --indent-tab=# wie fälschlich in der Dokumentation angegeben. Bei der ersten Zeile handelt es sich um die ausgeschriebene Form. Die zweite Zeile stellt das Pendant in der Kurzschreibweise dar. Anstatt der Raute muss eine Zahl angegeben werden, die bestimmt wie viele Leerzeichen jeweils durch ein Tabulator-Zeichen ersetzt werden sollen. Wird keine Zahl angegeben, wird standardmäßig 4 verwendet. Der Aufruf lautet dann --force-indent=tab=, nicht --force-indent=tab. Leider funktioniert dies nicht so wie in der Dokumentation angegeben. Vielmehr wird pro Einrückungstiefe ein Tabulator verwendet. Zunächst der C++-Beispiel-Code vor der Formatierung: //... int bar =1; i f ( foo ) { bar +=2; } Listing 1: Vor der Formatierung Der Code sieht nach dem Aufruf von astyle --force-indent=tab=2 bzw. astyle -T2 folgendermaßen aus. //... int bar =1; i f ( foo ) { bar +=2; } Listing 2: Nach Aufruf von astyle -T2 Wie zu sehen, wurden die sechs Leerzeichen durch ein Tabulator-Zeichen ersetzt. Dies bestätigt das oben beschriebene von der Dokumentation abweichende Verhalten, nach der nun eigentlich drei Tabs vorhanden sein sollten. Da die Verwendung von jeweils einem Tabulator pro Einrückung jedoch den üblichen Konventionen entspricht, ist dies nicht weiter schlimm. 4

9 In dem soeben erzeugten Code kann man durch folgende Option die Tabulatoren wieder in Leerzeichen verwandeln: --indent=spaces=# -s# astyle wird mit der Option -s3 aufgerufen, um pro Einrückung drei Leerzeichen zu verwenden. //... int bar =1; i f ( foo ) { bar +=2; } Listing 3: Nach Aufruf von astyle -s3 Eine weitere nützliche Option betrifft die Platzierung der geschweiften Klammern. Manche Programmierer bevorzugen es, die öffnende geschweifte Klammer zum Beispiel nach einer if-anweisung in die nächste Zeile zu setzen (siehe Listing 3). Andere bevorzugen es dagegen, die geschweifte Klammer in die selbe Zeile wie das if zu schreiben. Letzteres lässt sich mit folgender Option bewerkstelligen: --brackets=attach -a Listing 4 zeigt, wie das ursprüngliche Code-Beispiel (Listing 1) nach dem Aufruf von astyle mit dieser Option aussieht. //... int bar =1; i f ( foo ) { bar +=2; } Listing 4: Nach Aufruf von astyle -a Der resultierende Code wird nun etwas genauer untersucht. Zunächst ist ersichtlich, dass die geschweifte Klammer wie gewünscht in dieselbe Zeile wie die if-anweisung verschoben wurde. Allerdings wurden auch die ursprünglich sechs Leerzeichen durch vier Leerzeichen ersetzt. Hier greift die (in diesem Fall vielleicht nicht ganz so intuitive) Standardeinstellung von astyle, für eine Einrückungstiefe 5

10 immer vier Leerzeichen zu verwenden. Sollen die vormals sechs Leerzeichen beibehalten werden, muss explizit die Option -s6 mit angegeben werden. Abschließend betrachten wir die Möglichkeit, Leerzeichen zwischen Operatoren (etwa = oder += ) und deren Operanden einzufügen, um den Code etwas leserlicher zu gestalten. Dies läßt sich mit der folgenden Option erreichen: --pad=oper -p Diese Option wird nun auf den Code in Listing 4 angewendet. //... int bar = 1; i f ( foo ) { bar += 2; } Listing 5: Nach Aufruf von astyle -p Zunächst einmal kann man sehen, dass die gewünschten Leerzeichen um die Operatoren = und += eingefügt wurden. Allerdings fällt auf, dass die geschweifte Klammer wieder in die Zeile nach der if-anweisung verschoben wurde. Dies widerspricht eindeutig der Dokumentation, die besagt, dass standardmäßig keine Formatierung stattfindet. Fazit: Da astyle den ein oder anderen Fehler besitzt, sollte man die gewünschten Optionen möglichst explizit beim Aufruf mit angeben, um ungewollte Effekte zu vermeiden. Um sich diese ständig wiederkehrende Tipparbeit zu erleichtern, bietet sich die Verwendung einer Konfigurationsdatei an, die in Abschnitt 5 beschrieben wird. 4.3 Styles Styles sind vordefinierte Formatierungen, die mehrere Optionen bündeln und sich an bestimmte Standards oder Konventionen, etwa Kernighan&Ritchie oder den GNU Coding Style, halten. Welche Optionen sich nun konkret hinter einem Style verbergen, ist der Dokumentation leider nicht zu entnehmen. Falls Interesse daran besteht, kann man dies jedoch im Quelltext von astyle nachschauen. Der relevante Code befindet sich in der Datei astyle main.cpp zu Beginn der Funktion parseoption(). Listing 6 zeigt einen Auszug, der die Optionen enthüllt, die sich hinter dem Style gnu verbergen. 6

11 //... else i f ( IS OPTION( arg, s t y l e=gnu ) ) { f o r m a t t e r. setblockindent ( true ) ; f o r m a t t e r. s e t S p a c e I n d e n t a t i o n ( 2 ) ; f o r m a t t e r. setbracketformatmode (BREAK MODE) ; f o r m a t t e r. s e t C l a s s I n d e n t ( f a l s e ) ; f o r m a t t e r. setswitchindent ( f a l s e ) ; } //... f o r m a t t e r. setnamespaceindent ( f a l s e ) ; // G // s2 // b // C // S // N Listing 6: astyle main.cpp, parseoption() Zur besseren Verständlichkeit wurde das jeweilige Optionskürzel als Kommentar dem Code hinzugefügt. 4.4 Beispiele Hier finden sich einige Beispiele, die die zuvor beschriebenen Optionen verwenden und die verschiedenen Möglichkeiten des Aufrufs von astyle veranschaulichen. Im ersten Beispiel werden alle Optionen in der ausgeschriebenen Form angegeben: $ astyle --brackets=attach --pad=oper --force-indent=tab=4 < vorher.cpp > nachher.cpp Man beachte, dass der Programmaufruf lediglich der besseren Lesbarkeit halber auf zwei Zeilen verteilt wurde. Normalerweise steht der Aufruf in einer Zeile. Das folgende Beispiel verwendet die dem obigen Aufruf entsprechenden Options-kürzel. Die Bedeutung und die resultierende Quelltextdatei nachher.cpp sind jedoch vollkommen äquivalent. $ astyle -a -p -T4 < vorher.cpp > nachher.cpp Nachfolgend derselbe Aufruf mit verketteten Optionen: $ astyle -apt4 < vorher.cpp > nachher.cpp Optionen können in der Lang- und Kurzform selbstverständlich auch gemischt verwendet werden: 7

12 $ astyle --brackets=attach --pad=oper -T4 < vorher.cpp > nachher.cpp Zuletzt noch eine Version, die nicht die Umleitung der Ein-/Ausgabe (also < und > ) der jeweils verwendeten Shell benutzt, sondern den Namen des Quellprogramms direkt als Argument an astyle übergibt: $ astyle -a -p -T4 quelltext.cpp Wie bereits in Abschnitt 3 beschrieben, wird bei dieser Form des Aufrufs die Originaldatei quelltext.cpp in quelltext.cpp.orig umbenannt und die Veränderungen finden sich in der neu erzeugten Datei quelltext.cpp. 5 Konfiguration Damit häufig verwendete Optionen nicht jedesmal erneut angegeben werden müssen, bietet astyle die Möglichkeit, das Laufzeitverhalten durch eine Konfigurationsdatei an die jeweiligen Bedürfnisse des Benutzers anzupassen. 5.1 Ablauf astyle sucht im Homeverzeichnis nach der Konfigurationsdatei mit dem Namen /.astylerc. Diese Datei wird nicht automatisch angelegt, sondern muss manuell erstellt werden. Will man eine andere Datei verwenden, kann man den Dateinamen in der Umgebungsvariablen ARTISTIC STYLE OPTIONS festlegen. Ist diese Variable gesetzt, wird die Datei /.astylerc nicht mehr verarbeitet, selbst wenn die Umgebungsvariable einen ungültigen Dateinamen enthält! Im letzten Schritt werden die Optionen ausgewertet, die astyle beim Aufruf von der Kommandozeile mitgegeben wurden. Diese haben die höchste Priorität und werden verwendet, falls es zu Konflikten mit den in der Konfigurationsdatei angegebenen Optionen kommt. Ist etwa die Option -a in der Konfigurationsdatei angegeben und es wird in der Kommandozeile zusätzlich die Option -b verwendet, dann wird die Option -b von astyle benutzt. 5.2 Dateiformat Optionen können in der Lang- oder Kurzform angegeben werden. Die Präfixe - bzw. -- sind dabei optional. Es können mehrere Optionen in einer Zeile stehen, diese müssen dann jedoch durch ein Leerzeichen voneinander getrennt sein. Verkettungen der Optionskürzel wie beim Aufruf in der Shell sind hier also nicht möglich. Kommentare werden mit dem Rauten-Zeichen # eingeleitet und erstrecken sich bis zum Ende der Zeile. Kommentare werden von astyle ignoriert. 8

13 5.3 Beispiele Nachfolgend einige zulässige Beispiele für den Aufbau der Konfigurationsdatei: -a -p -T # Optionskuerzel in einer Zeile a p T # Ohne Praefix - a # Optionskuerzel verteilt ueber drei Zeilen -p #. T #. --style=gnu # "GNU Coding Style" mit Praefix -- style=gnu -p # "GNU Coding Style" und Leerzeichen um Operatoren Literatur [1] Home Page von astyle, [2] GPL, license [3] Artistic License, [4] Patch, id=2319&func=browse, Abruf am