'\" t
.\" Automatically generated by Pandoc 3.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "zograscope" "7" "April 02, 2023" "" ""
.hy
.SH NAME
.PP
\f[I]zograscope\f[R] is a collection of source-processing tools spawned
out of syntax-aware diffing.
.PP
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.
.SH LANGUAGE SUPPORT
.PP
.TS
tab(@);
lw(9.9n) lw(60.1n).
T{
Language
T}@T{
Status
T}
_
T{
C
T}@T{
C11 and earlier with common extensions, but without K&R syntax
T}
T{
C++
T}@T{
C++14 and earlier with common extensions
T}
T{
Bash
T}@T{
Not targeting a specific version
T}
T{
GNU Make
T}@T{
Most of the syntax
T}
T{
Lua
T}@T{
Version 5.4
T}
.TE
.SS C
.PP
The exact grammar is that of C11 with extensions implemented in popular
compilers and additional extensions needed to allow processing of code
with macros.
.PP
Note the following:
.IP \[bu] 2
old K&R style of function declarations isn\[cq]t parsed (there might be
a workaround for it, but this syntax is deprecated either way)
.IP \[bu] 2
preprocessor directives aren\[cq]t tokenized according to language rules
yet, but their contents is diffed
.IP \[bu] 2
extensive use of macros in unusual places might not be parsed (this
probably won\[cq]t change)
.PP
Other than that code in C89, C99, C11 and GNU-versions of C language
should be recognized.
.SS C++
.PP
C++ support relies on external application called [srcml][srcml] and
requires it to be installed in binary form (not necessary during build).
.PP
Reported standard version supported by \f[V]srcml\f[R] is C++14, so all
previous ones should work too.
Although their parser doesn\[cq]t handle all language constructs equally
well, it\[cq]s seems to be good enough, especially for a ready to use
parser that wasn\[cq]t that hard to integrate.
.PP
Note the following:
.IP \[bu] 2
the tuning of comparison is in progress and will be refined over time
.SS Bash
.PP
The source of the grammar doesn\[cq]t explicitly specify the version.
.SS GNU Make
.PP
It\[cq]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.
.PP
Yet parser is capable of processing quite complicated examples of
Makefiles (like the one used in this project or generated by
\f[V]automake\f[R]) which contain many features most people don\[cq]t
know exist.
It\[cq]s definitely not 100%, but 90% or even more of all existing
Makefiles out there should be parsed.
.PP
Note the following:
.IP \[bu] 2
the comparison might not produce best results on Makefiles as it needs
some tuning, this should happen over time (Makefiles aren\[cq]t changed
that often)
.SS Lua
.PP
Note the following:
.IP \[bu] 2
non-5.4 versions should work, but can produce worse results (however,
syntax is normally backward compatible so this shouldn\[cq]t happen
often)
.SS Other
.PP
More languages should be added in the future, maybe with external
parsers that are capable of preserving all information about the source
code.
.SH CONFIGURATION
.PP
Configuration is done per directory tree (\[lq]root\[rq]) which is the
closes parent (or current directory) that contains \f[V].zs/\f[R]
directory.
The \f[V].zs/\f[R] directory contains files which define how contents of
the root is to be processed.
Settings from multiple nested roots are not combined.
.SS \f[V].zs/exclude\f[R] file
.PP
A \f[V].gitignore\f[R]-like (or \f[V].git/info/exclude\f[R]-like) file
that lists paths relative to the root.
The purpose is to exclude uninteresting files (automatically generated,
third-party or otherwise).
\f[V].zs/exclude\f[R] is used by tools that search for files
automatically and doesn\[cq]t prevent the use of the same files when
they are specified explicitly.
.PP
The following kinds of entries are recognized:
.IP \[bu] 2
empty lines, which are ignored
.IP \[bu] 2
lines that start with a \f[V]#\f[R] (comments), which are ignored
.IP \[bu] 2
lines that end with \f[V]/\f[R] match only directories, the \f[V]/\f[R]
is stripped and line processing continues
.IP \[bu] 2
lines without \f[V]/\f[R] are treated as shell-like globs against
filename which apply at any directory level and define paths whose
processing should be skipped
.IP \[bu] 2
lines that start with \f[V]!\f[R] define exception from rules that
precede them, you can\[cq]t undo exclusion of files in excluded
directories, for the purpose of this discussion the \f[V]!\f[R] is
stripped and line processing continues
.IP \[bu] 2
lines that start with \f[V]/\f[R] always match paths instead of filename
and provide a way to specify files to be ignored only in the root,
otherwise they are processed as specified in the next item
.IP \[bu] 2
other lines are treated as shell-like globs against paths relative to
the root (leading \f[V]/\f[R] is allowed, but has no effect other than
changing type of a match) which define paths whose processing should be
skipped
.PP
No way to escape leading \f[V]#\f[R] and \f[V]!\f[R] or a newline at the
moment.
.PP
Globs support the following: \f[V][{char-class}]\f[R],
\f[V][!{char-class}]\f[R], \f[V][\[ha]{char-class}]\f[R], \f[V]?\f[R]
(doesn\[cq]t match \f[V]/\f[R]), \f[V]*\f[R] (matches any (including
zero) number of characters except for \f[V]/\f[R]) and
\f[V]\[rs]{char}\f[R] (matches literal \f[V]{char}\f[R]).
.PP
Example:
.IP
.nf
\f[C]
# .zs/exclude

