de.frame4j

Class SVNkeys

java.lang.Object

de.frame4j.util.App

de.frame4j.SVNkeys

All Implemented Interfaces:

FileVisitor, AttrSettable, TextHelper.MessageComponents, AppMBean, ComVar, UIInfo, ActionListener, EventListener

@MinDoc(copyright="Copyright 2003 - 2013, 2016, 2017  A. Weinert",
        author="Albrecht Weinert",
        version="V.50",
        lastModified="4.06.2021",
        usage="start as Java application (-? for help)",
        purpose="refine and beautify text files got from SVN")
public class SVNkeys
extends App
implements FileVisitor

Beautify text files got from Subversion / SVN (or CVS) .

This application beautifies / modifies the text contained in Subversion (SVN) or also the outdated Concurrent Versioning System (CVS) keywords. This is usually done prior to building or deployment. Optionally the "keyword brace" can be removed. Using this tool is the — better — substitute for export, -kv or similar.

The task can be done in one step for a whole project as this application visits all specified text files starting from a base directory. Sub-directories are visited recursively too as default (use option -nr if no descend to sub-directories is wanted).

The standard setting for files to be visited is: all files of types
conf;c;h;css;htaccess;java;html;properties;bat;xml;txt;asm;cmd;htm;xsl;xsd;dtd;ent;cpp;php;ini
Those are the usual source and control text files of a (Java-, XML-, ..) software or web publishing project.

All the standard settings, like file, directory and text criteria etc. described here, can be modified by start parameters or by extra .properties files supplied in very great detail and freedom.

In every visited text file some replacements may be done; in the standard setting they are:

• replacing tabs by three spaces
• replacing dollar bracketed $CVSkeyword$ or $CVSkeyword: value$, namely
  • "Date" by "03.11.2009", that is by the actual date or by the date of last file modification in the form defined by "j.m.Y" (see TimeHelper.format(CharSequence, java.time.ZonedDateTime))
  • "Date: utcDate" by the reformatted date relates to local time zone in the form defined by "j.m.Y" (see TimeHelper.format(CharSequence, java.time.ZonedDateTime))
    Remark: CVS and cvsNT use UTC without specifying it while SVN explicitly specifies the zone offset; both works here.
  • "Author" by "A. Weinert"
    Remark: thats changeable, of course, see above and SVNkeys.properties
  • "Author: name" by "name"
  • "Name" by "last revision (HEAD)"
  • "Name: release" by "release"
  • "Revision" by "new"
  • "Revision: revision" by "revision"
  • "Rev" and "LastChangedRevision" are treated like Revision.
  • "LastChangedBy" by "(unknown)"
  • "LastChangedBy: name" by "name"
  • "Id" by "(this file)"
  • "Id: pigsty" by "pigsty"
  • "HeadURL" by "" (nothing)
  • "HeadURL: serverURL" by "serverURL"
  • "Branch" by "" (nothing)
  • "Branch: hare" by "hare"
  • "URL"is treated like HeadURL.

The first point fights a bug of some (Eclipse-Java-) editors using tabulators instead of spaces for indentation against being ordered otherwise. The other points overcome faults and the deformednes of the CVS and SVN checkout and export functions (especially the -kv option bringing just anger and tears).
Just for clarification: This application renders export, -kv and all else superfluous. Just work on checked out files (or a copy thereof) before preparing (compiling, documenting, building) the project for deployment.

In the procedure of removing the dollar-keyword-braces the now got value may undergo another non case sensitive compare and replace. This feature is normally used to replace log-in names set in by SVN by the person's name, as "FB3-MEVA\weinert" by "Albrecht Weinert" for example. This substitutions are freely configurable.

In another mode of operation is the "draining" of CVS-keys or Subversion-keywords, that is replacing $CVSkeyword: value$ by just $CVSkeyword$.
Hint: This "draining" is more useful for SVN. Due to a bug, SVN fails to modify on some content between colon (:) and closing dollar ($).

