<?xml version="1.0" encoding="UTF-8"?>
<!--
 *
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2010 - 2011 - DIGITEO - Michael Baudin
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="assert_checkfilesequal" xml:lang="en">
    <refnamediv>
        <refname>assert_checkfilesequal</refname>
        <refpurpose>Check that two files are equal.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            flag = assert_checkfilesequal ( filecomp , fileref )
            flag = assert_checkfilesequal ( filecomp , fileref , compfun )
            [flag,errmsg] = assert_checkfilesequal ( ... )

        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Parameters</title>
        <variablelist>
            <varlistentry>
                <term>filecomp :</term>
                <listitem>
                    <para> a 1-by-1 matrix of strings, the computed file.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>fileref :</term>
                <listitem>
                    <para> a 1-by-1 matrix of strings, the reference file.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>compfun :</term>
                <listitem>
                    <para> a function or a list, the comparison function (default compfun = []). If no comparison function is used, the equality operator "==" is used. See below for details.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>flag :</term>
                <listitem>
                    <para> a 1-by-1 matrix of boolean, %t if computed is close to expected, %f if not</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>errmsg :</term>
                <listitem>
                    <para> a 1-by-1 matrix of strings, the error message. If flag==%t, then errormsg=="". If flag==%f, then errmsg contains the error message.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            Performs silently if the files are equal.
            Generates an error if filecomp or fileref do not exist.
            Generates an error if the content of the files are not equal.
        </para>
        <para>
            If the files are not equal,
            <itemizedlist>
                <listitem>
                    <para>if the errmsg output variable is not used, an error is generated,</para>
                </listitem>
                <listitem>
                    <para>if the errmsg output variable is used, no error is generated.</para>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            If the comparison function compfun is a function, it should have header areequal = compfun ( txtcomp , txtref )
            where txtcomp is the content of the computed file, txtref is the content of the reference file and areequal
            is a boolean. The areequal boolean is true if the two contents are equal.
            If compfun is a list, it should be list (cf,a1,a2,...), where cf is a comparison function,
            and the arguments a1, a2, will be automatically be appended
            as parameters when calling cf.
        </para>
        <para>
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
//
// Prepare data for the tests
// fileref1 : three lines of text.
// filecomp1 : == fileref1
// filecomp2 : <> fileref1
fileref1 = fullfile(TMPDIR,"fileref.txt");
txt1 = [
"Line #1"
"Line #2"
"Line #3"
];
fd = mopen(fileref1,"w");
mputl(txt1,fd);
mclose(fd);
filecomp1 = fullfile(TMPDIR,"filecomp1.txt");
fd = mopen(filecomp1,"w");
mputl(txt1,fd);
mclose(fd);
filecomp2 = fullfile(TMPDIR,"filecomp2.txt");
txt2 = [
"Line #1"
"Line #4"
"Line #3"
];
fd = mopen(filecomp2,"w");
mputl(txt2,fd);
mclose(fd);

// A test which pass
flag = assert_checkfilesequal ( filecomp1 , fileref1 )
[flag,errmsg] = assert_checkfilesequal ( filecomp1 , fileref1 )

// Failure: filecomp2 <> fileref1
// Error generated
flag = assert_checkfilesequal ( filecomp2 , fileref1 )
// No error generated
[flag,errmsg] = assert_checkfilesequal ( filecomp2 , fileref1 )

// Prepare data for the tests
// fileref2 == filecomp3, given that comment lines are ignored.
// fileref2 <> filecomp4, given that comment lines are ignored.
// Notice that the comments are inserted at different positions in the files:
// sometimes at the beginning, sometimes in the middle.
fileref2 = fullfile(TMPDIR,"fileref2.txt");
txt = [
"// bla 2"
"Line #1"
"// bla 2"
"Line #2"
"Line #3"
];
fd = mopen(fileref2,"w");
mputl(txt,fd);
mclose(fd);
filecomp3 = fullfile(TMPDIR,"filecomp3.txt");
txt = [
"Line #1"
"// bla 5168"
"Line #2"
"Line #3"
"// bla oups"
];
fd = mopen(filecomp3,"w");
mputl(txt,fd);
mclose(fd);
filecomp4 = fullfile(TMPDIR,"filecomp4.txt");
txt = [
"// bla 3"
"Line #1"
"Line #4"
"// bla 5168"
"Line #3"
"// bla oups"
];
fd = mopen(filecomp4,"w");
mputl(txt,fd);
mclose(fd);

// A test with a comparison function which ignores comment lines.
function otxt = myfilter ( itxt )
nr = size(itxt,"r")
// This is the pattern for a comment line of the form "// blabla"
pattern = "/\/\/.*/"
k = 1
for i = 1 : nr
start = regexp(itxt(i),pattern)
if ( start == [] ) then
otxt(k) = itxt(i)
k = k + 1
end
end
endfunction
function areequal = mycompfun ( ctxt , etxt )
ctxt = myfilter ( ctxt )
etxt = myfilter ( etxt )
areequal = ( ctxt == etxt )
endfunction
//
// A test which pass
[flag,errmsg] = assert_checkfilesequal ( filecomp3 , fileref2 , mycompfun )
// A test which fails
[flag,errmsg] = assert_checkfilesequal ( filecomp4 , fileref2 , mycompfun )

   ]]></programlisting>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revdescription>Function introduced
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