# automatically generated sources
src/c/c11-lexer.gen.cpp
src/c/c11-parser.gen.cpp
src/make/*.gen.*

# Qt-produced sources
ui_*.h
moc_*.cpp
moc_*.h

# file in root
/config.h
\f[R]
.fi
.SS \f[V].zs/attributes\f[R] file
.PP
Borrowing from the \f[V]git\f[R] project here again.
This file consists of lines matching paths to attributes.
Lines are trimmed before being processed.
.PP
Empty lines and comments work like in \f[V].zs/excludes\f[R] file, all
other lines follow this pattern:
.IP
.nf
\f[C]
exclude-expr [attr1=value1 [attr2=value2 [...]]]
\f[R]
.fi
.PP
Expressions that define exceptions (start with \f[V]!\f[R]) are
recognized but ignored to keep syntax consistent between different
files, which basically makes them another type of comments.
.PP
Each line of the file is visited in top down order and attributes from
every matching entry are merged with the current state.
Hierarchy of configuration values:
.IP "1." 3
Default values (lowest priority)
.IP "2." 3
Attributes
.IP "3." 3
Command-line parameters (highest priority)
.PP
Supported attributes:
.IP \[bu] 2
\f[V]lang\f[R]
.PD 0
.P
.PD
Default: \[lq]\[lq]
.PD 0
.P
.PD
Those accepted by \f[V]--lang\f[R] command-line option: bash, c, cxx,
make, lua
.IP \[bu] 2
\f[V]tab-size\f[R]
.PD 0
.P
.PD
Default: 4
.PD 0
.P
.PD
Value should be an integer that\[cq]s greater than zero
.PP
Unknown attributes are ignored.
.PP
Example:
.IP
.nf
\f[C]
# .zs/attributes

*.c tab-size=8
*.h tab-size=8 lang=c
tab-2.[ch] tab-size=2

# any.c has tab-size=8
# tab-2.c has tab-size=2
# tab-2.h has tab-size=2 lang=c
# any.h has tab-size=8 lang=c
# any.cpp has tab-size=4
\f[R]
.fi
.SH INVOCATION
.PP
All tools have common and specific command-line arguments.
Tool-specific arguments are described on the page of the tool, common
ones are below.
.PP
\f[V]-h\f[R], \f[V]--help\f[R]
.PD 0
.P
.PD
print help message
.PP
\f[V]--dry-run\f[R]
.PD 0
.P
.PD
parse and exit
.PP
\f[V]--debug[=g]\f[R]
.PD 0
.P
.PD
enable debugging of grammar (\f[V]g\f[R] flag) and/or stree (\f[V]s\f[R]
flag)
.PP
\f[V]--dump[=t]\f[R]
.PD 0
.P
.PD
display tree (\f[V]t\f[R] flag) and/or stree (\f[V]s\f[R] flag)
.PP
\f[V]--time-report\f[R]
.PD 0
.P
.PD
report time spent on different activities
.PP
\f[V]--color\f[R]
.PD 0
.P
.PD
force colorization of output
.PP
\f[V]--lang\f[R] \f[I]name\f[R]
.PD 0
.P
.PD
force specific language (\f[V]bash\f[R], \f[V]c\f[R], \f[V]cxx\f[R],
\f[V]make\f[R], \f[V]lua\f[R]) and disable auto-detection
.PP
\f[V]--no-pager\f[R]
.PD 0
.P
.PD
never spawn a pager for output
.SH BEHAVIOUR
.SS Pager
.PP
By default when output is a terminal (not the case when invoked by Git),
\f[V]less\f[R] is spawn if output is about the size of the screen.
Use \f[V]--no-pager\f[R] to change the behaviour.
.SS Language detection
.PP
By default language is auto-detected based on file name.
When name is not recognized the file is parsed as C.
.SH TOOLS
.PP
\f[B]zs-diff\f[R](1)
.PP
A terminal-based syntax-aware diff.
.PP
\f[B]zs-find\f[R](1)
.PP
Grep-like tool that finds elements of source code structure.
.PP
\f[B]zs-gdiff\f[R](1)
.PP
A Qt5 GUI version of syntax-aware diff.
.PP
\f[B]zs-hi\f[R](1)
.PP
Simple syntax highlighter for xterm-256color palette.
.PP
\f[B]zs-stats\f[R](1)
.PP
Counter of lines of code.
.PP
\f[B]zs-tui\f[R](1)
.PP
TUI interface with underdefined scope of functionality.
.SH AUTHORS
xaizek <xaizek@posteo.net>.