Hint 2: To this application belongs (as integral part) a .properties file, named SVNkeys.properties. It resides in the actual directory, in jre/lib or (best) in the .jar file containing this application.

This file SVNkeys.properties is part of the documentation.

Hint 3: All public object variables and setters are properties steering the operation mode of SVNkeys. They are set automatically by start arguments and .properties file(s) by de.frame4j.util.Prop (see setFields()).

Hint 4: With CVS (and cvsNT) you just have the so called "keyword substitution" always. You have to kill it explicitly sometimes for non text files. With Subversion this nice feature is off by default and must be switched on for every single file, like in example:
svn propset svn:keywords "Date Revision Author Id HeadURL" *.java
Stupidly it's really for the single file(s) not for the file type, as the example might suggest. Bringing in a new .java file you must repeat the procedure for it!
This application SVNkeys gets the types of text files to modify by the property FileCriteria.types, the default see above or in SVNkeys.properties.

Hint 5: This application is part of the framework Frame4J. Frame4J's building and deploying scripts also use this application before compiling or doing the (javaDoc) documentation. That makes Frame4J "self beautifying" (and involved "self building").
So the text you just see is (also) edited by SVNkeys or SVNkeysFilter. For sake of compactness the actual SVN keywords of this source follow. If you don't see the something like
$Date: 2013-01-12 23:47:57 +0100 (Sa, 12 Jan 2013) $
SVNkeys did work:

• Revision: "50"
• Date: "4.06.2021"
• Author: "A. Weinert"

Hint 6: This application uses 4 to 8 parallel threads / tasks to work on the the files. The beautifying of a single file is totally independent of all others and in project with hundreds of files the gain is significant compared to single thread sequential work.

© Copyright 2003, 2009, 2013 Albrecht Weinert

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	SVNkeys.MyTask The single task for a file visited.

Nested classes/interfaces inherited from interface de.frame4j.io.FileVisitor

FileVisitor.Ask, FileVisitor.AskConsImpl, FileVisitor.AskGrafImpl

Nested classes/interfaces inherited from interface de.frame4j.util.ComVar

ComVar.Impl

Field Summary

Fields

Modifier and Type	Field and Description
String	clBrace Closing brace for keywords.
String	dateDefault Substitute for empty $Date$.
boolean	dateDefaultToMod For empty $Date$ insert the file's modification date.
boolean	dateDefaultToNow For empty $Date$ insert current time.
String	dateFormat Re-format the date; format String.
String	dateKey Keyword for Date.
String	directory Start directory.
String	fieldLengthMarker Field end marker keywords.
String	filModEnc Encoding of files to be modified.
String	ignFilesWith Text to mark excluded file.
boolean	ignoreKeyCase Ignore case for keywords.
boolean	keepLastModif Keep the file modification date, also with replacements.
int	maxBraceDist Maximal distance for keyword braces.
String	opBrace Opening brace for keywords.
boolean	recursion Visit (recursively) also sub-directories.
boolean	reformatDate Re-format the date.
boolean	removeBraces Remove the keyword braces.
boolean	removeContent Remove the keyword content.
String	setOperator Set operator for keywords.
boolean	tabReplace Replace Tabs by spaces.
int	tabWidth Replace tabs by that number of spaces.

Fields inherited from class de.frame4j.util.App

ano, appBase, appIO, appStartTime, appStartTimeMS, args, argsOrig, bgColor, err, fullClassName, help, icon, log, mainThread, myClass, myFrame, name, out, outMode, packName, prop, retCode, runFlag, shortClassName, title, verbose, verbosity

Fields inherited from interface de.frame4j.util.ComVar

