xaizek / zograscope (License: AGPLv3 only) (since 2018-12-07)
Mainly a syntax-aware diff that also provides a number of additional tools.
<root> / README.md (3009911b2538d84ec217cfa20ce9658607dbf1ac) (7,084B) (mode 100644) [raw]
**zograscope**, _2017 - 2019_

![Screenshot](data/examples/c/screenshot.png)

**Clone recursively, there are submodules:**

```bash
git clone --recursive https://github.com/xaizek/zograscope.git
```

1. [Description](#description)
2. [Tools](#tools)
3. [Building and Installing](#building-and-installing)
4. [Documentation](#documentation)
5. [License](#license)
6. [Credits](#credits)

## Name ##

"A zograscope is an optical device for enhancing the sense of depth perception
from a flat picture." ([wiki][wiki-zograscope])

## Description ##

`zograscope` is built around syntax-aware diff and includes a number of
additional tools.

The nature of syntax-aware diff requires knowledge of structure of the code,
which can be used to build other simple tools that can benefit from this
information.  Competing with real language front-ends in the level of accuracy
is not possible, but making some things that are one step further than regular
text-processing utilities seems feasible and the result might be even more
practical than some of the more elaborate tools which end up requiring
complicated setup process.

### Status ###

The project is work in progress, but is useful in its current state.

Code isn't perfect and isn't extensively documented as initial version was more
of an experiment, but this situation gets better.

### Supported languages ###

| Language  |  Status                                                          |
|-----------|------------------------------------------------------------------|
|  C        |  C11 and earlier with common extensions, but without K&R syntax  |
|  C++      |  C++14 and earlier with common extensions                        |
|  GNU Make |  Most of the syntax                                              |

#### C ####

The exact grammar is that of C11 with extensions implemented in popular
compilers and additional extensions needed to allow processing of code with
macros.

Note the following:
 * old K&R style of function declarations isn't parsed (there might be a
   workaround for it, but this syntax is deprecated either way)
 * preprocessor directives aren't tokenized according to language rules yet,
   but their contents is diffed
 * extensive use of macros in unusual places might not be parsed (this probably
   won't change)

Other than that code in C89, C99, C11 and GNU-versions of C language should be
recognized.

#### C++ ####

C++ support relies on external application called [srcml][srcml] and requires it
to be installed in binary form (not necessary during build).

Reported standard version supported by `srcml` is C++14, so all previous ones
should work too.  Although their parser doesn't handle all language constructs
equally well, it's seems to be good enough, especially for a ready to use parser
that wasn't that hard to integrate.

Note the following:
 * the tuning of comparison is in progress and will be refined over time

#### GNU Make ####

It's hard to measure level of support in case of GNU Make, because there seem to
be no reference for the syntax itself apart from documentation, which is not
concise.

Yet parser is capable of processing quite complicated examples of Makefiles
(like the one used in this project or generated by `automake`) which contain
many features most people don't know exist.  It's definitely not 100%, but 90%
or even more of all existing Makefiles out there should be parsed.

Note the following:
 * the comparison might not produce best results on Makefiles as it needs
   some tuning, this should happen over time (Makefiles aren't changed that
   often)

#### Other ####

More languages should be added in the future, maybe with external parsers that
are capable of preserving all information about the source code.

## Tools ##

### [zs-diff](tools/diff/README.md) ###

A terminal-based syntax-aware diff.

### [zs-find](tools/find/README.md) ###

Grep-like tool that finds elements of source code structure.

### [zs-gdiff](tools/gdiff/README.md) ###

A Qt5 GUI version of syntax-aware diff.

### [zs-hi](tools/hi/README.md) ###

Simple syntax highlighter for xterm-256color palette.

### [zs-stats](tools/stats/README.md) ###

Counter of lines of code.

### [zs-tui](tools/tui/README.md) ###

TUI interface with underdefined scope of functionality.

## Building and Installing ##

```bash
# if Qt5 is available (use `qmake` if it corresponds to Qt5 on your machine)
echo 'QT5_PROG := qmake-qt5' >> config.mk
# if libgit2 is present
echo 'HAVE_LIBGIT2 := yes'   >> config.mk
# if cursesw is present
echo 'HAVE_CURSESW := yes'   >> config.mk

make release check
```

This will build release version and run tests.  The executables will be named
`release/zs-*`.

There is no data, so just making them available in the `$PATH` will work.
However, it's possible to install conventionally (`/usr` prefix by default):

```
make install
```

`DESTDIR` and `PREFIX` can be set to modify destination location.  On invoking
`make uninstall` same values of these values should be specified.

### Dependencies ###

* [GNU Make][make]
* C++11-capable compiler (GCC 4.9 has some issues, GCC 5.3 works fine)
* [flex][flex]
* [GNU Bison][bison] v3+
* [Boost][boost], tested with 1.59, but older versions might work too
* (optional, run-time, for C++) [srcml][srcml]
* (optional, for `gdiff` tool) [qt5][qt5]
* (optional, for `gdiff` tool) [libgit2][libgit2]
* (optional, for `tui` tool) [curses][curses] with support of wide characters

## Documentation ##

At the moment there is only `--help` option.

## License ##

![AGPLv3](data/agplv3.png)

Version 3 of the GNU Affero General Public License.

## Credits ##

[dtl library][dtl] is used for finding edit distance.

[pmr implementation][pmr] from C++17 with a small addition is employed for
custom allocators.

[TinyXML2][tinyxml2] is used for parsing XML.

[Catch2][catch] is used for tests.

### References ###

[Change Distilling: Tree Differencing for Fine-Grained Source Code Change
Extraction][cd].
Beat Fluri, Michael Würsch, Martin Pinzger, and Harald C. Gall.
2007.

[Change Detection in Hierarchically Structured Information][hier].
Sudarshan Chawathe, Hector Garcia-molina and Jennifer Widom.
1996.

[Simple fast algorithms for the editing distance between trees and related
problems][ted].
Kaizhong Zhang and Dennis Shasha.
1989.

[wiki-zograscope]: https://en.wikipedia.org/wiki/Zograscope

[make]: https://www.gnu.org/software/make/
[flex]: https://github.com/westes/flex
[bison]: https://www.gnu.org/software/bison/
[boost]: http://www.boost.org/
[srcml]: http://www.srcml.org/
[qt5]: https://www.qt.io/
[libgit2]: https://libgit2.org/
[curses]: https://en.wikipedia.org/wiki/Curses_(programming_library)

[dtl]: https://github.com/cubicdaiya/dtl
[pmr]: https://github.com/phalpern/CppCon2017Code
[tinyxml2]: https://github.com/leethomason/tinyxml2
[catch]: https://github.com/catchorg/Catch2

[cd]: http://www.merlin.uzh.ch/publication/show/2531
[hier]: http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.48.9224
[ted]: http://citeseer.ist.psu.edu/viewdoc/summary?doi=10.1.1.460.5601
Hints

Before first commit, do not forget to setup your git environment:
git config --global user.name "your_name_here"
git config --global user.email "your@email_here"

Clone this repository using HTTP(S):
git clone https://code.reversed.top/user/xaizek/zograscope

Clone this repository using ssh (do not forget to upload a key first):
git clone ssh://rocketgit@code.reversed.top/user/xaizek/zograscope

You are allowed to anonymously push to this repository.
This means that your pushed commits will automatically be transformed into a pull request:
... clone the repository ...
... make some changes and some commits ...
git push origin master