xaizek / zograscope

Mainly a syntax-aware diff that also provides a number of additional tools.

zograscope, 2017 - 2024

Clone recursively, there are submodules:

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

1. Description (Status; Supported languages; Configuration)
2. Tools
3. Building and Installing (Dependencies)
4. Documentation
5. License
6. Credits (References)

Name

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

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.

Documentation

See the manual page.

Tools

zs-diff

A terminal-based syntax-aware diff.

zs-find

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

zs-gdiff

A Qt5 GUI version of syntax-aware diff.

zs-hi

Simple syntax highlighter for xterm-256color palette.

zs-stats

Counter of lines of code.

zs-tui

TUI interface with underdefined scope of functionality.

Building and Installing

# 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 libsrcml is present
echo 'HAVE_LIBSRCML := 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
• C++11-capable compiler (GCC 4.9 has some issues, GCC 5.3 works fine)
• flex
• GNU Bison v3+
• Boost, tested with 1.58, but older versions might work too
• (optional, run- or build-time, for C++) srcml (v0.9.5 and v1.0.0 were tested)
• (optional, for gdiff tool) qt5
• (optional, for gdiff tool) libgit2
• (optional, for tui tool) curses with support of wide characters
• (optional) pandoc for regenerating man pages

For Debian-based distributions

If you are using Debian or one of its derivatives, you can install the dependencies as follows:

# install make and build tools
sudo apt install -y build-essential
# installing dependencies
sudo apt install -y libboost-filesystem-dev libboost-iostreams-dev
sudo apt install -y libboost-program-options-dev libboost-system-dev
sudo apt install -y libarchive13
sudo apt install -y bison flex
# installing srcml
wget http://131.123.42.38/lmcrs/beta/srcML-Ubuntu18.04.deb
sudo apt install ./srcML-Ubuntu18.04.deb

You can also check out the CI build script in case dependencies change in the future.

License

Version 3 of the GNU Affero General Public License.

Credits

dtl library is used for finding edit distance.

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

TinyXML2 is used for parsing XML.

tree-sitter is used for parsing of some languages.

Catch2 is used for tests.

References

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

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

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

zograscope's Issues

Addition of a build system generator

I suggest to reuse a higher level build system than your current make script so that powerful checks for software features will become easier.

• CMake
• Autotools

Makefile parser error: syntax error, unexpected ASSIGN_OP, expecting ':' or WS

../nuttx/libs/libnx/Makefile:229:55: parse error: syntax error, unexpected ASSIGN_OP, expecting ':' or WS
Failed to parse: ../nuttx/libs/libnx/Makefile

ifeq ($(CONFIG_NXFONT_TOM_THUMB_4X6),y)
	$(Q) $(MAKE) -C nxfonts -f Makefile.sources TOPDIR=$(TOPDIR) NXFONTS_FONTID=43 EXTRADEFINES=$(EXTRADEFINES)
endif

Javascript support

Hi, I'm on the lookout for a patch tool whose intelligence stretches beyond linenumbers, that can be run in a post-install script.

Zograscope looks interesting. Are there any plans on adding javascript support?

Makefile parser error: syntax error, unexpected include, expecting WS or NL or LEADING_TAB

../nuttx/drivers/wireless/spirit/Make.defs:41:39: parse error: syntax error, unexpected include, expecting WS or NL or LEADING_TAB
Failed to parse: ../nuttx/drivers/wireless/spirit/Make.defs

ifeq ($(CONFIG_WL_SPIRIT),y)

# Include Spirit library support

include wireless$(DELIM)spirit$(DELIM)lib$(DELIM)Make.defs
include wireless$(DELIM)spirit$(DELIM)include$(DELIM)Make.defs
include wireless$(DELIM)spirit$(DELIM)drivers$(DELIM)Make.defs

endif

Makefile parser error: syntax error, unexpected ), expecting CHARS or VAR or $(

../nuttx/arch/sim/src/Makefile:268:9: parse error: syntax error, unexpected ), expecting CHARS or VAR or $(
Failed to parse: ../nuttx/arch/sim/src/Makefile

Points to this:

ifeq ($())CONFIG_SIM_CYGWIN_DECORATED),y)

Installation instructions

Hi,
This project looks great and I'd like to try it out. However, I'm new to C++ and having some difficulties installing the program.

Could you please provide instructions how to get the dependencies installed (e.g., Boost)?

Build fails in macOS

Fresh clone and I get this:

➜  zograscope git:(master) make
c++ -c -I./src/ -std=c++11 -Wall -Wextra -MMD -Isrc/ -Ithird-party/ -DYYDEBUG -Og -g tools/diff/diff.cpp -o tools/diff/diff.o
error: invalid integral value 'g' in '-Og'
error: invalid integral value 'g' in '-Og'

Compiler info:

➜  zograscope git:(master) clang --version
Apple LLVM version 8.0.0 (clang-800.0.42.1)
Target: x86_64-apple-darwin16.7.0
Thread model: posix
InstalledDir: /Applications/Xcode81.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin

Makefile parsing fails

Just tried to highlight a Makefile with zs-hi and get a parsing error.

➜  zograscope git:(master) ./zs-hi --lang make ../nuttx/arch/arm/src/Makefile
../nuttx/arch/arm/src/Makefile:168:43: parse error: syntax error, unexpected ':', expecting NL or LEADING_TAB
Failed to parse: ../nuttx/arch/arm/src/Makefile

Makefile: https://gist.github.com/tritao/50b838d940ff4a5c753361e9c513e03f

Makefile parser error: syntax error, unexpected SLIT

../nuttx/arch/avr/src/avr/Toolchain.defs:92:11: parse error: syntax error, unexpected SLIT
Failed to parse: ../nuttx/arch/avr/src/avr/Toolchain.defs

Points to this:

  $(error "No valid CONFIG_ARCH_CHIP_ set in the configuration")

Full file: https://gist.github.com/tritao/352281e9dee9d8832c51772378b92102

I get the same reported error message for this as well:

LIBGCC = ${shell "$(CC)" $(ARCHCPUFLAGS) -print-libgcc-file-name}

Probably the same issue.

Another instance:

  CUSTOM_DIR = $(patsubst "%",%,$(CONFIG_ARCH_BOARD_CUSTOM_DIR))

reserved identifier violation

I would like to point out that an identifier like “ZOGRASCOPE__HIGHLIGHTER_HPP__” does not fit to the expected naming convention of the C++ language standard.
Would you like to adjust your selection for unique names?

Build fails with linker error, due to bad positioning of LD_FLAGS

Hi,
on my machine make did not run through. I had to move $(LD_FLAGS) to the end of the line on line 119 in file Makefile, then it works.
Cheers,
Matthias