AUTHOR, BLANK_STRING, cons, CONSOL_ENCODING, COPYRIGHT, D, D_NaN, D_NegInf, D_PosInf, EMPTY_INT_A, EMPTY_STRING, FILE_ENCODING, FRW_CLLD, FS, FSS, H, hasCons, HOST_IP, HOST_IPv4, HOST_NAME, INIT_ERROR, JAR_ENCODING, JH, JOB_DONE_OK, JRL, LOG_OUT_ERROR, M, MAIN_THREAD_EXC, NO_BYTES, NO_CLASSES, NO_DOUBLES, NO_OBJECTS, NO_PARS_ERROR, NO_STRINGS, NOT_WINDOWS, ON_PI, ONE_DAY, ONE_HOUR, ONE_LEAP_YEAR, ONE_MINUTE, ONE_SECOND, ONE_WEEK, ONE_YEAR, OS, PROG_NAME, PROG_SHORT, PS, RUNTIME, S, SHY, UD, UL, UL_UR_da, UR

Fields inherited from interface de.frame4j.net.AttrSettable

ILLEGAL_TYPE, ILLEGAL_VALUE, NO_ATTRIBUTE, NO_KNOWN_ATTRIBUTE, NO_VALUE, OK, retVtext

Method Summary

Modifier and Type	Method and Description
int	doIt() Working method of SVNkeys.
static void	main(String[] args) Start method of SVNkeys.
int	visit(File dD) File visitor.

Methods inherited from class de.frame4j.util.App

actionPerformed, allowNoPropertiesFile, clientOrder, condHelpLog, connect, errMeld, errMeld, errorExit, errorExit, errorText, extraPropertiesFile, formMessage, formMessage, formMessage, getAbout, getAboutText, getActTime, getAppLogger, getAppStartTime, getArgs, getAuthor, getCopyright, getDbLogger, getExecTimeMs, getExecTimeMsL, getExecTimeString, getHelp, getHelpText, getIcon, getLanguage, getLogHandler, getMessageComponent, getMessageComponentsLength, getMyFrame, getName, getNameWithVersDate, getOutMode, getProp, getPurpose, getStartTime, getStateString, getTheCloser, getTitle, getUsage, getVerbose, getVerbosity, getVersDate, go, go, go, haveIcon, isDebug, isHelp, isHelpLog, isNormal, isRunFlag, isSilent, isTest, isVerbose, logVerbose, logVerbose, makeStatusTextEnd, makeStatusTextStart, messageFormat, normalExit, parsePartial, performeAction, queueAction, regAsStdMBean, repExc, setAboutText, setAttribute, setAttribute, setAuthor, setBgColor, setCodePages, setCopyright, setHelp, setLogOut2, setName, setOutMode, setOutMode, setPurpose, setTitle, setUsage, setVerbose, setVerbose, setVerbosity, setVerbosity, setVersDate, stop, threeLineEndMsg, toString, twoLineEndMsg, twoLineStartMsg, valueLang, valueLang, wakeMainThread

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface de.frame4j.net.AttrSettable

retVtext

Field Detail

filModEnc

public String filModEnc

Encoding of files to be modified.

The name of the real/current encoding of the text files to be modified. It must fit and is not changed.

No explicit setting (null) defaults to the platform encoding.

Since:

January 2017

recursion

public boolean recursion

Visit (recursively) also sub-directories.

If true all matching files are worked on in sub-directories, also.

default: false

tabReplace

public boolean tabReplace

Replace Tabs by spaces.

default: true

See Also:

tabWidth

tabWidth

public int tabWidth

Replace tabs by that number of spaces.

allowed: 2..12
default: 3

See Also:

tabReplace

opBrace

public String opBrace

Opening brace for keywords.

default: (SVN / Subversion standard) is Dollar $

clBrace

public String clBrace

Closing brace for keywords.

default: (SVN / Subversion standard) is Dollar $

setOperator

public String setOperator

Set operator for keywords.

default: (SVN / Subversion standard) is colon :

maxBraceDist

public int maxBraceDist

