Zz.unkrig.de: Difference between revisions

From unkrig.de
Jump to navigation Jump to search
 
(45 intermediate revisions by the same user not shown)
Line 1: Line 1:
A set of command-line tools that handle not only directories and files, but also ZIP and GZIP files, and even nested ZIP files.
<meta name="keywords" content="java, compressed, archive, zip, zipped, nested"></meta>
<meta name="description" content="A set of command-line tools that handle not only directories and files, but also archive and compressed files, and even nested archive files"></meta>
A set of command-line tools that handle not only directories and files, but also archive and compressed files, and even nested archive files. They can even disassemble Java <code>.class</code> files on-the fly and operate on the disassembly.


== Description ==
== Tool Documentation ==


=== zzdiff ===
=== zzdiff ===


Computes the differences between files, directory trees, ZIP file entries, GZIPped files and prints them in various formats; widely compatible with the UNIX&trade; DIFF command line utility.
Computes the differences between files, directory trees, archive file entries, compressed files and prints them in various formats; widely compatible with the UNIX&trade; DIFF command line utility.


==== zzdiff Command Line Tool ====
Read the [http://zz.unkrig.de/maindoc/zz-diff/Main.main(String%5b%5d).html command line tool documentation].
Usage:
  java de.unkrig.zz.diff.Main -help
  java de.unkrig.zz.diff.Main [ <option> ] ... <file1> <file2>
Show contents differences between <file1> and <file2> in DIFF format.
  java de.unkrig.zz.diff.Main [ <option> ] ... <dir1> <dir2>
Show which files were added (missing in <dir1>) or deleted (missing in <dir2>)
and their subdirectories, and any contents differences for the remaining files
in DIFF format.
Valid options are:
  File selection:
    -exclude <glob>
    -x <glob>        Ignore matching files, e.g. 'dir/zipfile!dir/file' or
                      '**/file'. '<exc>' is a 'combined wildcard pattern', see
                      below.
    -zip
    -z                Look into ZIP format files instead of comparing the plain
                      file
    -nested-zip
    -zz              Recurse into ZIP format files instead of comparing the plain
                      file
    -name-equivalence <regex>
    -ne <regex>      Files with different names map iff their names match the
                      <regex> and all capturing groups are equal
  Contents processing:
    -disassemble
    -da              Disassemble .class files
      -da-no-lines    Don't display lines debug info
      -da-no-vars    Don't display local variables debug info
    -line-equivalence <name> <regex>
                      Lines in files <name> that contain <regex> and all
                      capturing groups are equal are regarded as equal
    -ignore <name> <regex>
    -I <name> <regex> Ignore differences in files <name> where all lines
                      (deleted, changed or added) match the given <regex>
    -ignore-whitespace
    -w                Ignore whitespace differences
    -encoding <enc>  Encoding of the files being compared (defaults to 'UTF-8')
  Output generation:
    -out <file>      Write DIFF to <file> instead of STDOUT
    -quiet
    -q                Report only which files were added, deleted or changed
    -context
    -c                Output 'context diff' format with three lines of context
    -Context <N>
    -C <N>            Output 'context diff' format with <N> lines of context
    -unified
    -u                Output 'unified diff' format with three lines of context
    -Unified <N>
    -U <N>            Output 'unified diff' format with <N> lines of context
  Logging:
    -nowarn          Suppress all messages except errors
    -verbose          Log verbose messages
    -debug            Log verbose and debug messages
    -log <level>:<logger>:<handler>:<formatter>
                      Add logging at level FINE on the root logger to STDERR,
                      using the FormatFormatter and MESSAGE_AND_EXCEPTION
                      format, or the given arguments which are all optional.
A 'combined wildcard pattern' can have the form
    *~*.c~*.h+foo.c
, which means 'foo.c plus all that don't end with .c or .h'


==== <zzdiff> Ant Task ====
Read the [http://zz.unkrig.de/antdoc/index.html?tasks/zzdiff.html ANT task documentation].
<taskdef resource="de/unkrig/zz/antlib.xml" classpath="path/to/de.unkrig.zz.jar" />
...
<zzdiff ...>


===== Attributes =====
=== zzfind ===
;ignoreWhitespace: Ignore whitespace differences
 
;absentFileMode: REPORT_AS_ADDED_OR_DELETED (the default): Report about added and deleted files and directories<br>COMPARE_ADDED_AND_DELETED_WITH_EMPTY: Compare added or deleted file with the empty document; compare added and deleted directories with the empty directory<br>COMPARE_ADDED_WITH_EMPTY: Compare added files with the empty document; compare added directories with the empty directory; report about deleted files and directories
Finds files in directory trees and entries in archive files by various criteria; widely compatible with the UNIX&trade; FIND command line utility.
;zip: Look into ZIP format files instead of comparing the plain file
 
;nestedZip: Recurse into ZIP format files instead of comparing the plain file
Read the [http://zz.unkrig.de/maindoc/zz-find/Main.main(String%5b%5d).html command line tool documentation] (or the [http://zz.unkrig.de/maindoc/zz-find/Main.main(String%5b%5d).txt plain text version]).
;disassembleClassFiles: Disassemble .class files
 
;disassembleClassFilesButHideLines: Don't display lines debug info
Read the [http://zz.unkrig.de/antdoc/index.html?tasks/zzfind.html ANT task documentation].
;disassembleClassFilesButHideVars: Don't display local variables debug info
;encoding: Encoding of the files being compared (defaults to default platform encoding)
;diffMode: QUIET: Report only which files were added, deleted or changed, NORMAL (the default): Output 'normal diff' format, CONTEXT: Output 'context diff' format, UNIFIED: Output 'unified diff' format
;contextSize: Amount of 'context' which is reported with each difference; default is +- three lines (only relevant for 'context diff' and 'unified diff' formats)
;out: Write DIFF to the named file instead of STDOUT
;file1
;file2: The two files or the two directories to compare
;property (optional): Set the named property to 'true' iff there are no differences between ''file1'' and ''file2'' (particularly useful with 'diffMode=QUIET')


===== Subelements =====
=== zzgrep ===
;<exclude name="..." />: Ignore matching files, e.g. 'dir/zipfile!dir/file' or '**/file'. 'name' is a 'combined wildcard pattern', see below.
;<equivalentName nameRegex="..." />: Files with different names map iff their names match the 'nameRegex' and all capturing groups are equal
;<equivalentLine name="..." regex="..." />: Lines in files 'name' that contain 'regex' and all capturing groups are equal are regarded as equal
;<ignore name="..." regex="..." />: Ignore differences in files 'name' where all lines (deleted, changed or added) match the given 'regex'


=== zzfind ===
Finds lines in files in directory trees and in entries in archive files by regular expressions; widely compatible with the UNIX&trade; GREP command line utility.
 
Read the [http://zz.unkrig.de/maindoc/zz-grep/Main.main(String%5b%5d).html command line tool documentation].


Finds files in directory trees and entries in ZIP files by various criteria; widely compatible with the UNIX&trade; FIND command line utility.
Read the [http://zz.unkrig.de/antdoc/index.html?tasks/zzgrep.html ANT task documentation].


==== zzfind Command Line Tool ====
=== zzpack ===
A FIND utility that can recurse into nested files in ZIP format
Usage:
  java de.unkrig.zz.find.Main [ <option> ... ] <dir> ... [ <expression> ]
Apply <expression> to all files in <dir>
  java de.unkrig.zz.find.Main [ <option> ... ] -z <file-or-dir> ... [ <expression> ]
Apply <expression> to all files and entries in <file-or-dir>
Valid <option>s are:
  -help
  -z              Look into ZIP files
  -zz            Look into ZIP files and nested ZIP files
  -encoding <enc> Contents encoding (only relevant for '-cat'), default is 'windows-1252'
  -nowarn        Suppress all messages except errors
  -quiet          Suppress normal output
  -verbose        Log verbose messages
  -debug          Log verbose and debug messages
  -log <level>:<logger>:<handler>:<formatter>:<format>
                  Add logging at level FINE on logger 'de.unkrig' to STDERR
                  using the FormatFormatter and SIMPLE format, or the given
                  arguments which are all optional.
<expression>s are either tests or actions. Both evaluate to a boolean value.
Valid tests are:
  -name <glob>    Name matches '<glob>' (see below).
  -path <glob>    The full path (e.g. 'dir/zipfile!dir/zipfile!dir/file' or
                  'dir/file') matches '<glob>' (see below).
  -type f        The file or zip entry is of 'file' type.
  -type d        The file is of 'directory' type (directory entries in ZIP
                  files are always ignored).
  <exp1> -a <exp2>
  <exp1> <exp2>  '<exp1>' and '<exp2>' are true.
  <exp1> -o <exp2>
                  '<exp1>' or '<exp2>' is true.
  -not <exp>
  ! <exp>        '<exp>' is false.
  ( <exp> )      '<exp>' is true.
Valid actions are:
  -print          Print file path and return true.
  -ls            Print file type, readablity, writability, size, modification
                  time and path, and return true.
  -exec <word>... ;
                  Execute '<word>...' as an external command; '{}' is
                  replaced with the current file's path (which may contain '!'
                  and would then NOT denote a physical file in the file system).
  -cat            Print file contents and return true.
If no action is given, then '-print' is implictly added.
Example <glob>s:
  dir/file.zip!dir/file  Entry 'dir/file' in ZIP file 'dir/file.zip'
  */x                    File 'x' in an immediate subdirectory
  **/x                  File 'x' in any subdirectory
  ***/x                  File 'x' in any subdirectory, or entry 'x' in any ZIP
                          file in any subdirectory
  a,dir/file.zip!dir/b  File 'a' and entry 'dir/b' in ZIP file 'dir/file.zip'
  ~*.c                  Files that don't end with '.c'
  ~*.c~*.h              Files that don't end with '.c' or '.h'
  ~*.c~*.h,foo.c        'foo.c' plus all files that don't end with '.c' or '.h'


==== <zzfind> Ant Task ====
Creates an archive file from a set of given files, directories, and archive entries.
<taskdef resource="de/unkrig/zz/antlib.xml" classpath="path/to/de.unkrig.zz.jar" />
...
<zzfind ... />


===== Attributes =====
Read the [http://zz.unkrig.de/maindoc/zz-pack/Main.main(String%5b%5d).html command line tool documentation].
;zip="true": Look into ZIP files (default is FALSE)
;nestedZip="true": Look into ZIP files and nested ZIP files (default is FALSE)


===== Subelements =====
Read the [http://zz.unkrig.de/antdoc/index.html?tasks/zzpack.html ANT task documentation].
;Resource collection (e.g. <dirset>): The set of files and/or directories to apply the tests and actions (see below) to. If more than one action or test is given, then these are implicitly and-connected.


Actions:
=== zzpatch ===
;<cat encoding="..." />: Copies the contents of the current file to a given string consumer and evaluates to TRUE.
;<exec command="..." />: Executes an external command; the special string '{}' within the command is replaced with the full path of the current file. Evaluates to TRUE iff the command exists with status code '0'.
;<ls />: Prints the file type ('d' or '-'), readablity ('r' or '-'), writability ('w' or '-'), size, modification time  and path and evaluates to TRUE.
;<print />: Prints the path of the current file to the given string consumer and evaluates to TRUE.


Tests:
Modifies the contents of files in directory trees and of entries in archive files by various criteria; widely compatible with the UNIX&trade; PATCH command line utility.
;<and>...</and>: Accepts a sequence of operand subelements; evaluates them in sequence until one evaluates to FALSE; evaluates to TRUE iff all operands evaluate to TRUE
;<or>...</or>: Accepts a sequence of operand subelements; evaluates them in sequence until one evaluates to TRUE; evaluates to FALSE iff all operands evaluate to FALSE
;<name value="..." />: Evaluates to TRUE iff the name of the current file matches the given glob.
;<path value="..." />: Evaluates to TRUE iff the path of the current file matches the given glob.
;<type value="..." />: Evaluates to TRUE iff the type of the current file matches the given value (FILE or DIR).
;<not>...</not>: Accepts exactly one operand subelement; evaluates to TRUE if the operand evaluates to FALSE and vice versa.


=== zzgrep ===
Read the [http://zz.unkrig.de/maindoc/zz-patch/Main.main(String%5b%5d).html command line tool documentation].
 
Read the [http://zz.unkrig.de/antdoc/index.html?tasks/zzpatch.html ANT task documentation].


Finds lines in files in directory trees and in entries in ZIP files by regular expressions; widely compatible with the UNIX&trade; GREP command line utility.
== Download and Installation ==


==== zzgrep Command Line Tool ====
=== Runnable JAR files ===
A GREP utility that can recurse into nested files in ZIP format
Usage:
  java de.unkrig.zz.grep.Main [ <option> ... ] <regex> [ <file-or-dir> ... ]
Reads all lines from STDIN or <file> or all files under <dir> and prints those
which contain <regex>.
Valid options are:
  -help
  -zip
  -z              Look into ZIP files.
  -nested-zip
  -zz            Look into ZIP files and nested ZIP files.
  -gzip          Look into GZIP files.
  -encoding <enc> Contents encoding, default is 'windows-1252'
  -q  -quiet      Suppress all normal output.
  -l  -list      Print only names of files containing matches.
  -i  -ignore-case
                  Ignore case distinctions.
  -v  -inverted  Select non-matching lines.
  -da            Disassemble .class files on-the-fly.
    -da-no-lines  Don't print line numbers in the disassembly.
    -da-no-vars  Don't print variable names in the disassembly.
  -include <glob> If given, then only entries that match <glob> are scanned.
  -exclude <glob> Entries that match <glob> and their subentries are NOT
                  scanned.
  -nowarn        Suppress all messages except errors
  -verbose        Log verbose messages
  -debug          Log verbose and debug messages
  -log <level>:<logger>:<handler>:<formatter>:<format>
                  Add logging at level FINE on logger 'de.unkrig' to STDERR
                  using the FormatFormatter and SIMPLE format, or the given
                  arguments which are all optional.
<file-or-dir>: Instead of STDIN, read from <file>, or from all files under <dir>
Example <glob>s:
  dir/file.zip!dir/file  Entry 'dir/file' in ZIP file 'dir/file.zip'
  */x                    File 'x' in an immediate subdirectory
  **/x                  File 'x' in any subdirectory
  ***/x                  File 'x' in any subdirectory, or entry 'x' in any ZIP
                          file in any subdirectory
  a,dir/file.zip!dir/b  File 'a' and entry 'dir/b' in ZIP file 'dir/file.zip'
  ~*.c                  Files that don't end with '.c'
  ~*.c~*.h              Files that don't end with '.c' or '.h'
  ~*.c~*.h,foo.c        'foo.c' plus all files that don't end with '.c' or '.h'
Exit status is 0 if any line was selected, 1 otherwise; if any error occurs,
the exit status is 2.


==== <zzgrep> Ant Task ====
<html>
<taskdef resource="de/unkrig/zz/antlib.xml" classpath="path/to/de.unkrig.zz.jar" />
  <form method="get" action="https://repository.sonatype.org/service/local/artifact/maven/redirect">
...
    <input type="hidden" name="r" value="central-proxy" />
<zzgrep ...>...</zzgrep>
    <input type="hidden" name="g" value="de.unkrig.zz" />
    <input type="hidden" name="v" value="LATEST" />
    <input type="hidden" name="c" value="jar-with-dependencies" />


===== Attributes =====
    Latest version of
;zip: Whether or not ZZGREP should look into ZIP files.
    <select name="a">
;nestedZip: Whether or not ZZGREP should look into ZIP files and nested ZIP files.
      <option>zz-diff</option>
;gzip: Whether or not ZZGREP should look auto-detect and gunzip GZIP files.
      <option>zz-find</option>
;encoding: Contents encoding, default is 'windows-1252'
      <option>zz-grep</option>
;operation: The operation that should be executed by ZZGREP: NORMAL (for each match, print the file name, a colon, a space and the matched line), LIST (for each match, print the file name), or QUIET (do not print the matches). The default is NORMAL.
      <option>zz-pack</option>
;caseInsensitive: Whether the regular expression should be applied case-insensitively.
      <option>zz-patch</option>
;inverted: Whether matching lines should be treated as non-matching, and vice versa.
    </select>
;disassembleClassFiles: Whether to disassemble Java&trade; class files on-the-fly before matching its contents.
    <input type="submit" value="DOWNLOAD" />
;disassembleClassFilesButHideLines: Whether to hide source line numbers in the Java&trade; class file disassembly.
  </form>
;disassembleClassFilesButHideVars: Whether to local variable names in the Java&trade; class file disassembly.
</html>
;regex: The regular expression to match each line against.


===== Subelements =====
=== MS WINDOWS executables ===
;<exclude pattern="..." />: All files who's names match the given glob are excluded, even if they were previously included.
;<include pattern="..." />: All files who's names match the given glob are included, even if they were previously excluded through <exclude>.
;Ressource collection, e.g. <fileset>: File and directory tree which ZZGREP will include in its search.


=== zzpatch ===
<html>
  <form method="get" action="https://repository.sonatype.org/service/local/artifact/maven/redirect">
    <input type="hidden" name="r" value="central-proxy" />
    <input type="hidden" name="g" value="de.unkrig.zz" />
    <input type="hidden" name="v" value="LATEST" />
    <input type="hidden" name="p" value="exe" />


Modifies the contents of files in directory trees and of entries in ZIP files by various criteria; widely compatible with the UNIX&trade; PATH command line utility.
    Latest version of
    <select name="a">
      <option>zz-diff</option>
      <option>zz-find</option>
      <option>zz-grep</option>
      <option>zz-pack</option>
      <option>zz-patch</option>
    </select>
    <input type="submit" value="DOWNLOAD" />
  </form>
</html>


==== zzpatch Command Line Tool ====
Notice: These executables require an installed JRE; at least version 1.6. They will complain if they cannot find a suitable JRE, and give advice how to get things running.
Usage:
    java de.unkrig.zz.patch.Main [ <option> ... ] <file-or-dir>
Transforms <file-or-dir> in-place.
    java de.unkrig.zz.patch.Main [ <option> ... ] <file-or-dir> <new-file-or-dir>
Transforms <file-or-dir> into <new-file-or-dir>.
    java de.unkrig.zz.patch.Main [ <option> ... ] <file-or-dir> ... <out-dir>
Transforms <file-or-dir> and creates the output in <out-dir>.
Valid options are:
  -help      Shows this text.
  -keep      If existing files were overwritten, keep copies of the originals.
  -update <glob> <update-file>
              Replace the contents of files/ZIP entries that match <glob> (see
              below) with that of <update-file>.
  -substitute <glob> <regex> <replacement>
              Substitute occurrences of <regex> in files/zip entries that
              match <glob> (see below) with <replacement>.
  -patch <glob> <patch-file>
              Apply <patch-file> to all files/ZIP entries that match <glob>
              (see below). <patch-file> can be in traditional, context or
              unified diff format.
  -remove <glob>
              Remove all in files/ZIP entries that match <glob> (see below).
  -rename <glob>
              Rename out files/ZIP entries according to <glob> (see below), e.g.
              '(*).c=$1.c.orig'. Multiple '-rename' options are applied in the
              given order.
  -add <glob> <name> <contents-file>
              To all directories/ZIP format files that match <glob>, add a
              member/entry <name>, and fill it from <contents-file>.
  -z
  -zip        Look into ZIP files.
  -nested-zip
  -zz        Look recursively into ZIP files.
  -gzip      Look into GZIP files.
  -input-encoding <enc>
  -output-encoding <enc>
              Encoding of input files and output files (only relevant for
              '-substitute' and '-patch'); default is 'windows-1252'
  -patch-file-encoding <enc>
              Encoding of patch files (only relevant for '-patch'); default is
              'windows-1252'


  -nowarn    Suppress all messages except errors
=== APACHE ANT libraries ===
  -quiet      Suppress normal output
  -verbose    Log verbose messages
  -debug      Log verbose and debug messages
  -log <level>:<logger>:<handler>:<formatter>:<format>
              Add logging at level FINE on logger 'de.unkrig' to STDERR using
              the FormatFormatter and SIMPLE format, or the given arguments
              which are all optional.
Example <glob>s:
  dir/file.zip!dir/file  Entry 'dir/file' in ZIP file 'dir/file.zip'
  */x                    File 'x' in an immediate subdirectory
  **/x                  File 'x' in any subdirectory
  ***/x                  File 'x' in any subdirectory, or entry 'x' in any ZIP
                          file in any subdirectory
  a,dir/file.zip!dir/b  File 'a' and entry 'dir/b' in ZIP file 'dir/file.zip'
  ~*.c                  Files that don't end with '.c'
  ~*.c~*.h              Files that don't end with '.c' or '.h'
  ~*.c~*.h,foo.c        'foo.c' plus all files that don't end with '.c' or '.h'


==== <zzpatch> Ant Task ====
<html>
<taskdef resource="de/unkrig/zz/antlib.xml" classpath="path/to/de.unkrig.zz.jar" />
  <form method="get" action="https://repository.sonatype.org/service/local/artifact/maven/redirect">
...
    <input type="hidden" name="r" value="central-proxy" />
<zzpatch ...>
    <input type="hidden" name="g" value="de.unkrig.zz" />
    <input type="hidden" name="v" value="LATEST" />
    <input type="hidden" name="c" value="jar-with-dependencies" />


===== Attributes =====
    Latest version of
;keepOriginals="''boolean''": Whether to keep backup copies of files/entries that are modified or removed. Default is false.
    <select name="a">
;out="''file''": If the value is an existing directory, then all input files are transformed into new files in that directory. Otherwise exactly one input file must be specified, and the input file is transformed into the named file. If this attribute is not set, then all input files are transformed in-place.
      <option value="zz-all">All-in-one</option>
;zip="''boolean''": If false, then files in ZIP format are processed like all other regular files. If true, then the transformations are applied to the entries of ZIP format files, rather than to the ZIP file.
      <option>zz-diff</option>
;nestedZip="''boolean''": If false, then files in ZIP format are processed like all other regular files. If true, then the transformations are applied to the entries of ZIP format files (even nested entries), rather than to the ZIP file.
      <option>zz-find</option>
;gzip="''boolean''": If false, then files in GZIP format are processed like all other regular files. If true, then the transformations are applied to the entries of GZIP format files, rather than to the GZIP file.
      <option>zz-grep</option>
;file="''file''": Another file that will be patched.
      <option>zz-pack</option>
;dir="''dir''": Another directory tree that will be patched.
      <option>zz-patch</option>
    </select>
    <input type="submit" value="DOWNLOAD" />
  </form>
</html>


===== Subelements =====
To use the ANT types, insert one of the following lines in your build script:


;Resource collection (e.g. <code><fileset></code>, <code><dirset></code>)
  <taskdef resource="de/unkrig/zz/zz-diff.xml"  classpath="path/to/zz-diff-x.y.z-jar-with-dependencies.jar"  />
:Files and directory trees that will be patched.
  <taskdef resource="de/unkrig/zz/zz-find.xml"  classpath="path/to/zz-find-x.y.z-jar-with-dependencies.jar"  />
  <taskdef resource="de/unkrig/zz/zz-grep.xml"  classpath="path/to/zz-grep-x.y.z-jar-with-dependencies.jar"  />
  <taskdef resource="de/unkrig/zz/zz-pack.xml"  classpath="path/to/zz-pack-x.y.z-jar-with-dependencies.jar"  />
  <taskdef resource="de/unkrig/zz/zz-patch.xml" classpath="path/to/zz-patch-x.y.z-jar-with-dependencies.jar" />


;<code><update name="''glob''" updateFile="''file''" /></code>
If you use more than one of the tools in your build script, it is more efficient to use the "all-in-one" JAR file:
:The contents of files/entries that match <code>name="''glob''"</code> will be replaced with the contents of the <code>updateFile="''file''"</code>.


;<code><substitute name="''glob''" inputEncoding="''enc''" outputEncoding="''enc''" regex="''regex''" replacement="''replacement''" /></code>
  <taskdef resource="de/unkrig/zz/zz-all.xml" classpath="path/to/zz-all-x.y.z-jar-with-dependencies.jar" />
:Replaces all occurrences of <code>regex="''regex''"</code> with <code>replacement="''...''"</code> in files/entries that match <code>name="''glob''"</code>. Alternatively, regex and replacement can be configured with <code><regex></code> and <code><replacement></code> ''subelements''; the major advantage of subelements is that they can contain <code><![CDATA[...]]></code> sections where you don't have to SGML-escape special characters.
:With the [http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html#MULTILINE MULTILINE] option enabled (by including "<code>(?m)</code>" in the regex), you are not limited to line-wise pattern matching, but be careful with using greedy quantifiers, because these may require that the entire contents of each file needs to be loaded into memory.


;<code><patch name="''glob''" inputEncoding="''enc''" outputEncoding="''enc''" patchFile="''file''" patchFileEncoding="''enc''" /></code>
=== Java Library ===
:Files/entries that match <code>name="''glob''"</code> will be patched with the DIFF document in the <code>patchFile="''file''"</code>. Supported DIFF formats are 'traditional diff', 'context diff' and 'unified diff'.


;<code><remove name="''glob''" /></code>
The ZZ tools also have a public Java API that can be used from by any Java application. You can either download and use this JAR file, or, if you're using MAVEN, put in your "pom.xml" file:
:Files/entries that match <code>name="''glob''"</code> will be deleted/removed.


;<code><rename name="''glob''" /></code>
<dependency>
:Files/entries that match <code>name="''glob''"</code> will be renamed. The glob must be in the 'replacement' format, as described [http://commons.unkrig.de/javadoc/de/unkrig/commons/text/pattern/Glob.html#REPLACEMENT" here].
    <groupId>de.unkrig.zz</groupId>
    <artifactId>zz-diff</artifactId> <!-- Or zz-find, zz-grep, zz-pack, zz-patch. -->
    <version>x.y.z</version>
</dependency>


== Resources ==
Here is the API documentation:


[https://svn.code.sf.net/p/loggifier/code/trunk/ Source code]
* [http://zz.unkrig.de/javadoc/zz-diff/ zz-diff API documentation]
* [http://zz.unkrig.de/javadoc/zz-find/ zz-find API documentation]
* [http://zz.unkrig.de/javadoc/zz-grep/ zz-grep API documentation]
* [http://zz.unkrig.de/javadoc/zz-pack/ zz-pack API documentation]
* [http://zz.unkrig.de/javadoc/zz-patch/ zz-patch API documentation]


[http://zz.unkrig.de/download/                  Binaries]
== Resources ==


[http://zz.unkrig.de/CHANGELOG.txt              Change log]
<html>
  <form method="get" action="https://repository.sonatype.org/service/local/artifact/maven/redirect">
    <input type="hidden" name="r" value="central-proxy" />
    <input type="hidden" name="g" value="de.unkrig.zz" />
    <input type="hidden" name="v" value="LATEST" />
    <input type="hidden" name="c" value="sources" />


[http://zz.unkrig.de/javadoc/                   JAVADOC]
    Source code is available on <a href="https://github.com/aunkrig/zz">GITHUB</a>,
    and also through MAVEN:
    <select name="a">
      <option>zz-diff</option>
      <option>zz-find</option>
      <option>zz-grep</option>
      <option>zz-pack</option>
      <option>zz-patch</option>
    </select>
    <input type="submit" value="DOWNLOAD" />
  </form>
</html>


These tools make heavy use of [http://commons.unkrig.de commons.unkrig.de].
The ZZ tools make heavy use of [http://commons.unkrig.de/ commons.unkrig.de].


== License ==
== License ==


ZZ.UNKRIG.DE is published under the "[[New BSD License]]".
ZZ.UNKRIG.DE is published under the "[[New BSD License]]".
== Change Log ==
; Changes in version 1.3.11-SNAPSHOT (not yet released):
:* -
; Changes in version 1.3.10, 2022-12-29:
:* Changed handling of "-" to ResourceProcessings.STDIN_URL.
:* ZZDIFF can now handle "-" (stdin) as one of its two inputs.
:* ZZPATCH: --substitute: Removed the concept of the "replacement mode", because the extended replacement syntax just implements the "literal" and "expression" replacement modes.
:* ZZPACK: Added the "--rename" feature.
:* ZZPATCH: Substitution: Replacement mode "REPLACEMENT_STRING" now supports "ext syntax", i.e. "${...}" embedded expressions.
:* ZZPATCH: ExitException message is now "Printers.info()"ed instead of "Printers.verbose()"ed.
:* ZZFIND: Greatly simplified the computation of the expression variables.
:* ZZFIND: Fixed an exception when finding in STDIN: STDIN does not have the properties "readable", "writable" and "executable".
:* ZZFIND: Class file version can now be accessed by "cf.javaVersion".
:* ZZFIND: MAINDOC: Documented the "archiveEntry" variable.
:* ZZGREP: Moved "Grep.lineCounter()" to "ConsumerUtil".
:* ZZGREP: Eliminated the 65536-characters-per-line limit -- finds and counts matches now also in very long lines.
:* ZZPATCH: Added the "--assert-count" condition for updates/substitution replacements/patch hunks/removals/renamings/additions.
:* ZZFIND: Learned that the various ZIP archive libraries return random values for "ZipEntry.getMethod()" and "ZipEntry.getCrc()", thus made the test cases tolerant against these.
:* ZZFIND: Don't print a stack trace on predicate parse errors; only print the error message.
:* ZZPATCH: Added command line options for archive decryption: --7z-input-file-password --zip-input-file-password --password
:* ZZPATCH: Added command line options for archive compression and encryption: --zip-output-entry-compression-level --zip-output-file-password --zip-output-file-encryption-method
:* ZZFIND: Added short command line option for archive decryption: --password
:* ZZFIND: Added the "-version" command line option.
:* ZZGREP: Added command line options "--input-encoding" and "--output-encoding". (Previously, the output encoding was not configurable.)
:* ZZGREP: Fixed the printing of "--" separator lines between context-grep chunks.
:* ZZFIND: MAINDOC: Documented priority of operators.
:* ZZFIND: CatAction: Entries that have no input stream (e.g. directories or directory archive entries) are silently ignored, because that is practical: Otherwise, you'd always have to put "-type normal*" right before the "-cat" action.
:* ZZFIND: -copy action: Now ignore entries that have no input stream (e.g. directories or directory archive entries), because that is practical: Otherwise, you'd always have to put "-type normal*" right before the "-copy" action.
:* ZZFIND: -copy action: Attempt to restore each file's "last modification date", too.
:* ZZPATCH: Unified DIFF format: Some DIFF tools (namely GNU diffutils 3.5) put a TAB character (instead of a SPACE) between the file name and the date.
:* ZZFIND: Added "--toFile" option to "-disassemble".
:* ZZFIND: Added new variable "archiveEntry".
:* ZZFIND: Added action "-java-class-file".
:* ZZFIND: Added expression variable "compressionMethod" (for archive entries).
; Changes in version 1.3.9, 2020-11-06:
:* Updated jdisasm to 1.0.6.
:* Updated de.unkrig.commons to 1.2.15.
:* Removed the generation of the "...-antlib.jar" file, because "...-jar-with-dependencies.jar" can be used as an ANTLIB as well.
:* Fixed the file type in the output of -ls.
:* Added expression variables "readable", "writable" and "executable".
:* Adapted to an incompatible API change in "commons-file" (all content processing was augmented with an optional "lastModifiedDate" parameter).
:* Fixed an NPE that occurred with 7Z archive entries that have NO modification date set.
:* ZZFIND now compiles with JDK 1.8 (before it was 1.6).
:* Major refactoring: Replaced "Mappings properties" with "Map<String, Function<Object, Object>> properties.
:* Implemented the new expression variables "_map", "_keys" and "_values".
:* Context diff: The "hunk separator line" ("--") was missing.
:* Actions that read the contents of a document (-cat, -copy, -disassemble, -digest, -checksum) didn't for "normal-file" documents.
:* "--nowarn", "--quiet", "--verbose" and "--debug" now not only configure the "Printers", but also "SimpleLogging".
:* Added the "--replacementMode" option which allows for more complex replacements than the java.util.regex.Matcher can offer
; Changes in version 1.3.8, 2019-10-09:
:* zzgrep: Implemented "-e".
:* zzgrep: Implemented "--byte-offset", "--with-path", "--no-path", "--label", "--line-number", "--after-context", "--before-context" and "--context".
:* <zzpatch> Ant task: "<substitution><regex>..." and "...<replacement>...": Property "replacement" was missing for "addText()".
:* Major refactoring of "zz.Find" - removed tons of copied code.
:* zzfind: Improved handling of corrupt archives and compressed contents.
; Changes in version 1.3.7, 2019-08-05:
:* In addition to "...-jar-with-dependencies.jar", generate a "...-antlib.jar" file, where the ANT classes are NOT included.
:* The "-copy" action now supports a "--append" (alias "-a") modifier.
:* Now using "ExpressionEvaluator.parseExt()".
:* Added "--printf" command line action.
:* Fixed the "line equivalence" and the "ignore" feature; both were accidentially broken with revision 6980 (affects only release 1.3.5).
:* The "zz-diff" command line tool now also accepts URLs on its command line.
:* "--verbose" had no effect; now it prints the names of files and archive entries that are searched.
; Changes in Version 1.3.6, 2018-07-24:
:* Added a test case for "zzpatch --substitute --iff".
:* Substitution conditions now support a new variable, "occurrence".
:* Added a "<condition>" subelement on the "<substitution>" element. This is useful, e.g., to replace only the FIRST match.
:* For conformance with GREP, exit with status 2 (not 1) on errors.
:* <zzfind>: Added the "<prune />" and "<delete />" subelements.
:* zzfind: Renamed option "--depth" to "--descendants-first" (and left the original as an alias).
:* <zzfind>: Renamed the depth="..." attribute to descendantsFirst="...".
:* Added the "-prune" and "-delete" actions.
:* Added "&&" and "-and" as aliases for "-a".
:* Added "||" and "-or" as aliases for "-o".
:* Added options "da-verbose", "da-source-directory" and "da-symbolic-labels".
:* Continue with next archive entry on IOException.
:* ZZGREP: When run with a list file-or-dirs, only every second file-or-dir was searched.
; Changes in version 1.3.4, 2017-02-03:
:* Added a workaround for: MS WINDOWS 7: Read-protected directory produces: isDirectory() => true canRead()    => true list()        => null listFiles()  => null (Caused NPEs.)
:* ZZDIFF: Bug fixed: Document DIFF was always UNIFIED, regardless of the document diff mode setting.
:* Change version of de.unkrig.commons from "1.2.6-SNAPSHOT" to "1.2.7-SNAPSHOT" (because THAT is the correct post-1.2.6 version).
:* Renamed "namePredicate" to "pathPredicate".
:* Replaced the "name=..." attribute with "path=...", and marked the old attribute as @deprecated.
:* The "pathPredicate" was missing from content processors.
:* Generate ANTDOC only for the "zz-all" module, not for "zz-(diff|find|grep|pack|patch)" individually. Saves on build time, and reduces redundant documentation.
; Changes in version 1.3.3, 2016-11-28:
:* Removed unnecessary dependency on "jdisasm".
:* Fixed the classpath for zz-all antdoc.
:* Added the "--no-recurse-subdirctories" command line option.
:* Extracted the "DOcumentDiff" class from the "Diff" class.
:* Added task attribute "recurseSubdirectories=false".
:* Added the "Diff.diff(path1, path2, stream1, stream2)" method.
; Changes in version 1.3.2, 2016-11-25:
:* Added test cases for ZZDIFF.
:* Added "Diff.execute(String path1, String path2, ...)" to allow for custom "path1" and "path2" strings when reporting differences.
:* Improved many "DiffException"s' messages.
:* Slightly clarified the wording of the license: Replaced "author" with "copyright holder and its contributors".
:* Include project name and version in APIDOC's "-header" and "-footer".
; Changes in version 1.3.1, 2016-11-07:
:* The JVM (sometimes) did not terminate when it is shut down orderly (i.e. "main()" returns or "System.exit()" is invoked).
:* Added the "launch4j" maven plugin that creates MS WINDOWS executables from the runnable JAR files.
:* Made the scope of the "ant" dependency "provided", so that the classes of "ant.jar" don't get into the "jar-with-dependencies".
:* Added JAVADOC "overview.html" files for the five zz tools.
:* ZZFIND: Made many methods and nested types PUBLIC, so they can be used via the Java API.
:* Moved ANTDOC generation from "zz-parent/build.ant" to "zz-parent/pom.xml".
:* Added "zz-all", which is an aggregation of the five ZZ tools.
; Changes in version 1.3.0, 2016-10-30:
:* ZZFIND, <zzfind>: Line separator was missing from the "LS" action.
:* ZZFIND, <zzfind>: Added the "-digest" and "-checksum" actions.
:* ZZFIND: Allow combinations of file names and "-" (STDIN).
:* <zzfind>: Added "<true/>" and "<false/>".
:* ZZFIND: Added "-true" and "-false".
:* <zzfind>: The expression subelements are now named ANT components.
:* ZZFIND: Variable substitution (in "-echo" and "-copy") now supports "@variableName" in addition to "@{variable-name}".
:* ZZDIFF, <zzdiff>: Added options "addedFile" and "deletedFile" which supersede "newFile" and "unidirectionalNewFile".
:* <zzpatch>: File/entry renaming did not work (flag Glob.REPLACEMENT was missing).
:* <zzfind>: Renamed the "<path>" expression component to "<path_>" to avoid a name clash with the global type with the same name.
:* Switched from the old ANT build to MAVEN.
; Changes in version 1.2.5, 2016-02-12:
:* ZZFIND, <zzfind>: Added the "depth" property.
:* ZZFIND, <zzfind>: Added the "comma operator", "-mtime", "-depth", "-minDepth" and "-maxDepth".
; Changes in version 1.2.4, 2016-02-10:
:* <zzpatch>: "condition=..." is now an attribute of the <patch> subelement, not the task.
:* zzdiff: Added command line option "--normal".
:* All pathes: Compressed file names and compressed contents paths are now suffixed with '%' (instead of '!') to circumvent problems with "Glob"'s directory prefix mechanism.
:* ZZFIND on STDIN threw exceptions, because "-ls" requires "isDirectory", "size", etc.
:* ZZFIND: Parsing of special command line argument "-" (for "STDIN") didn't work.
:* ZZGREP: The "-quiet" command line option did not have any effect.
; Changes in version 1.2.3, 2015-09-27:
:* ZZFIND command line tool: Option "--look-into": Glob was compiled WITHOUT the WILDCARD|INCLUDES_EXCLUDES flag.
; Changes in version 1.2.2, 2015-09-27:
:* ZZPATCH ant task: Removed attribute "memberName=..." from subelement "<add>", because the ant task does not traverse directories (opposed to the command line version), and thus adding members to directories is not possible.
:* ZZDIFF: Fixed some NPEs that occurred when files / entries are EXCLUDED.
:* ZZFIND: Added the "DisassembleAction" (disassembles a Java .class file).
:* Generate and publish HTML documentation for ANT tasks with ANTDOC.
; Changes in version 1.2.1, 2015-05-24:
:* FIND: Command line tool and ANT task now continue with next directory member on IOExceptions.
:* DIFF: Added the "tokenization" configuration parameter, which allows for Java token-based DIFFing.
:* DIFF: Added the "ignoreCStyleComments" and "ignoreCPlusPlusStyleComments" configuration option (relevant iff "tokenization" is "JAVA").
:* The classes for the 'zzpack' ant task were missing from the jar file.
:* ZZFIND ant task: Added the "file=..." and "dir=..." attributes.
:* ZZFIND: Added the "<echo message=...>" and "<property name=... value=...>" actions.
; Changes in version 1.2.0, 2015-04-30:
:* "ArchiveFormatFactory" and "CompressionFormatFactory" now register "URLStreamHandler"s for all archive and compression formats, so these can be used as "protocols" of "java.net.URL", e.g. "zip:file:foo.zip!file.txt".
:* Major refactoring of 'de.unkrig.commons.file.fileprocessing' and 'de.unkrig.commons.file.contentsprocessing'. Effectively, ZZGREP can now use these classes, because 'process()' now returns 'T'.
:* Renamed the following classes for consistency with 'java.util.Collections', '...Arrays', etc.:
:** ContentsProcessingUtil => ContentsProcessings
:** ContentsTransformerUtil => ContentsTransformations
:** FileProcessingUtil => FileProcessings
:** FileTransformationUtil  => FileTransformations
:* ANT integration: Added the '<patch>' filter (for use in ANT 'filter chain's).
:* ANT integration: Added the 'condition' property to the '<zzpatch>' task.
:* ZZDIFF: Added the "-sequential" command line option.
:* <zzdiff>: Replaced the 'lookInto[Nested](Zip|Gzip)="..."' attributes with the (more flexible) 'lookInto="..."' attribute.
:* <zzdiff>: Replaced the "<exclude>" subelements with the "path=..." attribute, eliminating the unusual "negative" logic.
; Changes in version 1.1.0, 2014-10-25:
:* zzpatch: No file arguments mean 'transform STDIN to STDOUT'.
:* zzpatch: Added 'conditions' for the 'substitute', 'replace', 'patch', 'remove', 'rename' and 'add' features.
:* zzpatch: Added 'dontSortDirectoryMembers' feature.
:* de.unkrig.commons.file: Thanks to apache.commons.compress, we now not only support the ZIP archive format and the GZIP compression algorithm, but also the AR, ARJ, CPIO, DUMP, JAR, TAR and SEVEN_Z archive formats and the BZIP2, PACK200, XZ, LZMA, SNAPPY and Z compression algorithms.
:* <zzpatch>, <zzgrep>: Removed the 'dir="..."' and 'sortDirectoryMembers="..."' attributes from these ANT tasks because recursing directories is ANT's job.
:* <zzpatch>, <zzgrep>: Replaced the 'lookInto[Nested](Zip|Gzip)="..."' attributes with the (more flexible) 'lookInto="..."' attribute.
:* <zzgrep>: Removed the "dir=..." attribute.
; Changes in version 1.0.11, 2014-04-12:
:* ZZDIFF: Added option '-unchanged-files' resp. ANT task attribute 'reportUnchangedFiles="true"': Also report unchanged files.
:* ZZDIFF: Added '-zip' and '-nested-zip' command line options - aliases for '-z' and '-zz'.
:* ZZFIND: Added the '-copy' action - similar to '-cat', but copies the data bytewise.
:* <zzfind>: Added a '<sequential>' subelement.
:* <zzgrep>: Added attributes 'file="..."' and 'dir="..."'
:* <zzpatch>: Added attributes 'file="..."', 'tofile="..."', 'dir="..."' and 'todir="..."'
:* de.unkrig.commons.util: <simplelogging>: Added attribute 'spec="..."'.
:* <zzgrep>: Added attribute 'property="..."'.
:* <zzgrep>: Added subelement '<search name="..." regex="..." caseSensitive="..."/>'
:* <zzgrep>: Made the 'case sensitivity logic' POSITIVE.
:* <zzgrep>: Removed the '<include>' and '<exclude>' subelements in favor of 'name="..."'.
:* <zzgrep>: 'name="..."', 'regex="..."' and 'caseSensitive="..."' are now mutually exclusive with '<search>' subelements.
:* <zzgrep>: Runtime optimization: Now only the files to which at least one search applies are processed.
; Changes in version 1.0.10, 2014-03-22:
:* ZZDIFF: Added option '-keep-going' resp. ANT task attribute 'keepGoing="true"': Report errors and continue with next file.
 
; Changes in version 1.0.9, 2014-03-20:
:* COMMONS.UTIL: Added the SIMPLELOGGING task that was missing from 'antlib.xml'.
:* COMMONS.FILE: Inserted lots of logging.
:* ZZPATCH: Added the <regex> and <replacement> subelements to <substitute>: Alternative to the 'regex=...' and 'replacement=...' attributes. The major advantage of the subelements is that they can contain '<![CDATA[...]]>' sections where you don't have to SGML-escape special characters.
:* ZZPATCH: Added lots of logging to make ANT build file debugging easier.
:* ZZPATCH: Contents substitution is no longer line-wise, but allows for multi-line matching and replacement.
:* ZZFIND: Now searching STDIN iff no file specified.
:* ZZDIFF: Added diff mode 'EXIST', which is like diff mode 'QUIET' but ignores CONTENT differences.
; Changes in version 1.0.8, 2013-11-29:
:* ZZDIFF: Absent file modes COMPARE_*_WITH_EMPTY: Added and deleted directories were counted as difference, although they shouldn't.
; Changes in version 1.0.7, 2013-11-26:
:* The ZZ tools now live in ONE jar file; there is a new 'Main' class that forks into the various tools
:* Renamed the tasks from 'de.unkrig.zz.diff' to 'zzdiff'.
:* ZZDIFF: Absent file modes COMPARE_ADDED_AND_DELETED_WITH_EMPTY and COMPARE_ADDED_WITH_EMPTY: Added and deleted DIRECTORIES are now treated as EMPTY directories.
:* ZZDIFF: Added ANT task property 'property'.
; Changes in version 1.0.6, 2013-10-02:
:* ZZPATCH: '-patch' now preserves line separators (instead of silently replacing them with the default line separator).
; Changes in version 1.0.5, 2013-10-01:
:* ZZDIFF: Added the 'encoding' attribute to the ant task.
:* ZZFIND: Added the missing '<cat>' and '<ls>' actions to the ant task.
:* ZZFIND: Added the '-encoding' option to the command line tool.
:* ZZGREP: Added the 'encoding' attribute to the ant task.
:* ZZGREP: Added the '-encoding' option to the command line tool.
:* ZZPATCH: Added 'inputEncoding' and 'outputEncoding' to 'substitution' and 'patch'.
:* ZZPATCH: Added 'patchFileEncoding' to 'patch'.
:* ZZPATCH: '-substitute' now preserves line separators (instead of silently replacing them with the default line separator).
; Changes in version 1.0.4, 2013-09-22:
:* ZZFIND: The 'readable', 'writable', 'size' and 'modificationTime' tests were missing from the ANT task
; Changes in version 1.0.3, 2013-09-22:
:* ZZDIFF: Added the 'absentFileMode' option (a.k.a. as '-new-file' and '-unidirectional-new-file').
:* SimpleLogging: VERBOSE messages were not printed because the OUT_HANDLER was misconfigured.
; Changes in version 1.0.2, 2013-07-05:
:* Fixed a major bug: 'SelectiveContentsTransfomer' executed BOTH delegates when the predicate evaluates to FALSE. This didn't hurt in many cases, but for 'zzpatch -update' it did.
; Changes in version 1.0.1, 2013-06-14:
:* Major refactoring of 'de.unkrig.commons'.
; Version 1.0.0, 2012-10-03:
Initial release.

Latest revision as of 10:13, 29 December 2022

<meta name="keywords" content="java, compressed, archive, zip, zipped, nested"></meta> <meta name="description" content="A set of command-line tools that handle not only directories and files, but also archive and compressed files, and even nested archive files"></meta> A set of command-line tools that handle not only directories and files, but also archive and compressed files, and even nested archive files. They can even disassemble Java .class files on-the fly and operate on the disassembly.

Tool Documentation[edit]

zzdiff[edit]

Computes the differences between files, directory trees, archive file entries, compressed files and prints them in various formats; widely compatible with the UNIX™ DIFF command line utility.

Read the command line tool documentation.

Read the ANT task documentation.

zzfind[edit]

Finds files in directory trees and entries in archive files by various criteria; widely compatible with the UNIX™ FIND command line utility.

Read the command line tool documentation (or the plain text version).

Read the ANT task documentation.

zzgrep[edit]

Finds lines in files in directory trees and in entries in archive files by regular expressions; widely compatible with the UNIX™ GREP command line utility.

Read the command line tool documentation.

Read the ANT task documentation.

zzpack[edit]

Creates an archive file from a set of given files, directories, and archive entries.

Read the command line tool documentation.

Read the ANT task documentation.

zzpatch[edit]

Modifies the contents of files in directory trees and of entries in archive files by various criteria; widely compatible with the UNIX™ PATCH command line utility.

Read the command line tool documentation.

Read the ANT task documentation.

Download and Installation[edit]

Runnable JAR files[edit]

Latest version of

MS WINDOWS executables[edit]

Latest version of

Notice: These executables require an installed JRE; at least version 1.6. They will complain if they cannot find a suitable JRE, and give advice how to get things running.

APACHE ANT libraries[edit]

Latest version of

To use the ANT types, insert one of the following lines in your build script:

 <taskdef resource="de/unkrig/zz/zz-diff.xml"  classpath="path/to/zz-diff-x.y.z-jar-with-dependencies.jar"  />
 <taskdef resource="de/unkrig/zz/zz-find.xml"  classpath="path/to/zz-find-x.y.z-jar-with-dependencies.jar"  />
 <taskdef resource="de/unkrig/zz/zz-grep.xml"  classpath="path/to/zz-grep-x.y.z-jar-with-dependencies.jar"  />
 <taskdef resource="de/unkrig/zz/zz-pack.xml"  classpath="path/to/zz-pack-x.y.z-jar-with-dependencies.jar"  />
 <taskdef resource="de/unkrig/zz/zz-patch.xml" classpath="path/to/zz-patch-x.y.z-jar-with-dependencies.jar" />

If you use more than one of the tools in your build script, it is more efficient to use the "all-in-one" JAR file:

 <taskdef resource="de/unkrig/zz/zz-all.xml" classpath="path/to/zz-all-x.y.z-jar-with-dependencies.jar" />

Java Library[edit]

The ZZ tools also have a public Java API that can be used from by any Java application. You can either download and use this JAR file, or, if you're using MAVEN, put in your "pom.xml" file:

<dependency>
    <groupId>de.unkrig.zz</groupId>
    <artifactId>zz-diff</artifactId> 
    <version>x.y.z</version>
</dependency>

Here is the API documentation:

Resources[edit]

Source code is available on GITHUB, and also through MAVEN:

The ZZ tools make heavy use of commons.unkrig.de.

License[edit]

ZZ.UNKRIG.DE is published under the "New BSD License".

Change Log[edit]

Changes in version 1.3.11-SNAPSHOT (not yet released)
  • -
Changes in version 1.3.10, 2022-12-29
  • Changed handling of "-" to ResourceProcessings.STDIN_URL.
  • ZZDIFF can now handle "-" (stdin) as one of its two inputs.
  • ZZPATCH: --substitute: Removed the concept of the "replacement mode", because the extended replacement syntax just implements the "literal" and "expression" replacement modes.
  • ZZPACK: Added the "--rename" feature.
  • ZZPATCH: Substitution: Replacement mode "REPLACEMENT_STRING" now supports "ext syntax", i.e. "${...}" embedded expressions.
  • ZZPATCH: ExitException message is now "Printers.info()"ed instead of "Printers.verbose()"ed.
  • ZZFIND: Greatly simplified the computation of the expression variables.
  • ZZFIND: Fixed an exception when finding in STDIN: STDIN does not have the properties "readable", "writable" and "executable".
  • ZZFIND: Class file version can now be accessed by "cf.javaVersion".
  • ZZFIND: MAINDOC: Documented the "archiveEntry" variable.
  • ZZGREP: Moved "Grep.lineCounter()" to "ConsumerUtil".
  • ZZGREP: Eliminated the 65536-characters-per-line limit -- finds and counts matches now also in very long lines.
  • ZZPATCH: Added the "--assert-count" condition for updates/substitution replacements/patch hunks/removals/renamings/additions.
  • ZZFIND: Learned that the various ZIP archive libraries return random values for "ZipEntry.getMethod()" and "ZipEntry.getCrc()", thus made the test cases tolerant against these.
  • ZZFIND: Don't print a stack trace on predicate parse errors; only print the error message.
  • ZZPATCH: Added command line options for archive decryption: --7z-input-file-password --zip-input-file-password --password
  • ZZPATCH: Added command line options for archive compression and encryption: --zip-output-entry-compression-level --zip-output-file-password --zip-output-file-encryption-method
  • ZZFIND: Added short command line option for archive decryption: --password
  • ZZFIND: Added the "-version" command line option.
  • ZZGREP: Added command line options "--input-encoding" and "--output-encoding". (Previously, the output encoding was not configurable.)
  • ZZGREP: Fixed the printing of "--" separator lines between context-grep chunks.
  • ZZFIND: MAINDOC: Documented priority of operators.
  • ZZFIND: CatAction: Entries that have no input stream (e.g. directories or directory archive entries) are silently ignored, because that is practical: Otherwise, you'd always have to put "-type normal*" right before the "-cat" action.
  • ZZFIND: -copy action: Now ignore entries that have no input stream (e.g. directories or directory archive entries), because that is practical: Otherwise, you'd always have to put "-type normal*" right before the "-copy" action.
  • ZZFIND: -copy action: Attempt to restore each file's "last modification date", too.
  • ZZPATCH: Unified DIFF format: Some DIFF tools (namely GNU diffutils 3.5) put a TAB character (instead of a SPACE) between the file name and the date.
  • ZZFIND: Added "--toFile" option to "-disassemble".
  • ZZFIND: Added new variable "archiveEntry".
  • ZZFIND: Added action "-java-class-file".
  • ZZFIND: Added expression variable "compressionMethod" (for archive entries).
Changes in version 1.3.9, 2020-11-06
  • Updated jdisasm to 1.0.6.
  • Updated de.unkrig.commons to 1.2.15.
  • Removed the generation of the "...-antlib.jar" file, because "...-jar-with-dependencies.jar" can be used as an ANTLIB as well.
  • Fixed the file type in the output of -ls.
  • Added expression variables "readable", "writable" and "executable".
  • Adapted to an incompatible API change in "commons-file" (all content processing was augmented with an optional "lastModifiedDate" parameter).
  • Fixed an NPE that occurred with 7Z archive entries that have NO modification date set.
  • ZZFIND now compiles with JDK 1.8 (before it was 1.6).
  • Major refactoring: Replaced "Mappings properties" with "Map<String, Function<Object, Object>> properties.
  • Implemented the new expression variables "_map", "_keys" and "_values".
  • Context diff: The "hunk separator line" ("--") was missing.
  • Actions that read the contents of a document (-cat, -copy, -disassemble, -digest, -checksum) didn't for "normal-file" documents.
  • "--nowarn", "--quiet", "--verbose" and "--debug" now not only configure the "Printers", but also "SimpleLogging".
  • Added the "--replacementMode" option which allows for more complex replacements than the java.util.regex.Matcher can offer
Changes in version 1.3.8, 2019-10-09
  • zzgrep: Implemented "-e".
  • zzgrep: Implemented "--byte-offset", "--with-path", "--no-path", "--label", "--line-number", "--after-context", "--before-context" and "--context".
  • <zzpatch> Ant task: "<substitution><regex>..." and "...<replacement>...": Property "replacement" was missing for "addText()".
  • Major refactoring of "zz.Find" - removed tons of copied code.
  • zzfind: Improved handling of corrupt archives and compressed contents.
Changes in version 1.3.7, 2019-08-05
  • In addition to "...-jar-with-dependencies.jar", generate a "...-antlib.jar" file, where the ANT classes are NOT included.
  • The "-copy" action now supports a "--append" (alias "-a") modifier.
  • Now using "ExpressionEvaluator.parseExt()".
  • Added "--printf" command line action.
  • Fixed the "line equivalence" and the "ignore" feature; both were accidentially broken with revision 6980 (affects only release 1.3.5).
  • The "zz-diff" command line tool now also accepts URLs on its command line.
  • "--verbose" had no effect; now it prints the names of files and archive entries that are searched.
Changes in Version 1.3.6, 2018-07-24
  • Added a test case for "zzpatch --substitute --iff".
  • Substitution conditions now support a new variable, "occurrence".
  • Added a "<condition>" subelement on the "<substitution>" element. This is useful, e.g., to replace only the FIRST match.
  • For conformance with GREP, exit with status 2 (not 1) on errors.
  • <zzfind>: Added the "<prune />" and "<delete />" subelements.
  • zzfind: Renamed option "--depth" to "--descendants-first" (and left the original as an alias).
  • <zzfind>: Renamed the depth="..." attribute to descendantsFirst="...".
  • Added the "-prune" and "-delete" actions.
  • Added "&&" and "-and" as aliases for "-a".
  • Added "||" and "-or" as aliases for "-o".
  • Added options "da-verbose", "da-source-directory" and "da-symbolic-labels".
  • Continue with next archive entry on IOException.
  • ZZGREP: When run with a list file-or-dirs, only every second file-or-dir was searched.
Changes in version 1.3.4, 2017-02-03
  • Added a workaround for: MS WINDOWS 7: Read-protected directory produces: isDirectory() => true canRead() => true list() => null listFiles() => null (Caused NPEs.)
  • ZZDIFF: Bug fixed: Document DIFF was always UNIFIED, regardless of the document diff mode setting.
  • Change version of de.unkrig.commons from "1.2.6-SNAPSHOT" to "1.2.7-SNAPSHOT" (because THAT is the correct post-1.2.6 version).
  • Renamed "namePredicate" to "pathPredicate".
  • Replaced the "name=..." attribute with "path=...", and marked the old attribute as @deprecated.
  • The "pathPredicate" was missing from content processors.
  • Generate ANTDOC only for the "zz-all" module, not for "zz-(diff|find|grep|pack|patch)" individually. Saves on build time, and reduces redundant documentation.
Changes in version 1.3.3, 2016-11-28
  • Removed unnecessary dependency on "jdisasm".
  • Fixed the classpath for zz-all antdoc.
  • Added the "--no-recurse-subdirctories" command line option.
  • Extracted the "DOcumentDiff" class from the "Diff" class.
  • Added task attribute "recurseSubdirectories=false".
  • Added the "Diff.diff(path1, path2, stream1, stream2)" method.
Changes in version 1.3.2, 2016-11-25
  • Added test cases for ZZDIFF.
  • Added "Diff.execute(String path1, String path2, ...)" to allow for custom "path1" and "path2" strings when reporting differences.
  • Improved many "DiffException"s' messages.
  • Slightly clarified the wording of the license: Replaced "author" with "copyright holder and its contributors".
  • Include project name and version in APIDOC's "-header" and "-footer".
Changes in version 1.3.1, 2016-11-07
  • The JVM (sometimes) did not terminate when it is shut down orderly (i.e. "main()" returns or "System.exit()" is invoked).
  • Added the "launch4j" maven plugin that creates MS WINDOWS executables from the runnable JAR files.
  • Made the scope of the "ant" dependency "provided", so that the classes of "ant.jar" don't get into the "jar-with-dependencies".
  • Added JAVADOC "overview.html" files for the five zz tools.
  • ZZFIND: Made many methods and nested types PUBLIC, so they can be used via the Java API.
  • Moved ANTDOC generation from "zz-parent/build.ant" to "zz-parent/pom.xml".
  • Added "zz-all", which is an aggregation of the five ZZ tools.
Changes in version 1.3.0, 2016-10-30
  • ZZFIND, <zzfind>: Line separator was missing from the "LS" action.
  • ZZFIND, <zzfind>: Added the "-digest" and "-checksum" actions.
  • ZZFIND: Allow combinations of file names and "-" (STDIN).
  • <zzfind>: Added "<true/>" and "<false/>".
  • ZZFIND: Added "-true" and "-false".
  • <zzfind>: The expression subelements are now named ANT components.
  • ZZFIND: Variable substitution (in "-echo" and "-copy") now supports "@variableName" in addition to "@{variable-name}".
  • ZZDIFF, <zzdiff>: Added options "addedFile" and "deletedFile" which supersede "newFile" and "unidirectionalNewFile".
  • <zzpatch>: File/entry renaming did not work (flag Glob.REPLACEMENT was missing).
  • <zzfind>: Renamed the "<path>" expression component to "<path_>" to avoid a name clash with the global type with the same name.
  • Switched from the old ANT build to MAVEN.
Changes in version 1.2.5, 2016-02-12
  • ZZFIND, <zzfind>: Added the "depth" property.
  • ZZFIND, <zzfind>: Added the "comma operator", "-mtime", "-depth", "-minDepth" and "-maxDepth".
Changes in version 1.2.4, 2016-02-10
  • <zzpatch>: "condition=..." is now an attribute of the <patch> subelement, not the task.
  • zzdiff: Added command line option "--normal".
  • All pathes: Compressed file names and compressed contents paths are now suffixed with '%' (instead of '!') to circumvent problems with "Glob"'s directory prefix mechanism.
  • ZZFIND on STDIN threw exceptions, because "-ls" requires "isDirectory", "size", etc.
  • ZZFIND: Parsing of special command line argument "-" (for "STDIN") didn't work.
  • ZZGREP: The "-quiet" command line option did not have any effect.
Changes in version 1.2.3, 2015-09-27
  • ZZFIND command line tool: Option "--look-into": Glob was compiled WITHOUT the WILDCARD|INCLUDES_EXCLUDES flag.
Changes in version 1.2.2, 2015-09-27
  • ZZPATCH ant task: Removed attribute "memberName=..." from subelement "<add>", because the ant task does not traverse directories (opposed to the command line version), and thus adding members to directories is not possible.
  • ZZDIFF: Fixed some NPEs that occurred when files / entries are EXCLUDED.
  • ZZFIND: Added the "DisassembleAction" (disassembles a Java .class file).
  • Generate and publish HTML documentation for ANT tasks with ANTDOC.
Changes in version 1.2.1, 2015-05-24
  • FIND: Command line tool and ANT task now continue with next directory member on IOExceptions.
  • DIFF: Added the "tokenization" configuration parameter, which allows for Java token-based DIFFing.
  • DIFF: Added the "ignoreCStyleComments" and "ignoreCPlusPlusStyleComments" configuration option (relevant iff "tokenization" is "JAVA").
  • The classes for the 'zzpack' ant task were missing from the jar file.
  • ZZFIND ant task: Added the "file=..." and "dir=..." attributes.
  • ZZFIND: Added the "<echo message=...>" and "<property name=... value=...>" actions.
Changes in version 1.2.0, 2015-04-30
  • "ArchiveFormatFactory" and "CompressionFormatFactory" now register "URLStreamHandler"s for all archive and compression formats, so these can be used as "protocols" of "java.net.URL", e.g. "zip:file:foo.zip!file.txt".
  • Major refactoring of 'de.unkrig.commons.file.fileprocessing' and 'de.unkrig.commons.file.contentsprocessing'. Effectively, ZZGREP can now use these classes, because 'process()' now returns 'T'.
  • Renamed the following classes for consistency with 'java.util.Collections', '...Arrays', etc.:
    • ContentsProcessingUtil => ContentsProcessings
    • ContentsTransformerUtil => ContentsTransformations
    • FileProcessingUtil => FileProcessings
    • FileTransformationUtil => FileTransformations
  • ANT integration: Added the '<patch>' filter (for use in ANT 'filter chain's).
  • ANT integration: Added the 'condition' property to the '<zzpatch>' task.
  • ZZDIFF: Added the "-sequential" command line option.
  • <zzdiff>: Replaced the 'lookInto[Nested](Zip|Gzip)="..."' attributes with the (more flexible) 'lookInto="..."' attribute.
  • <zzdiff>: Replaced the "<exclude>" subelements with the "path=..." attribute, eliminating the unusual "negative" logic.
Changes in version 1.1.0, 2014-10-25
  • zzpatch: No file arguments mean 'transform STDIN to STDOUT'.
  • zzpatch: Added 'conditions' for the 'substitute', 'replace', 'patch', 'remove', 'rename' and 'add' features.
  • zzpatch: Added 'dontSortDirectoryMembers' feature.
  • de.unkrig.commons.file: Thanks to apache.commons.compress, we now not only support the ZIP archive format and the GZIP compression algorithm, but also the AR, ARJ, CPIO, DUMP, JAR, TAR and SEVEN_Z archive formats and the BZIP2, PACK200, XZ, LZMA, SNAPPY and Z compression algorithms.
  • <zzpatch>, <zzgrep>: Removed the 'dir="..."' and 'sortDirectoryMembers="..."' attributes from these ANT tasks because recursing directories is ANT's job.
  • <zzpatch>, <zzgrep>: Replaced the 'lookInto[Nested](Zip|Gzip)="..."' attributes with the (more flexible) 'lookInto="..."' attribute.
  • <zzgrep>: Removed the "dir=..." attribute.
Changes in version 1.0.11, 2014-04-12
  • ZZDIFF: Added option '-unchanged-files' resp. ANT task attribute 'reportUnchangedFiles="true"': Also report unchanged files.
  • ZZDIFF: Added '-zip' and '-nested-zip' command line options - aliases for '-z' and '-zz'.
  • ZZFIND: Added the '-copy' action - similar to '-cat', but copies the data bytewise.
  • <zzfind>: Added a '<sequential>' subelement.
  • <zzgrep>: Added attributes 'file="..."' and 'dir="..."'
  • <zzpatch>: Added attributes 'file="..."', 'tofile="..."', 'dir="..."' and 'todir="..."'
  • de.unkrig.commons.util: <simplelogging>: Added attribute 'spec="..."'.
  • <zzgrep>: Added attribute 'property="..."'.
  • <zzgrep>: Added subelement '<search name="..." regex="..." caseSensitive="..."/>'
  • <zzgrep>: Made the 'case sensitivity logic' POSITIVE.
  • <zzgrep>: Removed the '<include>' and '<exclude>' subelements in favor of 'name="..."'.
  • <zzgrep>: 'name="..."', 'regex="..."' and 'caseSensitive="..."' are now mutually exclusive with '<search>' subelements.
  • <zzgrep>: Runtime optimization: Now only the files to which at least one search applies are processed.
Changes in version 1.0.10, 2014-03-22
  • ZZDIFF: Added option '-keep-going' resp. ANT task attribute 'keepGoing="true"': Report errors and continue with next file.
Changes in version 1.0.9, 2014-03-20
  • COMMONS.UTIL: Added the SIMPLELOGGING task that was missing from 'antlib.xml'.
  • COMMONS.FILE: Inserted lots of logging.
  • ZZPATCH: Added the <regex> and <replacement> subelements to <substitute>: Alternative to the 'regex=...' and 'replacement=...' attributes. The major advantage of the subelements is that they can contain '<![CDATA[...]]>' sections where you don't have to SGML-escape special characters.
  • ZZPATCH: Added lots of logging to make ANT build file debugging easier.
  • ZZPATCH: Contents substitution is no longer line-wise, but allows for multi-line matching and replacement.
  • ZZFIND: Now searching STDIN iff no file specified.
  • ZZDIFF: Added diff mode 'EXIST', which is like diff mode 'QUIET' but ignores CONTENT differences.
Changes in version 1.0.8, 2013-11-29
  • ZZDIFF: Absent file modes COMPARE_*_WITH_EMPTY: Added and deleted directories were counted as difference, although they shouldn't.
Changes in version 1.0.7, 2013-11-26
  • The ZZ tools now live in ONE jar file; there is a new 'Main' class that forks into the various tools
  • Renamed the tasks from 'de.unkrig.zz.diff' to 'zzdiff'.
  • ZZDIFF: Absent file modes COMPARE_ADDED_AND_DELETED_WITH_EMPTY and COMPARE_ADDED_WITH_EMPTY: Added and deleted DIRECTORIES are now treated as EMPTY directories.
  • ZZDIFF: Added ANT task property 'property'.
Changes in version 1.0.6, 2013-10-02
  • ZZPATCH: '-patch' now preserves line separators (instead of silently replacing them with the default line separator).
Changes in version 1.0.5, 2013-10-01
  • ZZDIFF: Added the 'encoding' attribute to the ant task.
  • ZZFIND: Added the missing '<cat>' and '<ls>' actions to the ant task.
  • ZZFIND: Added the '-encoding' option to the command line tool.
  • ZZGREP: Added the 'encoding' attribute to the ant task.
  • ZZGREP: Added the '-encoding' option to the command line tool.
  • ZZPATCH: Added 'inputEncoding' and 'outputEncoding' to 'substitution' and 'patch'.
  • ZZPATCH: Added 'patchFileEncoding' to 'patch'.
  • ZZPATCH: '-substitute' now preserves line separators (instead of silently replacing them with the default line separator).
Changes in version 1.0.4, 2013-09-22
  • ZZFIND: The 'readable', 'writable', 'size' and 'modificationTime' tests were missing from the ANT task
Changes in version 1.0.3, 2013-09-22
  • ZZDIFF: Added the 'absentFileMode' option (a.k.a. as '-new-file' and '-unidirectional-new-file').
  • SimpleLogging: VERBOSE messages were not printed because the OUT_HANDLER was misconfigured.
Changes in version 1.0.2, 2013-07-05
  • Fixed a major bug: 'SelectiveContentsTransfomer' executed BOTH delegates when the predicate evaluates to FALSE. This didn't hurt in many cases, but for 'zzpatch -update' it did.
Changes in version 1.0.1, 2013-06-14
  • Major refactoring of 'de.unkrig.commons'.
Version 1.0.0, 2012-10-03

Initial release.