TDE
/
kdiff3
mirror of https://mirror.git.trinitydesktop.org/gitea/TDE/kdiff3
0
0
Fork 0
Code Issues Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '86f9be34cc'
${ noResults }
kdiff3/doc/en/preprocessors.html

202 lines
21 KiB
Raw Normal View History Unescape

Added abandoned KDE3 version of kdiff3 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/applications/kdiff3@1088041 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
15 years ago
<html><head><title>Preprocessor Commands</title><link rel="stylesheet" href="help:/common/kde-default.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.67.2"><meta name="keywords" content="KDE, kdeextragear, kdiff3, diff, merge, CVS, triplediff, compare, files, directories, version control, three-way-merge, in-line-differences, synchronise, kpart, kio, networktransparent, editor, white space, comments"><link rel="start" href="index.html" title="The KDiff3 Handbook"><link rel="up" href="documentation.html" title="Chapter 2. File Comparison And Merge"><link rel="prev" href="options.html" title="Options"><link rel="next" href="dirmerge.html" title="Chapter 3. Directory Comparison and Merge with KDiff3"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="GENERATOR" content="KDE XSL Stylesheet V1.13 using libxslt"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background-image: url(help:/common/top-middle.png); width: 100%; height: 131px;"><div style="position: absolute; right: 0px;"><img src="help:/common/top-right-konqueror.png" style="margin: 0px" alt=""></div><div style="position: absolute; top: 25px; right: 100px; text-align: right; font-size: xx-large; font-weight: bold; text-shadow: #fff 0px 0px 5px; color: #444">Preprocessor Commands</div></div><div style="margin-top: 20px; background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="options.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="dirmerge.html">Next</a></div><div class="navCenter">File Comparison And Merge</div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="preprocessors"></a>Preprocessor Commands</h2></div></div></div><p>
<span class="application">KDiff3</span> supports two preprocessor options.
</p><p>
<div class="variablelist"><dl><dt><span class="term"><span class="emphasis"><em>Preprocessor-Command:</em></span></span></dt><dd><p>
When any file is read, it will be piped through this external command.
The output of this command will be visible instead of the original file.
You can write your own preprocessor that fulfills your specific needs.
Use this to cut away disturbing parts of the file, or to automatically
correct the indentation etc.
</p></dd><dt><span class="term"><span class="emphasis"><em>Line-Matching Preprocessor-Command:</em></span></span></dt><dd><p>
When any file is read, it will be piped through this external command. If
a preprocessor-command (see above) is also specified, then the output of the
preprocessor is the input of the line-matching preprocessor.
The output will only be used during the line matching phase of the analysis.
You can write your own preprocessor that fulfills your specific needs.
Each input line must have a corresponding output line.
</p></dd></dl></div>
</p><p>
The idea is to allow the user greater flexibility while configuring the diff-result.
But this requires an external program, and many users don't want to write one themselves.
The good news is that very often <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> or <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">perl</strong></span></span>
will do the job.
</p><p>Example: Simple testcase: Consider file a.txt (6 lines):
<pre class="screen">
aa
ba
ca
da
ea
fa
</pre>
And file b.txt (3 lines):
<pre class="screen">
cg
dg
eg
</pre>
Without a preprocessor the following lines would be placed next to each other:
<pre class="screen">
aa - cg
ba - dg
ca - eg
da
ea
fa
</pre>
This is probably not wanted since the first letter contains the actually interesting information.
To help the matching algorithm to ignore the second letter we can use a line matching preprocessor
command, that replaces 'g' with 'a':
<pre class="screen">
<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/g/a/'
</pre>
With this command the result of the comparison would be:
<pre class="screen">
aa
ba
ca - cg
da - dg
ea - eg
fa
</pre>
Internally the matching algorithm sees the files after running the line matching preprocessor,
but on the screen the file is unchanged. (The normal preprocessor would change the data also on
the screen.)
</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sedbasics"></a><span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> Basics</h3></div></div></div><p>
This section only introduces some very basic features of <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span>. For more
information see <a href="info:/sed" target="_top">info:/sed</a> or
<a href="http://www.gnu.org/software/sed/manual/html_mono/sed.html" target="_top">
http://www.gnu.org/software/sed/manual/html_mono/sed.html</a>.
A precompiled version for Windows can be found at <a href="http://unxutils.sourceforge.net" target="_top">
http://unxutils.sourceforge.net</a>.
Note that the following examples assume that the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span>-command is in some
directory in the PATH-environment variable. If this is not the case, you have to specify the full absolute
path for the command.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Also note that the following examples use the single quotation mark (') which won't work for Windows.
On Windows you should use the double quotation marks (") instead.</p></div><p>
In this context only the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span>-substitute-command is used:
<pre class="screen">
<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>REGEXP</code></em></span>/<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>REPLACEMENT</code></em></span>/<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>FLAGS</code></em></span>'
</pre>
Before you use a new command within <span class="application">KDiff3</span>, you should first test it in a console.
Here the <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">echo</strong></span></span>-command is useful. Example:
<pre class="screen">
<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">echo</strong></span></span> abrakadabra | <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/a/o/'
-&gt; obrakadabra
</pre>
This example shows a very simple sed-command that replaces the first occurance
of "a" with "o". If you want to replace all occurances then you need the "g"-flag:
<pre class="screen">
<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">echo</strong></span></span> abrakadabra | <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/a/o/g'
-&gt; obrokodobro
</pre>
The "|"-symbol is the pipe-command that transfers the output of the previous
command to the input of the following command. If you want to test with a longer file
then you can use <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">cat</strong></span></span> on Unix-like systems or <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">type</strong></span></span>
on Windows-like systems. <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> will do the substitution for each line.
<pre class="screen">
<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">cat</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>filename</code></em></span> | <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>options</code></em></span>
</pre>
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="sedforkdiff3"></a>Examples For <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span>-Use In <span class="application">KDiff3</span></h3></div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2567628"></a>Ignoring Other Types Of Comments</h4></div></div></div><p>
Currently <span class="application">KDiff3</span> understands only C/C++ comments. Using the
Line-Matching-Preprocessor-Command you can also ignore
other types of comments, by converting them into C/C++-comments.
Example: To ignore comments starting with "#", you would like to convert them
to "//". Note that you also must enable the "Ignore C/C++-Comments" option to get
an effect. An appropriate Line-Matching-Preprocessor-Command would be:
<pre class="screen">
<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/#/\/\//'
</pre>
Since for <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> the "/"-character has a special meaning, it is necessary to place the
"\"-character before each "/" in the replacement-string. Sometimes the "\" is required
to add or remove a special meaning of certain characters. The single quotation marks (') before
and after the substitution-command are important now, because otherwise the shell will
try to interpret some special characters like '#', '$' or '\' before passing them to
<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span>. <span class="emphasis"><em>Note that on Windows you will need the double quotation marks (") here. Windows
substitutes other characters like '%', so you might have to experiment a little bit.</em></span>
</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2567680"></a>Caseinsensitive Diff</h4></div></div></div><p>
Use the following Line-Matching-Preprocessor-Command to convert all input to uppercase:
<pre class="screen">
<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/\(.*\)/\U\1/'
</pre>
Here the ".*" is a regular expression that matches any string and in this context matches
all characters in the line.
The "\1" in the replacement string refers to the matched text within the first pair of "\(" and "\)".
The "\U" converts the inserted text to uppercase.
</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2567704"></a>Ignoring Version Control Keywords</h4></div></div></div><p>
CVS and other version control systems use several keywords to insert automatically
generated strings (<a href="info:/cvs/Keyword%20substitution" target="_top">info:/cvs/Keyword substitution</a>).
All of them follow the pattern "$KEYWORD generated text$". We now need a
Line-Matching-Preprocessor-Command that removes only the generated text:
<pre class="screen">
<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/\$\(Revision\|Author\|Log\|Header\|Date\).*\$/\$\1\$/'
</pre>
The "\|" separates the possible keywords. You might want to modify this list
according to your needs.
The "\" before the "$" is necessary because otherwise the "$" matches the end of the line.
</p><p>
While experimenting with <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> you might come to understand and even like
these regular expressions. They are useful because there are many other programs that also
support similar things.
</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2567750"></a>Ignoring Numbers</h4></div></div></div><p>
Ignoring numbers actually is a built-in option. But as another example, this is how
it would look as a Line-Matching-Preprocessor-command.
<pre class="screen">
<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/[0123456789.-]//g'
</pre>
Any character within '[' and ']' is a match and will be replaced with nothing.
</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2567772"></a>Ignoring Certain Columns</h4></div></div></div><p>
Sometimes a text is very strictly formatted, and contains columns that you always want to ignore, while there are
other columns you want to preserve for analysis. In the following example the first five columns (characters) are
ignored, the next ten columns are preserved, then again five columns are ignored and the rest of the line is preserved.
<pre class="screen">
<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/.....\(..........\).....\(.*\)/\1\2/'
</pre>
Each dot '.' matches any single character. The "\1" and "\2" in the replacement string refer to the matched text within the first
and second pair of "\(" and "\)" denoting the text to be preserved.
</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2567800"></a>Combining Several Substitutions</h4></div></div></div><p>
Sometimes you want to apply several substitutions at once. You can then use the
semicolon ';' to separate these from each other. Example:
<pre class="screen">
<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">echo</strong></span></span> abrakadabra | <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/a/o/g;s/\(.*\)/\U\1/'
-&gt; OBROKODOBRO
</pre>
</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2567827"></a>Using <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">perl</strong></span></span> instead of <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span></h4></div></div></div><p>
Instead of <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> you might want to use something else like
<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">perl</strong></span></span>.
<pre class="screen">
<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">perl</strong></span></span> -p -e 's/<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>REGEXP</code></em></span>/<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>REPLACEMENT</code></em></span>/<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="replaceable"><em class="replaceable"><code>FLAGS</code></em></span>'
</pre>
But some details are different in <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">perl</strong></span></span>. Note that where
<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> needed "\(" and "\)" <span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">perl</strong></span></span>
requires the simpler "(" and ")" without preceding '\'. Example:
<pre class="screen">
<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">sed</strong></span></span> 's/\(.*\)/\U\1/'
<span xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" class="command"><span><strong class="command">perl</strong></span></span> -p -e 's/(.*)/\U\1/'
</pre>
</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2567900"></a>Order Of Preprocessor Execution</h3></div></div></div><p>
The data is piped through all internal and external preprocessors in the
following order:
</p><div class="itemizedlist"><ul type="disc"><li><p>Normal preprocessor,</p></li><li><p>Line-Matching-Preprocessor,</p></li><li><p>Ignore case (conversion to uppercase),</p></li><li><p>Detection of C/C++ comments,</p></li><li><p>Ignore numbers,</p></li><li><p>Ignore white space</p></li></ul></div><p>
The data after the normal preprocessor will be preserved for display and merging. The
other operations only modify the data that the line-matching-diff-algorithm sees.
</p><p>
In the rare cases where you use a normal preprocessor note that
the line-matching-preprocessor sees the output of the normal preprocessor as input.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2567963"></a>Warning</h3></div></div></div><p>
The preprocessor-commands are often very useful, but as with any option that modifies
your texts or hides away certain differences automatically, you might accidentally overlook
certain differences and in the worst case destroy important data.
</p><p>
For this reason during a merge if a normal preprocessor-command is being used <span class="application">KDiff3</span>
will tell you so and ask you if it should be disabled or not.
But it won't warn you if a Line-Matching-Preprocessor-command is active. The merge will not complete until
all conflicts are solved. If you disabled "Show White Space" then the differences that
were removed with the Line-Matching-Preprocessor-command will also be invisible. If the
Save-button remains disabled during a merge (because of remaining conflicts), make sure to enable
"Show White Space". If you don't wan't to merge these less important differences manually
you can select "Choose [A|B|C] For All Unsolved White space Conflicts" in the Merge-menu.
</p></div></div><div style="background-color: #white; color: black; margin-top: 20px; margin-left: 20px; margin-right: 20px;"><div style="position: absolute; left: 20px;"><a accesskey="p" href="options.html">Prev</a></div><div style="position: absolute; right: 20px;"><a accesskey="n" href="dirmerge.html">Next</a></div><div align="center"><a accesskey="h" href="index.html">Home</a></div></div><div style="background-color: #white; color: black; margin-left: 20px; margin-right: 20px;"><div class="navLeft">Options </div><div class="navRight"> Directory Comparison and Merge with <span class="application">KDiff3</span></div><div class="navCenter"><a accesskey="u" href="documentation.html">Up</a></div></div><br><br><div class="bannerBottom" style="background-image: url(help:/common/bottom-middle.png); background-repeat: x-repeat; width: 100%; height: 100px; bottom:0px;"><div class="BannerBottomRight"><img src="help:/common/bottom-right.png" style="margin: 0px" alt=""></div><div class="bannerBottomLeft"><img src="help:/common/bottom-left.png" style="margin: 0px;" alt=""></div><div id="comments" style="position:relative; top: 5px; left: 1em; height:85px; width: 50%; color: #cfe1f6"><p>Would you like to make a comment or contribute an update to this page?<br>
Send feedback to the <a href="mailto:kde-docs@kdemail.net" style="background:transparent; color:#cfe1f6; text-decoration: underline;">KDE Docs Team</a></p></div></div></body></html>