Maximal distance for keyword braces.

allowed 24 .. 300
other values: no limit (not recommended)
default = 150 (seems high, but #36;HeadURL: .... #36; can get longer.

fieldLengthMarker

public String fieldLengthMarker

Field end marker keywords.

default: Subversion only uses sharp (#)
set to blank or 0 for no effect

removeBraces

public boolean removeBraces

Remove the keyword braces.

Removing the ugly Dollars plus keyword plus colon (:) is the absolute minimal cosmetic prior to deployment.

default: true

removeContent

public boolean removeContent

Remove the keyword content.

default: false

ignoreKeyCase

public boolean ignoreKeyCase

Ignore case for keywords.

Note: SVN / Subversion and CVS are both case sensitive (Date != date).

default: false = case sensitive keywords

dateKey

public String dateKey

Keyword for Date.

Date and time of date are subject to optional reformatting due to the usual ugliness not fit for customers and / or documentation.

default: Date

See Also:

dateFormat

reformatDate

public boolean reformatDate

Re-format the date.

default: true

See Also:

dateKey

dateFormat

public String dateFormat

Re-format the date; format String.

default: j.m.Y

The format characters are described at TimeHelper.format(CharSequence, java.time.ZonedDateTime).

See Also:

dateKey

dateDefaultToNow

public boolean dateDefaultToNow

For empty $Date$ insert current time.

If true the replacement for an empty date is the current time, of course formatted with dateFormat. If false just dateDefault will be inserted instead.

default: false

See Also:

dateDefaultToMod

dateDefaultToMod

public boolean dateDefaultToMod

For empty $Date$ insert the file's modification date.

If true the replacement for an empty date is the file modification date, of course formatted with dateFormat. This setting has priority over dateDefaultToNow and dateDefault.

This feature gives a sensible date also for files not under version control (by just inserting $Date$.

Hint: Due to a bug Subversion will usually not work on $Date$. It needs $Date: $ or $Date: rhubarb $ including the trailing blank!

default: true

See Also:

keepLastModif

dateDefault

public String dateDefault

Substitute for empty $Date$.

default: (no date)

keepLastModif

public boolean keepLastModif

Keep the file modification date, also with replacements.

If true the last file modification date will be kept, even if this applications made "keyword replacements". The file date then still mirrors the date of the last content modification. That is CVS's point of view. Subversion's big bug is not to preserve modification dates but puts the dates of commit and checkout instead. No matter what, the date of beautifying by this tool normally will not be of interest.

default: true (i.e. do not consider beautifying as modification)

ignFilesWith

public String ignFilesWith

Text to mark excluded file.

If ignFilesWith is neither null nor empty, files that contain that text (regarding case) will not be worked on, even if matching all other file criteria.

Hereby one can exclude files from processing by setting a significant marker text (usually in an comment or hidden text).

default: null (no textual exclude criterion)

See Also:

FuR

directory

public String directory

Start directory.

default: . (actual directory)

Method Detail

main

public static void main(String[] args)

Start method of SVNkeys.

An exit code (ERRORLEVEL) 0 signalises a run without trouble.

Problems lead to >0. (< 0 not used for sake of Windows.)

exit code 0: OK.
exit code 1: completely run through, but I/O problems with some files or directories visited.
exit code>1: parameter or other starting problems; nothing done.

Parameters:

args - the application's start parameter

visit

public int visit(File dD)

File visitor.

Processing all text substitutions on the visited file.

Specified by:

visit in interface FileVisitor

Parameters:

dD - the file or directory to act upon or to determine a filter / function response about

Returns:

the response; mostly irrelevant under (pure) action / procedural aspects

See Also:

doUpDate()

doIt

public int doIt()

Working method of SVNkeys.

Specified by:

doIt in class App

Returns:

the exit code; 0 means OK

See Also:

Prop, App.go(String[]), App.go(String[], String, CharSequence), App.mainThread