16diff Module

16.1Overview

The diff module provices measures to detect differences between texts. To utilize it, import the diff module using import function.

Below is an example to show differences between files file1.txt and file2.txt:

diff.compose(stream('file1.txt'), stream('file2.txt')).render(sys.stdout)

16.2Module Function

The diff module provides following methods:

diff.compose(src1, src2):[icase,sync] {block?}

Extracts differences between two sets of line sequence and returns diff.diff@line instance that contains the difference information.

You can specify a value of string, stream, iterator or list for the argument src1 and src2. In the result, the content of src1 is referred to as an "original" one and that of src2 as a "new" one.

Below is an example to compare between two strings:

str1 = '...'
str2 = '...'
result = diff.compose(str1, str2)

Below is an example to compare between two files:

file1 = stream('file1.txt')
file2 = stream('file2.txt')
result = diff.compose(file1, file2)

Below is an example to compare between two iterators:

chars1 = '...'.each()
chars2 = '...'.each()
result = diff.compose(chars1, chars2)

Below is an example to compare between a file and a string:

file = stream('file.txt')
str = '...'
result = diff.compose(file, str)

If block is specified, it would be evaluated with a block parameter |d:diff.diff@line|, where d is the created instance. In this case, the block's result would become the function's returned value.

If attribute :icase is specified, it wouldn't distinguish upper and lower case of characters.

diff.compose@char(src1:string, src2:string):[icase] {block?}

Extracts differences between two strings and returns diff.diff@line instance that contains the difference information.

If block is specified, it would be evaluated with a block parameter |d:diff.diff@char|, where d is the created instance. In this case, the block's result would become the function's returned value.

If attribute :icase is specified, it wouldn't distinguish upper and lower case of characters.

16.3diff.diff@line Class

16.3.1Overview

The diff.diff@line instance is created by function diff.compose() and provides information about differences between two texts by lines.

16.3.2Property

The diff.diff@line instance has following properties:

diff.diff@line#distance … number [read-only]

The distance between the texts. Zero means that they are identical each other.

diff.diff@line#edits … iterator [read-only]

An iterator that returns diff.edit@line instances stored in the result.

diff.diff@line#nlines@new … number [read-only]

Number of lines in the "original" text.

diff.diff@line#nlines@org … number [read-only]

Number of lines in the "new" text.

16.3.3Method

The diff.diff@line class provides following methods:

diff.diff@line#eachhunk(format?:symbol, lines?:number) {block?}

Creates an iterator that returns diff.hunk@line instance stored in the result.

The argument format takes one of the symbols that specifies the hunk format:

`normal .. Normal format (not supported yet).
`context .. Context format (not supported yet).
`unified .. Unified format. This is the default.

The argument lines specifies a number of common lines appended before and after different lines

In default, this returns an iterator as its result value. Specifying the following attributes would customize the returned value:

:iter .. An iterator. This is the default behavior.
:xiter .. An iterator that eliminates nil from its elements.
:list .. A list.
:xlist .. A list that eliminates nil from its elements.
:set .. A list that eliminates duplicated values from its elements.
:xset .. A list that eliminates duplicated values and nil from its elements.

See the chapter of Mapping Process in Gura Language Manual for the detail.

If a block is specified, it would be evaluated repeatingly with block parameters |value, idx:number| where value is the iterated value and idx the loop index starting from zero. In this case, the last evaluated value of the block would be the result value. If one of the attributes listed above is specified, an iterator or a list of the evaluated value would be returned.

diff.diff@line#render(out?:stream:w, format?:symbol, lines?:number) {block?}

Renders diff result to the specified stream.

If the argument out is omitted, this method returns a string of the rendered text. Otherwise, it returns nil.

The argument format takes one of the symbols that specifies the rendering format:

`normal .. Normal format (not supported yet).
`context .. Context format (not supported yet).
`unified .. Unified format. This is the default.

The argument lines specifies a number of common lines appended before and after different lines.

16.4diff.hunk@line Class

16.4.1Overview

The diff.hunk@line instance provides information about a hunk.

16.4.2Property

The diff.hunk@line instance has following properties:

diff.hunk@line#diff_at_char … diff.diff@char [read-only]

diff.hunk@line#edits … iterator [read-only]

An iterator that returns diff.edit@line instances stored in the hunk.

diff.hunk@line#lineno@new … number [read-only]

Top line number of the "new" text covered by the hunk.

diff.hunk@line#lineno@org … number [read-only]

Top line number of the "original" text covered by the hunk.

diff.hunk@line#nlines@new … number [read-only]

Number of lines in the "new" text covered by the hunk.

diff.hunk@line#nlines@org … number [read-only]

Number of lines in the "original" text covered by the hunk.

diff.hunk@line#type … symbol [read-only]

16.4.3Method

The diff.hunk@line class provides following methods:

diff.hunk@line#print(out?:stream):void {block?}

Prints the content of the diff.hunk instance to the specified stream.

16.5diff.edit@line Class

16.5.1Overview

The diff.edit@line provides information about an edit operation.

16.5.2Property

The diff.edit@line instance has following properties:

diff.edit@line#lineno@new … number [read-only]

Lop line number of the "new" text correspond to the edit.

diff.edit@line#lineno@org … number [read-only]

Line number of the "original" text correspond to the edit.

diff.edit@line#mark@context … string [read-only]

diff.edit@line#mark@normal … string [read-only]

diff.edit@line#mark@unified … string [read-only]

A mark string that appears on the top of each line in Unified format.

diff.edit@line#source … string [read-only]

A source text.

diff.edit@line#type … symbol [read-only]

Edit operation:

`copy .. Copy the line.
`add .. Add the line.
`delete .. Delete the line.

diff.edit@line#unified … string [read-only]

A composed string in Unified format.

16.5.3Method

The diff.edit@line class provides following methods:

diff.edit@line#print(out?:stream):void {block?}

Prints the content of the diff.edit instance to the specified stream.

16.6diff.diff@char Class

16.6.1Overview

The diff.diff@char instance is created by function diff.compose@char() and provides information about differences between two texts by characters.

16.6.2Property

The diff.diff@char instance has following properties:

diff.diff@char#distance … number [read-only]

The distance between the texts. Zero means that they are identical each other.

diff.diff@char#edits … iterator [read-only]

An iterator that returns diff.edit@char instances stored in the result.

diff.diff@char#edits@new … iterator [read-only]

An iterator that returns diff.edit@char instances that are applied to the "new" string.

diff.diff@char#edits@org … iterator [read-only]

An iterator that returns diff.edit@char instances that are applied to the "original" string.

16.7diff.edit@char Class

16.7.1Overview

The diff.edit@char provides information about an edit operation.

16.7.2Property

The diff.edit@char instance has following properties:

diff.edit@char#mark@context … string [read-only]

diff.edit@char#mark@normal … string [read-only]

diff.edit@char#mark@unified … string [read-only]

A mark string that appears on the top of each line in Unified format.

diff.edit@char#source … string [read-only]

A source text.

diff.edit@char#type … symbol [read-only]

Edit operation:

`copy .. Copy the line.
`add .. Add the line.
`delete .. Delete the line.

16.8Thanks

This module uses dtl (Diff Template Library) which is distributed in the following site:

https://code.google.com/p/dtl-cpp/