Code Vault

xaizek / zograscope (License: AGPLv3 only) (since 2018-12-07)

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

Clone URLs: https://code.reversed.top/user/xaizek/zograscope ssh://rocketgit@code.reversed.top/user/xaizek/zograscope

Commit 308a6fcdcc5e9bdc9aa1a062c8984941a9eda689

Manual pages

Finally, moved pieces of READMEs and --help into manual pages, which can
also be read in Markdown.

Author: xaizek
Author date (UTC): 2022-07-19 15:38
Committer name: xaizek
Committer date (UTC): 2022-07-19 17:22
Parent(s): aa631e5aca26faf980bb508d3fd1928080040ba3
Signing key: 99DC5E4DB05F6BE2
Tree: 05e523673453d43f548db16d6661374cb11329e4

File	Lines added	Lines deleted
Makefile	15	4
README.md	4	176
docs/zograscope.md	81	169
docs/zs-com.md	0	0
docs/zs-diff.md	122	0
docs/zs-find.md	101	0
docs/zs-gdiff.md	66	0
docs/zs-grep.md	0	0
docs/zs-hi.md	48	0
docs/zs-stats.md	28	8
docs/zs-tui.md	57	0
man/zograscope.7	372	0
man/zs-com.1	21	0
man/zs-diff.1	138	0
man/zs-find.1	207	0
man/zs-gdiff.1	78	0
man/zs-grep.1	21	0
man/zs-hi.1	64	0
man/zs-stats.1	76	0
man/zs-tui.1	97	0
tools/diff/README.md	7	65
tools/find/README.md	3	32
tools/gdiff/README.md	6	1
tools/hi/README.md	3	9
tools/stats/README.md	3	12
tools/tui/README.md	5	0
tools/tui/tui.cpp	0	18

File Makefile changed (mode: 100644) (index bb2ba08..7f5d8f3)
...	...	CXXFLAGS += -Isrc/ -Ithird-party/ $(CFLAGS)
7	7	LDFLAGS += -g -lboost_iostreams -lboost_program_options -lboost_filesystem	LDFLAGS += -g -lboost_iostreams -lboost_program_options -lboost_filesystem
8	8	LDFLAGS += -lboost_system -pthread	LDFLAGS += -lboost_system -pthread
9	9
10		INSTALL := install
	10		INSTALL := install -D
11	11	DESTDIR :=	DESTDIR :=
12	12	PREFIX := /usr	PREFIX := /usr
13	13

...	...	tools_objects += $$($1.objects)
131	131	tools_depends += $$($1.depends)	tools_depends += $$($1.depends)
132	132
133	133	all: $$($1.bin)	all: $$($1.bin)
	134		man: man/zs-$1.1
134	135
135	136	$$($1.bin): \| $(out_dirs)	$$($1.bin): \| $(out_dirs)
136	137

...	...	out_dirs := $(sort $(dir $(lib_objects) $(tools_objects) $(tests_objects)))
158	159	# processs of running other rules	# processs of running other rules
159	160	$(shell mkdir -p $(out_dirs))	$(shell mkdir -p $(out_dirs))
160	161
161		.PHONY: all check clean debug release sanitize-basic
	162		.PHONY: all man check clean debug release sanitize-basic
162	163	.PHONY: coverage reset-coverage	.PHONY: coverage reset-coverage
163	164	.PHONY: install uninstall	.PHONY: install uninstall
164	165
	166		man: man/$(NAME).7
	167		man/%.1 man/%.7: docs/%.md
	168		pandoc -V title=$* \
	169		-V section=$(shell echo -n $@ \| tail -c1) \
	170		-V app=$* \
	171		-V date="$$(date +'%B %d, %Y')" \
	172		-V author='xaizek <xaizek@posteo.net>' \
	173		-s -o $@ $<
	174
165	175	all: $(lib)	all: $(lib)
166	176
167	177	debug release sanitize-basic: all	debug release sanitize-basic: all

...	...	check: $(out_dir)/tests/tests reset-coverage
185	195	@$(out_dir)/tests/tests $(TESTS)	@$(out_dir)/tests/tests $(TESTS)
186	196
187	197	install: release	install: release
188		$(INSTALL) -d $(DESTDIR)$(PREFIX)/bin
189		$(INSTALL) $(tools_bins) $(DESTDIR)$(PREFIX)/bin
	198		$(INSTALL) -t $(DESTDIR)$(PREFIX)/bin $(tools_bins)
	199		$(INSTALL) -t $(DESTDIR)$(PREFIX)/share/man/man7/ -m 644 man/*.7
	200		$(INSTALL) -t $(DESTDIR)$(PREFIX)/share/man/man1/ -m 644 man/*.1
190	201
191	202	uninstall:	uninstall:
192	203	$(RM) $(addprefix $(DESTDIR)$(PREFIX)/bin/,$(notdir $(tools_bins)))	$(RM) $(addprefix $(DESTDIR)$(PREFIX)/bin/,$(notdir $(tools_bins)))

File README.md changed (mode: 100644) (index eb724b8..88e96a5)
...	...	The project is work in progress, but is useful in its current state.
44	44	Code isn't perfect and isn't extensively documented as initial version was more	Code isn't perfect and isn't extensively documented as initial version was more
45	45	of an experiment, but this situation gets better.	of an experiment, but this situation gets better.
46	46
47		### Supported languages ###
48
49		\| Language \| Status \|
50		\|-----------\|------------------------------------------------------------------\|
51		\| C \| C11 and earlier with common extensions, but without K&R syntax \|
52		\| C++ \| C++14 and earlier with common extensions \|
53		\| GNU Make \| Most of the syntax \|
54		\| Lua \| Version 5.3 \|
55
56		#### C ####
57
58		The exact grammar is that of C11 with extensions implemented in popular
59		compilers and additional extensions needed to allow processing of code with
60		macros.
61
62		Note the following:
63		* old K&R style of function declarations isn't parsed (there might be a
64		workaround for it, but this syntax is deprecated either way)
65		* preprocessor directives aren't tokenized according to language rules yet,
66		but their contents is diffed
67		* extensive use of macros in unusual places might not be parsed (this probably
68		won't change)
69
70		Other than that code in C89, C99, C11 and GNU-versions of C language should be
71		recognized.
72
73		#### C++ ####
74
75		C++ support relies on external application called [srcml][srcml] and requires it
76		to be installed in binary form (not necessary during build).
77
78		Reported standard version supported by `srcml` is C++14, so all previous ones
79		should work too. Although their parser doesn't handle all language constructs
80		equally well, it's seems to be good enough, especially for a ready to use parser
81		that wasn't that hard to integrate.
82
83		Note the following:
84		* the tuning of comparison is in progress and will be refined over time
85
86		#### GNU Make ####
87
88		It's hard to measure level of support in case of GNU Make, because there seem to
89		be no reference for the syntax itself apart from documentation, which is not
90		concise.
91
92		Yet parser is capable of processing quite complicated examples of Makefiles
93		(like the one used in this project or generated by `automake`) which contain
94		many features most people don't know exist. It's definitely not 100%, but 90%
95		or even more of all existing Makefiles out there should be parsed.
96
97		Note the following:
98		* the comparison might not produce best results on Makefiles as it needs
99		some tuning, this should happen over time (Makefiles aren't changed that
100		often)
101
102		#### Lua ####
103
104		Newly added (March 2021) with very little testing so far. However, the
105		language is small and simple enough to not pose much difficulties.
106
107		Note the following:
108		* non-5.3 versions might still work, albeit can produce worse results
109
110		#### Other ####
111
112		More languages should be added in the future, maybe with external parsers that
113		are capable of preserving all information about the source code.
114
115		### Configuration ###
116
117		Configuration is done per directory tree ("root") which is the closes parent (or
118		current directory) that contains `.zs/` directory. The `.zs/` directory
119		contains files which define how contents of the root is to be processed.
120		Settings from multiple nested roots are not combined.
121
122		#### `.zs/exclude` file ####
123
124		A `.gitignore`-like (or `.git/info/exclude`-like) file that lists paths relative
125		to the root. The purpose is to exclude uninteresting files (automatically
126		generated, third-party or otherwise). `.zs/exclude` is used by tools that
127		search for files automatically and doesn't prevent the use of the same files
128		when they are specified explicitly.
129
130		The following kinds of entries are recognized:
131
132		* empty lines, which are ignored
133		* lines that start with a `#` (comments), which are ignored
134		* lines that end with `/` match only directories, the `/` is stripped and line
135		processing continues
136		* lines without `/` are treated as shell-like globs against filename which apply
137		at any directory level and define paths whose processing should be skipped
138		* lines that start with `!` define exception from rules that precede them, you
139		can't undo exclusion of files in excluded directories, for the purpose of this
140		discussion the `!` is stripped and line processing continues
141		* lines that start with `/` always match paths instead of filename and provide a
142		way to specify files to be ignored only in the root, otherwise they are
143		processed as specified in the next item
144		* other lines are treated as shell-like globs against paths relative to the
145		root (leading `/` is allowed, but has no effect other than changing type of a
146		match) which define paths whose processing should be skipped
147
148		No way to escape leading `#` and `!` or a newline at the moment.
149
150		Globs support the following: `[{char-class}]`, `[!{char-class}]`,
151		`[^{char-class}]`, `?` (doesn't match `/`), `*` (matches any (including zero)
152		number of characters except for `/`) and `\{char}` (matches literal `{char}`).
153
154		Example:
155
156		```gitignore
157		# .zs/exclude
158
159		# automatically generated sources
160		src/c/c11-lexer.gen.cpp
161		src/c/c11-parser.gen.cpp
162		src/make/.gen.
163
164		# Qt-produced sources
165		ui_*.h
166		moc_*.cpp
167		moc_*.h
168
169		# file in root
170		/config.h
171		```
172
173		#### `.zs/attributes` file ####
174
175		Borrowing from the `git` project here again. This file consists of lines
176		matching paths to attributes. Lines are trimmed before being processed.
177
178		Empty lines and comments work like in `.zs/excludes` file, all other lines
179		follow this pattern:
180
181		exclude-expr [attr1=value1 [attr2=value2 [...]]]
182
183		Expressions that define exceptions (start with `!`) are recognized but ignored
184		to keep syntax consistent between different files, which basically makes them
185		another type of comments.
186
187		Each line of the file is visited in top down order and attributes from every
188		matching entry are merged with the current state. Hierarchy of configuration
189		values:
190		1. Default values (lowest priority)
191		2. Attributes
192		3. Command-line parameters (highest priority)
193
194		Supported attributes:
195
196		* `lang`\
197		Default: ""\
198		Those accepted by `--lang` command-line option: c, cxx, make, lua
199		* `tab-size`\
200		Default: 4\
201		Value should be an integer that's greater than zero
202
203		Unknown attributes are ignored.
204
205		Example:
206
207		```
208		# .zs/exclude
209
210		*.c tab-size=8
211		*.h tab-size=8 lang=c
212		tab-2.[ch] tab-size=2
	47		## Documentation ##
213	48
214		# any.c has tab-size=8
215		# tab-2.c has tab-size=2
216		# tab-2.h has tab-size=2 lang=c
217		# any.h has tab-size=8 lang=c
218		# any.cpp has tab-size=4
219		```
	49		See the [manual page](./docs/zograscope.md).
220	50
221	51	## Tools ##	## Tools ##
222	52

...	...	make install
281	111	* (optional, for `gdiff` tool) [qt5][qt5]	* (optional, for `gdiff` tool) [qt5][qt5]
282	112	* (optional, for `gdiff` tool) [libgit2][libgit2]	* (optional, for `gdiff` tool) [libgit2][libgit2]
283	113	* (optional, for `tui` tool) [curses][curses] with support of wide characters	* (optional, for `tui` tool) [curses][curses] with support of wide characters
	114		* (optional) [pandoc][pandoc] for regenerating man pages
284	115
285	116	#### For Debian-based distributions ####	#### For Debian-based distributions ####
286	117

...	...	sudo apt install ./srcML-Ubuntu18.04.deb
303	134	You can also check out the [CI build script](data/appveyor/ubuntu.sh) in case	You can also check out the [CI build script](data/appveyor/ubuntu.sh) in case
304	135	dependencies change in the future.	dependencies change in the future.
305	136
306		## Documentation ##
307
308		At the moment there is only `--help` option.
309
310	137	## License ##	## License ##
311	138
312	139	![AGPLv3](data/agplv3.png)	![AGPLv3](data/agplv3.png)

...	...	Kaizhong Zhang and Dennis Shasha.
352	179	[qt5]: https://www.qt.io/	[qt5]: https://www.qt.io/
353	180	[libgit2]: https://libgit2.org/	[libgit2]: https://libgit2.org/
354	181	[curses]: https://en.wikipedia.org/wiki/Curses_(programming_library)	[curses]: https://en.wikipedia.org/wiki/Curses_(programming_library)
	182		[pandoc]: https://pandoc.org/
355	183
356	184	[dtl]: https://github.com/cubicdaiya/dtl	[dtl]: https://github.com/cubicdaiya/dtl
357	185	[pmr]: https://github.com/phalpern/CppCon2017Code	[pmr]: https://github.com/phalpern/CppCon2017Code

File docs/zograscope.md copied from file README.md (similarity 52%) (mode: 100644) (index eb724b8..91ac703)
1		zograscope, _2017 - 2022_
	1		NAME
	2		====
2	3
3		![Screenshot](data/examples/c/screenshot.png)
4
5		Clone recursively, there are submodules:
6
7		```bash
8		git clone --recursive https://github.com/xaizek/zograscope.git
9		```
10
11		1. [Description](#description) ([Status](#status);
12		[Supported languages](#supported-languages);
13		[Configuration](#configuration))
14		2. [Tools](#tools)
15		3. [Building and Installing](#building-and-installing)
16		([Dependencies](#dependencies))
17		4. [Documentation](#documentation)
18		5. [License](#license)
19		6. [Credits](#credits)
20		([References](#references))
21
22		## Name ##
23
24		"A zograscope is an optical device for enhancing the sense of depth perception
25		from a flat picture." ([wiki][wiki-zograscope])
26
27		## Description ##
28
29		`zograscope` is built around syntax-aware diff and includes a number of
30		additional tools.
	4		zograscope is a collection of source-processing tools spawned out of
	5		syntax-aware diffing.
31	6
32	7	The nature of syntax-aware diff requires knowledge of structure of the code,	The nature of syntax-aware diff requires knowledge of structure of the code,
33	8	which can be used to build other simple tools that can benefit from this	which can be used to build other simple tools that can benefit from this

...	...	text-processing utilities seems feasible and the result might be even more
37	12	practical than some of the more elaborate tools which end up requiring	practical than some of the more elaborate tools which end up requiring
38	13	complicated setup process.	complicated setup process.
39	14
40		### Status ###
41
42		The project is work in progress, but is useful in its current state.
43
44		Code isn't perfect and isn't extensively documented as initial version was more
45		of an experiment, but this situation gets better.
46
47		### Supported languages ###
	15		LANGUAGE SUPPORT
	16		================
48	17
49		\| Language \| Status \|
50		\|-----------\|------------------------------------------------------------------\|
51		\| C \| C11 and earlier with common extensions, but without K&R syntax \|
52		\| C++ \| C++14 and earlier with common extensions \|
53		\| GNU Make \| Most of the syntax \|
54		\| Lua \| Version 5.3 \|
	18		\| Language \| Status
	19		\|-----------\|-------------------------------------------------------------------
	20		\| C \| C11 and earlier with common extensions, but without K&R syntax
	21		\| C++ \| C++14 and earlier with common extensions
	22		\| GNU Make \| Most of the syntax
	23		\| Lua \| Version 5.3
55	24
56		#### C ####
	25		C
	26		-
57	27
58	28	The exact grammar is that of C11 with extensions implemented in popular	The exact grammar is that of C11 with extensions implemented in popular
59	29	compilers and additional extensions needed to allow processing of code with	compilers and additional extensions needed to allow processing of code with
60	30	macros.	macros.
61	31
62	32	Note the following:	Note the following:
	33
63	34	* old K&R style of function declarations isn't parsed (there might be a	* old K&R style of function declarations isn't parsed (there might be a
64	35	workaround for it, but this syntax is deprecated either way)	workaround for it, but this syntax is deprecated either way)
65	36	* preprocessor directives aren't tokenized according to language rules yet,	* preprocessor directives aren't tokenized according to language rules yet,

...	...	Note the following:
70	41	Other than that code in C89, C99, C11 and GNU-versions of C language should be	Other than that code in C89, C99, C11 and GNU-versions of C language should be
71	42	recognized.	recognized.
72	43
73		#### C++ ####
	44		C++
	45		---
74	46
75	47	C++ support relies on external application called [srcml][srcml] and requires it	C++ support relies on external application called [srcml][srcml] and requires it
76	48	to be installed in binary form (not necessary during build).	to be installed in binary form (not necessary during build).

...	...	equally well, it's seems to be good enough, especially for a ready to use parser
81	53	that wasn't that hard to integrate.	that wasn't that hard to integrate.
82	54
83	55	Note the following:	Note the following:
	56
84	57	* the tuning of comparison is in progress and will be refined over time	* the tuning of comparison is in progress and will be refined over time
85	58
86		#### GNU Make ####
	59		GNU Make
	60		--------
87	61
88	62	It's hard to measure level of support in case of GNU Make, because there seem to	It's hard to measure level of support in case of GNU Make, because there seem to
89	63	be no reference for the syntax itself apart from documentation, which is not	be no reference for the syntax itself apart from documentation, which is not

...	...	many features most people don't know exist. It's definitely not 100%, but 90%
95	69	or even more of all existing Makefiles out there should be parsed.	or even more of all existing Makefiles out there should be parsed.
96	70
97	71	Note the following:	Note the following:
	72
98	73	* the comparison might not produce best results on Makefiles as it needs	* the comparison might not produce best results on Makefiles as it needs
99	74	some tuning, this should happen over time (Makefiles aren't changed that	some tuning, this should happen over time (Makefiles aren't changed that
100	75	often)	often)
101	76
102		#### Lua ####
103
104		Newly added (March 2021) with very little testing so far. However, the
105		language is small and simple enough to not pose much difficulties.
	77		Lua
	78		---
106	79
107	80	Note the following:	Note the following:
	81
108	82	* non-5.3 versions might still work, albeit can produce worse results	* non-5.3 versions might still work, albeit can produce worse results
109	83
110		#### Other ####
	84		Other
	85		-----
111	86
112	87	More languages should be added in the future, maybe with external parsers that	More languages should be added in the future, maybe with external parsers that
113	88	are capable of preserving all information about the source code.	are capable of preserving all information about the source code.
114	89
115		### Configuration ###
	90		CONFIGURATION
	91		=============
116	92
117	93	Configuration is done per directory tree ("root") which is the closes parent (or	Configuration is done per directory tree ("root") which is the closes parent (or
118	94	current directory) that contains `.zs/` directory. The `.zs/` directory	current directory) that contains `.zs/` directory. The `.zs/` directory
119	95	contains files which define how contents of the root is to be processed.	contains files which define how contents of the root is to be processed.
120	96	Settings from multiple nested roots are not combined.	Settings from multiple nested roots are not combined.
121	97
122		#### `.zs/exclude` file ####
	98		`.zs/exclude` file
	99		------------------
123	100
124	101	A `.gitignore`-like (or `.git/info/exclude`-like) file that lists paths relative	A `.gitignore`-like (or `.git/info/exclude`-like) file that lists paths relative
125	102	to the root. The purpose is to exclude uninteresting files (automatically	to the root. The purpose is to exclude uninteresting files (automatically

...	...	moc_.h*
170	147	/config.h	/config.h
171	148	```	```
172	149
173		#### `.zs/attributes` file ####
	150		`.zs/attributes` file
	151		---------------------
174	152
175	153	Borrowing from the `git` project here again. This file consists of lines	Borrowing from the `git` project here again. This file consists of lines
176	154	matching paths to attributes. Lines are trimmed before being processed.	matching paths to attributes. Lines are trimmed before being processed.

...	...	another type of comments.
187	165	Each line of the file is visited in top down order and attributes from every	Each line of the file is visited in top down order and attributes from every
188	166	matching entry are merged with the current state. Hierarchy of configuration	matching entry are merged with the current state. Hierarchy of configuration
189	167	values:	values:
	168
190	169	1. Default values (lowest priority)	1. Default values (lowest priority)
191	170	2. Attributes	2. Attributes
192	171	3. Command-line parameters (highest priority)	3. Command-line parameters (highest priority)

...	...	tab-2.[ch] tab-size=2
218	197	# any.cpp has tab-size=4	# any.cpp has tab-size=4
219	198	```	```
220	199
221		## Tools ##
	200		INVOCATION
	201		==========
222	202
223		### [zs-diff](tools/diff/README.md) ###
	203		All tools have common and specific command-line arguments. Tool-specific
	204		arguments are described on the page of the tool, common ones are below.
224	205
225		A terminal-based syntax-aware diff.
	206		`-h`, `--help` \
	207		print help message
226	208
227		### [zs-find](tools/find/README.md) ###
	209		`--dry-run` \
	210		parse and exit
228	211
229		Grep-like tool that finds elements of source code structure.
	212		`--debug` \
	213		enable debugging of grammar
230	214
231		### [zs-gdiff](tools/gdiff/README.md) ###
	215		`--sdebug` \
	216		enable debugging of strees
232	217
233		A Qt5 GUI version of syntax-aware diff.
	218		`--dump-stree` \
	219		display stree(s)
234	220
235		### [zs-hi](tools/hi/README.md) ###
	221		`--dump-tree` \
	222		display tree(s)
236	223
237		Simple syntax highlighter for xterm-256color palette.
	224		`--time-report` \
	225		report time spent on different activities
238	226
239		### [zs-stats](tools/stats/README.md) ###
	227		`--fine-only` \
	228		use only fine-grained tree
240	229
241		Counter of lines of code.
	230		`--color` \
	231		force colorization of output
242	232
243		### [zs-tui](tools/tui/README.md) ###
	233		`--lang` _arg_ \
	234		force specific language (`c`, `cxx`, `make`, `lua`) and disable auto-detection
244	235
245		TUI interface with underdefined scope of functionality.
246
247		## Building and Installing ##
248
249		```bash
250		# if Qt5 is available (use `qmake` if it corresponds to Qt5 on your machine)
251		echo 'QT5_PROG := qmake-qt5' >> config.mk
252		# if libgit2 is present
253		echo 'HAVE_LIBGIT2 := yes' >> config.mk
254		# if cursesw is present
255		echo 'HAVE_CURSESW := yes' >> config.mk
256
257		make release check
258		```
259
260		This will build release version and run tests. The executables will be named
261		`release/zs-*`.
	236		BEHAVIOUR
	237		=========
262	238
263		There is no data, so just making them available in the `$PATH` will work.
264		However, it's possible to install conventionally (`/usr` prefix by default):
265
266		```
267		make install
268		```
269
270		`DESTDIR` and `PREFIX` can be set to modify destination location. On invoking
271		`make uninstall` same values of these values should be specified.
272
273		### Dependencies ###
274
275		* [GNU Make][make]
276		* C++11-capable compiler (GCC 4.9 has some issues, GCC 5.3 works fine)
277		* [flex][flex]
278		* [GNU Bison][bison] v3+
279		* [Boost][boost], tested with 1.59, but older versions might work too
280		* (optional, run-time, for C++) [srcml][srcml] (v0.9.5 and v1.0.0 were tested)
281		* (optional, for `gdiff` tool) [qt5][qt5]
282		* (optional, for `gdiff` tool) [libgit2][libgit2]
283		* (optional, for `tui` tool) [curses][curses] with support of wide characters
284
285		#### For Debian-based distributions ####
286
287		If you are using Debian or one of its derivatives, you can install the
288		dependencies as follows:
289
290		```bash
291		# install make and build tools
292		sudo apt install -y build-essential
293		# installing dependencies
294		sudo apt install -y libboost-filesystem-dev libboost-iostreams-dev
295		sudo apt install -y libboost-program-options-dev libboost-system-dev
296		sudo apt install -y libarchive13
297		sudo apt install -y bison flex
298		# installing srcml
299		wget http://131.123.42.38/lmcrs/beta/srcML-Ubuntu18.04.deb
300		sudo apt install ./srcML-Ubuntu18.04.deb
301		```
	239		Pager
	240		-----
302	241
303		You can also check out the [CI build script](data/appveyor/ubuntu.sh) in case
304		dependencies change in the future.
	242		When output is a terminal (not the case when invoked by Git), `less` is spawn
	243		if output is about the size of the screen.
305	244
306		## Documentation ##
	245		Language detection
	246		------------------
307	247
308		At the moment there is only `--help` option.
	248		By default language is auto-detected based on file name. When name is not
	249		recognized the file is parsed as C.
309	250
310		## License ##
	251		TOOLS
	252		=====
311	253
312		![AGPLv3](data/agplv3.png)
	254		[zs-diff(1)](./zs-diff.md)
313	255
314		Version 3 of the GNU Affero General Public License.
315
316		## Credits ##
317
318		[dtl library][dtl] is used for finding edit distance.
319
320		[pmr implementation][pmr] from C++17 with a small addition is employed for
321		custom allocators.
322
323		[TinyXML2][tinyxml2] is used for parsing XML.
	256		A terminal-based syntax-aware diff.
324	257
325		[tree-sitter][tree-sitter] is used for parsing of some languages.
	258		[zs-find(1)](./zs-find.md)
326	259
327		[Catch2][catch] is used for tests.
	260		Grep-like tool that finds elements of source code structure.
328	261
329		### References ###
	262		[zs-gdiff(1)](./zs-gdiff.md)
330	263
331		[Change Distilling: Tree Differencing for Fine-Grained Source Code Change
332		Extraction][cd].
333		Beat Fluri, Michael Würsch, Martin Pinzger, and Harald C. Gall.
334		2007.
	264		A Qt5 GUI version of syntax-aware diff.
335	265
336		[Change Detection in Hierarchically Structured Information][hier].
337		Sudarshan Chawathe, Hector Garcia-molina and Jennifer Widom.
338		1996.
	266		[zs-hi(1)](./zs-hi.md)
339	267
340		[Simple fast algorithms for the editing distance between trees and related
341		problems][ted].
342		Kaizhong Zhang and Dennis Shasha.
343		1989.
	268		Simple syntax highlighter for xterm-256color palette.
344	269
345		[wiki-zograscope]: https://en.wikipedia.org/wiki/Zograscope
	270		[zs-stats(1)](./zs-stats.md)
346	271
347		[make]: https://www.gnu.org/software/make/
348		[flex]: https://github.com/westes/flex
349		[bison]: https://www.gnu.org/software/bison/
350		[boost]: http://www.boost.org/
351		[srcml]: http://www.srcml.org/
352		[qt5]: https://www.qt.io/
353		[libgit2]: https://libgit2.org/
354		[curses]: https://en.wikipedia.org/wiki/Curses_(programming_library)
	272		Counter of lines of code.
355	273
356		[dtl]: https://github.com/cubicdaiya/dtl
357		[pmr]: https://github.com/phalpern/CppCon2017Code
358		[tinyxml2]: https://github.com/leethomason/tinyxml2
359		[tree-sitter]: https://tree-sitter.github.io/
360		[catch]: https://github.com/catchorg/Catch2
	274		[zs-tui(1)](./zs-tui.md)
361	275
362		[cd]: http://www.merlin.uzh.ch/publication/show/2531
363		[hier]: http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.48.9224
364		[ted]: http://citeseer.ist.psu.edu/viewdoc/summary?doi=10.1.1.460.5601
	276		TUI interface with underdefined scope of functionality.

File docs/zs-com.md added (mode: 100644) (index 0000000..e69de29)

File docs/zs-diff.md added (mode: 100644) (index 0000000..95429e1)
	1	NAME
	2	====
	3
	4	zs-diff is a terminal-based syntax-aware diff. The syntax-aware part means
	5	that comparison isn't sensible to formatting changes and understands general
	6	structure of its input.
	7
	8	The primary purpose of the utility is to be used as external diff by `git`.
	9
	10	INVOCATION
	11	==========
	12
	13	Manual Form
	14	-----------
	15
	16	`zs-diff` `[options...]` _old-file_ _new-file_
	17
	18	To be used in a shell.
	19
	20	Git Form
	21	--------
	22
	23	`zs-diff` `[options...]` _path_ _old-file_ _old-hex_ _old-mode_
	24	_new-file_ _new-hex_ _new-mode_
	25
	26	When Git calls external diff for a changed file.
	27
	28	Git Rename Form
	29	---------------
	30
	31	`zs-diff` `[options...]` _path_ _old-file_ _old-hex_ _old-mode_
	32	_new-file_ _new-hex_ _new-mode_
	33	_new-path_ _rename-msg_
	34
	35	When Git calls external diff for renamed and possibly changed file.
	36
	37	Tool-specific Options
	38	---------------------
	39
	40	`--no-refine` \
	41	do not refine coarse results
	42
	43	USAGE AND BEHAVIOUR
	44	===================
	45
	46	Invoking manually
	47	-----------------
	48
	49	Just do:
	50
	51	```bash
	52	zs-diff old-file new-file
	53	```
	54
	55	When Invoked by Git
	56	-------------------
	57
	58	If parsing fails when Git-like invocation is used, the tool attempts to invoke
	59	`git` with `--no-ext-diff` to do the diff. Unfortunately, Git doesn't supply
	60	enough information for a proper invocation and `git`-header you'll see will be
	61	with blob hashes or temporary paths.
	62
	63	Use with Git without Configuration
	64	----------------------------------
	65
	66	Use `$GIT_EXTERNAL_DIFF`:
	67
	68	```bash
	69	GIT_EXTERNAL_DIFF='zs-diff --color' git show --ext-diff
	70	```
	71
	72	Local Git integration
	73	---------------------
	74
	75	Add `zs-diff` as a diff tool to `git` with these lines (`.git/config`):
	76
	77	```gitconfig
	78	[diff "zs-diff"]
	79	command = zs-diff --color
	80	```
	81
	82	Then configure which files it should be used for (`.git/info/attributes`):
	83
	84	```gitattributes
	85	*.[ch] diff=zs-diff
	86	*.h.in diff=zs-diff
	87
	88	*.[ch]pp diff=zs-diff
	89
	90	Makefile diff=zs-diff
	91	Makefile.am diff=zs-diff
	92	Makefile.win diff=zs-diff
	93
	94	*.lua diff=zs-diff
	95	```
	96
	97	This will make it work for `git diff` and `git show`, but `git log` and other
	98	subcommands don't use custom diff tools by default and need `--ext-diff` option
	99	to be specified (can be done in an alias).
	100
	101	Global Git integration
	102	----------------------
	103
	104	Same as above, but specify attributes in `~/.config/git/attributes` and use one
	105	of the following files for configuration:
	106
	107	* `~/.config/git/config`
	108	* `~/.gitconfig`
	109
	110	Explicit use in Git
	111	-------------------
	112
	113	Interactive (say `y` to view specific file):
	114
	115	```bash
	116	git difftool -x zs-diff
	117	```
	118
	119	SEE ALSO
	120	========
	121
	122	zograscope(7) for common options and list of all tools there.

File docs/zs-find.md added (mode: 100644) (index 0000000..ab00a5a)
	1	NAME
	2	====
	3
	4	zs-find is a tool for searching in code. Applications include things like
	5	collecting crude statistics about the code, looking for certain nested
	6	configurations or sequences of tokens.
	7
	8	The syntax and matching abilities are relatively basic and are subject to
	9	significant changes in the future.
	10
	11	INVOCATION
	12	==========
	13
	14	`zs-find` `[options...]` _[paths...]_ : _matchers..._
	15
	16	`zs-find` `[options...]` _[paths...]_ : _[matchers...]_ : _[expressions...]_
	17
	18	`zs-find` `[options...]` _[paths...]_ :: _expressions..._
	19
	20	Paths can specify both files and directories. When no path is specified, "." is
	21	assumed.
	22
	23	Either _matchers..._, _expressions..._ or both must be specified.
	24
	25	Tool-specific Options
	26	---------------------
	27
	28	`-c`, `--count` \
	29	only count matches and report statistics
	30
	31	`--lang` \
	32	here this common option also limits set of files to process
	33
	34	Matchers
	35	--------
	36
	37	\| Matcher \| Description
	38	\|---------\|-------------
	39	\| `decl` \| Any sort of declaration
	40	\| `stmt` \| Statements
	41	\| `func` \| Functions (their definitions only)
	42	\| `call` \| Function invocations
	43	\| `param` \| Parameters of a function
	44	\| `comm` \| Comments of any kind
	45	\| `dir` \| Preprocessor-alike directives
	46	\| `block` \| Containers of statements
	47
	48	Expressions
	49	-----------
	50
	51	Each expressions matches a single token.
	52
	53	\| Expr \| What it matches
	54	\|---------\|-----------------
	55	\| `x` \| Exactly `x`
	56	\| `/^x/` \| Any token that starts with `x`
	57	\| `/x$/` \| Any token that ends with `x`
	58	\| `/^x$/` \| Exactly `x`
	59	\| `/x/` \| Any token that contains `x` as a substring
	60	\| `//x/` \| Regular expression `x`
	61	\| `//` \| Any token
	62
	63	EXAMPLES
	64	========
	65
	66	List all comments in C files:
	67
	68	```
	69	zs-find --lang c : dir
	70	```
	71
	72	Count number of preprocessor directives inside functions in all supported
	73	languages:
	74
	75	```
	76	zs-find --count src/ : func dir
	77	```
	78
	79	Print functions of a specific file if they contain `return` statement:
	80
	81	```
	82	zs-find src/utils/time.hpp : func : return
	83	```
	84
	85	List all statements containing uses of `exec()` family of functions:
	86
	87	```
	88	zs-find : stmt : '//^(execl[pe]?\|execvp?e?)$/'
	89	```
	90
	91	List all invocations of `snprintf` which have single token as the first
	92	argument:
	93
	94	```
	95	zs-find ../src : call : snprintf '(' // ,
	96	```
	97
	98	SEE ALSO
	99	========
	100
	101	zograscope(7) for common options and list of all tools there.

File docs/zs-gdiff.md added (mode: 100644) (index 0000000..7199aad)
	1	NAME
	2	====
	3
	4	zs-gdiff is a GUI syntax-aware diff that uses Qt5. See zs-diff(1) for
	5	more details and comparison against other tools.
	6
	7	The tool can either accept two files on command-line, be integrated with `git`
	8	by its means (yet using external GUI tools from `git` isn't very convenient in
	9	general) or pick up list of changed files in the repository (staged or unstaged
	10	in index or from a commit) by itself. The latter way of using `zs-gdiff` with
	11	`git` doesn't require any configuration and allows going through files without
	12	restarting it, unlike when `git` invokes external tools.
	13
	14	It works, but it's far from being polished.
	15
	16	INVOCATION
	17	==========
	18
	19	Manual Form
	20	-----------
	21
	22	`zs-gdiff` `[options...]` _old-file_ _new-file_
	23
	24	To be used in a shell.
	25
	26	Git Status Form
	27	---------------
	28
	29	`zs-gdiff` [`--cached`]
	30
	31	To be used in a shell to view staged/unstaged changes.
	32
	33	Git Commit Form
	34	---------------
	35
	36	`zs-gdiff` _git-reference_
	37
	38	To be used in a shell to view commit changes.
	39
	40	Git Form
	41	--------
	42
	43	`zs-gdiff` `[options...]` _path_ _old-file_ _old-hex_ _old-mode_
	44	_new-file_ _new-hex_ _new-mode_
	45
	46	When Git calls external diff for a changed file.
	47
	48	Git Rename Form
	49	---------------
	50
	51	`zs-gdiff` `[options...]` _path_ _old-file_ _old-hex_ _old-mode_
	52	_new-file_ _new-hex_ _new-mode_
	53	_new-path_ _rename-msg_
	54
	55	When Git calls external diff for renamed and possibly changed file.
	56
	57	Tool-specific Options
	58	---------------------
	59
	60	`--cached` \
	61	use staged changes instead of unstaged
	62
	63	SEE ALSO
	64	========
	65
	66	zograscope(7) for common options and list of all tools there.

File docs/zs-grep.md added (mode: 100644) (index 0000000..e69de29)

File docs/zs-hi.md added (mode: 100644) (index 0000000..9b8c06f)
	1	NAME
	2	====
	3
	4	zs-hi is a primitive code highlighter for terminal. The main purpose is
	5	testing and debugging of code parsing, but it can also be used on its own.
	6
	7	The only hard-coded color scheme at the moment is for xterm-256color palette.
	8
	9	INVOCATION
	10	==========
	11
	12	`zs-hi` `[options...]` _[{path\|-}]_
	13
	14	Not providing _path_ argument is equivalent to specifying `-` and thus reading
	15	from standard input.
	16
	17	EXAMPLES
	18	========
	19
	20	Highlighting standard input
	21	---------------------------
	22
	23	```
	24	pahole -C key_chunk_t vifm \| zs-hi
	25	```
	26
	27	Highlighting a file
	28	-------------------
	29
	30	```
	31	zs-hi utils.c
	32	```
	33
	34	Checking if code parses correctly
	35	---------------------------------
	36
	37	Whether the parser is able to handle given sources can be checked like this:
	38
	39	```
	40	find -name '*.[hc]' -exec zs-hi --dry {} \;
	41	```
	42
	43	It produces output for files with which it has issues.
	44
	45	SEE ALSO
	46	========
	47
	48	zograscope(7) for common options and list of all tools there.

File docs/zs-stats.md copied from file tools/stats/README.md (similarity 61%) (mode: 100644) (index e3521a3..0b9a74a)
1		[zograscope][zograscope] :: zs-stats
	1		NAME
	2		====
2	3
3		![Screenshot](data/example/screenshot.png)
	4		_zs-stats_ is a tool for counting:
4	5
5		## Description ##
6
7		`zs-stats` is a tool for counting:
8	6	* lines of code	* lines of code
9	7	* size of functions (complete definition)	* size of functions (complete definition)
10	8	* number of functions	* number of functions
11	9	* number of parameters of functions	* number of parameters of functions
12	10	* possibly other things in the future	* possibly other things in the future
13	11
14		## Differences ##
	12		INVOCATION
	13		==========
	14
	15		`zs-stats` `[options...]` _[paths...]_
	16
	17		Paths can specify both files and directories. When no path is specified, "." is
	18		assumed.
	19
	20		Tool-specific Options
	21		---------------------
	22
	23		`--annotate` \
	24		print source code annotated with line types
	25
	26		`--lang` \
	27		here this common option also limits set of files to process
	28
	29		OPERATION
	30		=========
15	31
16	32	Differences from some similar tools:	Differences from some similar tools:
	33
17	34	* counts line containing only braces/brackets/parenthesis separately from code	* counts line containing only braces/brackets/parenthesis separately from code
18	35	* blank lines inside multiline comments are counted as comments	* blank lines inside multiline comments are counted as comments
19	36	* blank lines inside string literals are counted as code	* blank lines inside string literals are counted as code

...	...	Differences from some similar tools:
23	40	although it's possible to add them)	although it's possible to add them)
24	41	* last line continuation in macros in C aren't recognized due to lack of	* last line continuation in macros in C aren't recognized due to lack of
25	42	tokenization of preprocessor directives; in C++ it might not be recognized	tokenization of preprocessor directives; in C++ it might not be recognized
26		due to srcml bugs
	43		due to SrcML bugs
	44
	45		SEE ALSO
	46		========
27	47
28		[zograscope]: ../../README.md
	48		zograscope(7) for common options and list of all tools there.

File docs/zs-tui.md added (mode: 100644) (index 0000000..10ba760)
	1	NAME
	2	====
	3
	4	`zs-tui` is a TUI version for processing files, whose scope is yet to be
	5	defined. So far it lists files or functions along with their size and parameter
	6	count and allows viewing those items in source code as well as viewing dump of
	7	their internal representation.
	8
	9	It's not clear if it's worth adding diffing functionality here. It's probably
	10	not, which means that this tool will be mostly for interactive browsing or
	11	similar activities and other tools might be extracted out of it.
	12
	13	INVOCATION
	14	==========
	15
	16	`zs-tui` `[options...]` _[paths...]_
	17
	18	Paths can specify both files and directories. When no path is specified, "." is
	19	assumed.
	20
	21	Tool-specific Options
	22	---------------------
	23
	24	`--lang` \
	25	here this common option also limits set of files to process
	26
	27	CONTROLS
	28	========
	29
	30	Supported Vim-like shortcuts:
	31
	32	* `G` -- to last line
	33	* `gg` -- to first line
	34	* `j` -- to the item below
	35	* `k` -- to the item above
	36
	37	Other shortcuts:
	38
	39	* files view:
	40	- `c` -- enter code view
	41	- `d` -- enter dump view
	42	- `f` -- switch to functions view
	43	- `q` -- quit the application
	44	* functions view:
	45	- `c` -- enter code view
	46	- `d` -- enter dump view
	47	- `f` -- switch to files view
	48	- `q` -- quit the application
	49	* code view:
	50	- `c/q` -- leave code view
	51	* dump view:
	52	- `d/q` -- leave dump view
	53
	54	SEE ALSO
	55	========
	56
	57	zograscope(7) for common options and list of all tools there.

File man/zograscope.7 added (mode: 100644) (index 0000000..42700d8)
	1	'\" t
	2	.\" Automatically generated by Pandoc 2.17.1.1
	3	.\"
	4	.\" Define V font for inline verbatim, using C font in formats
	5	.\" that render this, and otherwise B font.
	6	.ie "\f[CB]x\f[]"x" \{\
	7	. ftr V B
	8	. ftr VI BI
	9	. ftr VB B
	10	. ftr VBI BI
	11	.\}
	12	.el \{\
	13	. ftr V CR
	14	. ftr VI CI
	15	. ftr VB CB
	16	. ftr VBI CBI
	17	.\}
	18	.TH "zograscope" "7" "July 19, 2022" "" ""
	19	.hy
	20	.SH NAME
	21	.PP
	22	\f[I]zograscope\f[R] is a collection of source-processing tools spawned
	23	out of syntax-aware diffing.
	24	.PP
	25	The nature of syntax-aware diff requires knowledge of structure of the
	26	code, which can be used to build other simple tools that can benefit
	27	from this information.
	28	Competing with real language front-ends in the level of accuracy is not
	29	possible, but making some things that are one step further than regular
	30	text-processing utilities seems feasible and the result might be even
	31	more practical than some of the more elaborate tools which end up
	32	requiring complicated setup process.
	33	.SH LANGUAGE SUPPORT
	34	.PP
	35	.TS
	36	tab(@);
	37	lw(9.9n) lw(60.1n).
	38	T{
	39	Language
	40	T}@T{
	41	Status
	42	T}
	43	_
	44	T{
	45	C
	46	T}@T{
	47	C11 and earlier with common extensions, but without K&R syntax
	48	T}
	49	T{
	50	C++
	51	T}@T{
	52	C++14 and earlier with common extensions
	53	T}
	54	T{
	55	GNU Make
	56	T}@T{
	57	Most of the syntax
	58	T}
	59	T{
	60	Lua
	61	T}@T{
	62	Version 5.3
	63	T}
	64	.TE
	65	.SS C
	66	.PP
	67	The exact grammar is that of C11 with extensions implemented in popular
	68	compilers and additional extensions needed to allow processing of code
	69	with macros.
	70	.PP
	71	Note the following:
	72	.IP \[bu] 2
	73	old K&R style of function declarations isn\[cq]t parsed (there might be
	74	a workaround for it, but this syntax is deprecated either way)
	75	.IP \[bu] 2
	76	preprocessor directives aren\[cq]t tokenized according to language rules
	77	yet, but their contents is diffed
	78	.IP \[bu] 2
	79	extensive use of macros in unusual places might not be parsed (this
	80	probably won\[cq]t change)
	81	.PP
	82	Other than that code in C89, C99, C11 and GNU-versions of C language
	83	should be recognized.
	84	.SS C++
	85	.PP
	86	C++ support relies on external application called [srcml][srcml] and
	87	requires it to be installed in binary form (not necessary during build).
	88	.PP
	89	Reported standard version supported by \f[V]srcml\f[R] is C++14, so all
	90	previous ones should work too.
	91	Although their parser doesn\[cq]t handle all language constructs equally
	92	well, it\[cq]s seems to be good enough, especially for a ready to use
	93	parser that wasn\[cq]t that hard to integrate.
	94	.PP
	95	Note the following:
	96	.IP \[bu] 2
	97	the tuning of comparison is in progress and will be refined over time
	98	.SS GNU Make
	99	.PP
	100	It\[cq]s hard to measure level of support in case of GNU Make, because
	101	there seem to be no reference for the syntax itself apart from
	102	documentation, which is not concise.
	103	.PP
	104	Yet parser is capable of processing quite complicated examples of
	105	Makefiles (like the one used in this project or generated by
	106	\f[V]automake\f[R]) which contain many features most people don\[cq]t
	107	know exist.
	108	It\[cq]s definitely not 100%, but 90% or even more of all existing
	109	Makefiles out there should be parsed.
	110	.PP
	111	Note the following:
	112	.IP \[bu] 2
	113	the comparison might not produce best results on Makefiles as it needs
	114	some tuning, this should happen over time (Makefiles aren\[cq]t changed
	115	that often)
	116	.SS Lua
	117	.PP
	118	Note the following:
	119	.IP \[bu] 2
	120	non-5.3 versions might still work, albeit can produce worse results
	121	.SS Other
	122	.PP
	123	More languages should be added in the future, maybe with external
	124	parsers that are capable of preserving all information about the source
	125	code.
	126	.SH CONFIGURATION
	127	.PP
	128	Configuration is done per directory tree (\[lq]root\[rq]) which is the
	129	closes parent (or current directory) that contains \f[V].zs/\f[R]
	130	directory.
	131	The \f[V].zs/\f[R] directory contains files which define how contents of
	132	the root is to be processed.
	133	Settings from multiple nested roots are not combined.
	134	.SS \f[V].zs/exclude\f[R] file
	135	.PP
	136	A \f[V].gitignore\f[R]-like (or \f[V].git/info/exclude\f[R]-like) file
	137	that lists paths relative to the root.
	138	The purpose is to exclude uninteresting files (automatically generated,
	139	third-party or otherwise).
	140	\f[V].zs/exclude\f[R] is used by tools that search for files
	141	automatically and doesn\[cq]t prevent the use of the same files when
	142	they are specified explicitly.
	143	.PP
	144	The following kinds of entries are recognized:
	145	.IP \[bu] 2
	146	empty lines, which are ignored
	147	.IP \[bu] 2
	148	lines that start with a \f[V]#\f[R] (comments), which are ignored
	149	.IP \[bu] 2
	150	lines that end with \f[V]/\f[R] match only directories, the \f[V]/\f[R]
	151	is stripped and line processing continues
	152	.IP \[bu] 2
	153	lines without \f[V]/\f[R] are treated as shell-like globs against
	154	filename which apply at any directory level and define paths whose
	155	processing should be skipped
	156	.IP \[bu] 2
	157	lines that start with \f[V]!\f[R] define exception from rules that
	158	precede them, you can\[cq]t undo exclusion of files in excluded
	159	directories, for the purpose of this discussion the \f[V]!\f[R] is
	160	stripped and line processing continues
	161	.IP \[bu] 2
	162	lines that start with \f[V]/\f[R] always match paths instead of filename
	163	and provide a way to specify files to be ignored only in the root,
	164	otherwise they are processed as specified in the next item
	165	.IP \[bu] 2
	166	other lines are treated as shell-like globs against paths relative to
	167	the root (leading \f[V]/\f[R] is allowed, but has no effect other than
	168	changing type of a match) which define paths whose processing should be
	169	skipped
	170	.PP
	171	No way to escape leading \f[V]#\f[R] and \f[V]!\f[R] or a newline at the
	172	moment.
	173	.PP
	174	Globs support the following: \f[V][{char-class}]\f[R],
	175	\f[V][!{char-class}]\f[R], \f[V][\[ha]{char-class}]\f[R], \f[V]?\f[R]
	176	(doesn\[cq]t match \f[V]/\f[R]), \f[V]*\f[R] (matches any (including
	177	zero) number of characters except for \f[V]/\f[R]) and
	178	\f[V]\[rs]{char}\f[R] (matches literal \f[V]{char}\f[R]).
	179	.PP
	180	Example:
	181	.IP
	182	.nf
	183	\f[C]
	184	# .zs/exclude
	185
	186	# automatically generated sources
	187	src/c/c11-lexer.gen.cpp
	188	src/c/c11-parser.gen.cpp
	189	src/make/.gen.
	190
	191	# Qt-produced sources
	192	ui_*.h
	193	moc_*.cpp
	194	moc_*.h
	195
	196	# file in root
	197	/config.h
	198	\f[R]
	199	.fi
	200	.SS \f[V].zs/attributes\f[R] file
	201	.PP
	202	Borrowing from the \f[V]git\f[R] project here again.
	203	This file consists of lines matching paths to attributes.
	204	Lines are trimmed before being processed.
	205	.PP
	206	Empty lines and comments work like in \f[V].zs/excludes\f[R] file, all
	207	other lines follow this pattern:
	208	.IP
	209	.nf
	210	\f[C]
	211	exclude-expr [attr1=value1 [attr2=value2 [...]]]
	212	\f[R]
	213	.fi
	214	.PP
	215	Expressions that define exceptions (start with \f[V]!\f[R]) are
	216	recognized but ignored to keep syntax consistent between different
	217	files, which basically makes them another type of comments.
	218	.PP
	219	Each line of the file is visited in top down order and attributes from
	220	every matching entry are merged with the current state.
	221	Hierarchy of configuration values:
	222	.IP "1." 3
	223	Default values (lowest priority)
	224	.IP "2." 3
	225	Attributes
	226	.IP "3." 3
	227	Command-line parameters (highest priority)
	228	.PP
	229	Supported attributes:
	230	.IP \[bu] 2
	231	\f[V]lang\f[R]
	232	.PD 0
	233	.P
	234	.PD
	235	Default: \[lq]\[lq]
	236	.PD 0
	237	.P
	238	.PD
	239	Those accepted by \f[V]--lang\f[R] command-line option: c, cxx, make,
	240	lua
	241	.IP \[bu] 2
	242	\f[V]tab-size\f[R]
	243	.PD 0
	244	.P
	245	.PD
	246	Default: 4
	247	.PD 0
	248	.P
	249	.PD
	250	Value should be an integer that\[cq]s greater than zero
	251	.PP
	252	Unknown attributes are ignored.
	253	.PP
	254	Example:
	255	.IP
	256	.nf
	257	\f[C]
	258	# .zs/exclude
	259
	260	*.c tab-size=8
	261	*.h tab-size=8 lang=c
	262	tab-2.[ch] tab-size=2
	263
	264	# any.c has tab-size=8
	265	# tab-2.c has tab-size=2
	266	# tab-2.h has tab-size=2 lang=c
	267	# any.h has tab-size=8 lang=c
	268	# any.cpp has tab-size=4
	269	\f[R]
	270	.fi
	271	.SH INVOCATION
	272	.PP
	273	All tools have common and specific command-line arguments.
	274	Tool-specific arguments are described on the page of the tool, common
	275	ones are below.
	276	.PP
	277	\f[V]-h\f[R], \f[V]--help\f[R]
	278	.PD 0
	279	.P
	280	.PD
	281	print help message
	282	.PP
	283	\f[V]--dry-run\f[R]
	284	.PD 0
	285	.P
	286	.PD
	287	parse and exit
	288	.PP
	289	\f[V]--debug\f[R]
	290	.PD 0
	291	.P
	292	.PD
	293	enable debugging of grammar
	294	.PP
	295	\f[V]--sdebug\f[R]
	296	.PD 0
	297	.P
	298	.PD
	299	enable debugging of strees
	300	.PP
	301	\f[V]--dump-stree\f[R]
	302	.PD 0
	303	.P
	304	.PD
	305	display stree(s)
	306	.PP
	307	\f[V]--dump-tree\f[R]
	308	.PD 0
	309	.P
	310	.PD
	311	display tree(s)
	312	.PP
	313	\f[V]--time-report\f[R]
	314	.PD 0
	315	.P
	316	.PD
	317	report time spent on different activities
	318	.PP
	319	\f[V]--fine-only\f[R]
	320	.PD 0
	321	.P
	322	.PD
	323	use only fine-grained tree
	324	.PP
	325	\f[V]--color\f[R]
	326	.PD 0
	327	.P
	328	.PD
	329	force colorization of output
	330	.PP
	331	\f[V]--lang\f[R] \f[I]arg\f[R]
	332	.PD 0
	333	.P
	334	.PD
	335	force specific language (\f[V]c\f[R], \f[V]cxx\f[R], \f[V]make\f[R],
	336	\f[V]lua\f[R]) and disable auto-detection
	337	.SH BEHAVIOUR
	338	.SS Pager
	339	.PP
	340	When output is a terminal (not the case when invoked by Git),
	341	\f[V]less\f[R] is spawn if output is about the size of the screen.
	342	.SS Language detection
	343	.PP
	344	By default language is auto-detected based on file name.
	345	When name is not recognized the file is parsed as C.
	346	.SH TOOLS
	347	.PP
	348	\f[B]zs-diff\f[R](1)
	349	.PP
	350	A terminal-based syntax-aware diff.
	351	.PP
	352	\f[B]zs-find\f[R](1)
	353	.PP
	354	Grep-like tool that finds elements of source code structure.
	355	.PP
	356	\f[B]zs-gdiff\f[R](1)
	357	.PP
	358	A Qt5 GUI version of syntax-aware diff.
	359	.PP
	360	\f[B]zs-hi\f[R](1)
	361	.PP
	362	Simple syntax highlighter for xterm-256color palette.
	363	.PP
	364	\f[B]zs-stats\f[R](1)
	365	.PP
	366	Counter of lines of code.
	367	.PP
	368	\f[B]zs-tui\f[R](1)
	369	.PP
	370	TUI interface with underdefined scope of functionality.
	371	.SH AUTHORS
	372	xaizek <xaizek@posteo.net>.

File man/zs-com.1 added (mode: 100644) (index 0000000..d8a056f)
	1	.\" Automatically generated by Pandoc 2.17.1.1
	2	.\"
	3	.\" Define V font for inline verbatim, using C font in formats
	4	.\" that render this, and otherwise B font.
	5	.ie "\f[CB]x\f[]"x" \{\
	6	. ftr V B
	7	. ftr VI BI
	8	. ftr VB B
	9	. ftr VBI BI
	10	.\}
	11	.el \{\
	12	. ftr V CR
	13	. ftr VI CI
	14	. ftr VB CB
	15	. ftr VBI CBI
	16	.\}
	17	.TH "zs-com" "1" "July 19, 2022" "" ""
	18	.hy
	19
	20	.SH AUTHORS
	21	xaizek <xaizek@posteo.net>.

File man/zs-diff.1 added (mode: 100644) (index 0000000..ffc59a6)
	1	.\" Automatically generated by Pandoc 2.17.1.1
	2	.\"
	3	.\" Define V font for inline verbatim, using C font in formats
	4	.\" that render this, and otherwise B font.
	5	.ie "\f[CB]x\f[]"x" \{\
	6	. ftr V B
	7	. ftr VI BI
	8	. ftr VB B
	9	. ftr VBI BI
	10	.\}
	11	.el \{\
	12	. ftr V CR
	13	. ftr VI CI
	14	. ftr VB CB
	15	. ftr VBI CBI
	16	.\}
	17	.TH "zs-diff" "1" "July 19, 2022" "" ""
	18	.hy
	19	.SH NAME
	20	.PP
	21	\f[I]zs-diff\f[R] is a terminal-based syntax-aware diff.
	22	The syntax-aware part means that comparison isn\[cq]t sensible to
	23	formatting changes and understands general structure of its input.
	24	.PP
	25	The primary purpose of the utility is to be used as external diff by
	26	\f[V]git\f[R].
	27	.SH INVOCATION
	28	.SS Manual Form
	29	.PP
	30	\f[V]zs-diff\f[R] \f[V][options...]\f[R] \f[I]old-file\f[R]
	31	\f[I]new-file\f[R]
	32	.PP
	33	To be used in a shell.
	34	.SS Git Form
	35	.PP
	36	\f[V]zs-diff\f[R] \f[V][options...]\f[R] \f[I]path\f[R]
	37	\f[I]old-file\f[R] \f[I]old-hex\f[R] \f[I]old-mode\f[R]
	38	\f[I]new-file\f[R] \f[I]new-hex\f[R] \f[I]new-mode\f[R]
	39	.PP
	40	When Git calls external diff for a changed file.
	41	.SS Git Rename Form
	42	.PP
	43	\f[V]zs-diff\f[R] \f[V][options...]\f[R] \f[I]path\f[R]
	44	\f[I]old-file\f[R] \f[I]old-hex\f[R] \f[I]old-mode\f[R]
	45	\f[I]new-file\f[R] \f[I]new-hex\f[R] \f[I]new-mode\f[R]
	46	\f[I]new-path\f[R] \f[I]rename-msg\f[R]
	47	.PP
	48	When Git calls external diff for renamed and possibly changed file.
	49	.SS Tool-specific Options
	50	.PP
	51	\f[V]--no-refine\f[R]
	52	.PD 0
	53	.P
	54	.PD
	55	do not refine coarse results
	56	.SH USAGE AND BEHAVIOUR
	57	.SS Invoking manually
	58	.PP
	59	Just do:
	60	.IP
	61	.nf
	62	\f[C]
	63	zs-diff old-file new-file
	64	\f[R]
	65	.fi
	66	.SS When Invoked by Git
	67	.PP
	68	If parsing fails when Git-like invocation is used, the tool attempts to
	69	invoke \f[V]git\f[R] with \f[V]--no-ext-diff\f[R] to do the diff.
	70	Unfortunately, Git doesn\[cq]t supply enough information for a proper
	71	invocation and \f[V]git\f[R]-header you\[cq]ll see will be with blob
	72	hashes or temporary paths.
	73	.SS Use with Git without Configuration
	74	.PP
	75	Use \f[V]$GIT_EXTERNAL_DIFF\f[R]:
	76	.IP
	77	.nf
	78	\f[C]
	79	GIT_EXTERNAL_DIFF=\[aq]zs-diff --color\[aq] git show --ext-diff
	80	\f[R]
	81	.fi
	82	.SS Local Git integration
	83	.PP
	84	Add \f[V]zs-diff\f[R] as a diff tool to \f[V]git\f[R] with these lines
	85	(\f[V].git/config\f[R]):
	86	.IP
	87	.nf
	88	\f[C]
	89	[diff \[dq]zs-diff\[dq]]
	90	command = zs-diff --color
	91	\f[R]
	92	.fi
	93	.PP
	94	Then configure which files it should be used for
	95	(\f[V].git/info/attributes\f[R]):
	96	.IP
	97	.nf
	98	\f[C]
	99	*.[ch] diff=zs-diff
	100	*.h.in diff=zs-diff
	101
	102	*.[ch]pp diff=zs-diff
	103
	104	Makefile diff=zs-diff
	105	Makefile.am diff=zs-diff
	106	Makefile.win diff=zs-diff
	107
	108	*.lua diff=zs-diff
	109	\f[R]
	110	.fi
	111	.PP
	112	This will make it work for \f[V]git diff\f[R] and \f[V]git show\f[R],
	113	but \f[V]git log\f[R] and other subcommands don\[cq]t use custom diff
	114	tools by default and need \f[V]--ext-diff\f[R] option to be specified
	115	(can be done in an alias).
	116	.SS Global Git integration
	117	.PP
	118	Same as above, but specify attributes in
	119	\f[V]\[ti]/.config/git/attributes\f[R] and use one of the following
	120	files for configuration:
	121	.IP \[bu] 2
	122	\f[V]\[ti]/.config/git/config\f[R]
	123	.IP \[bu] 2
	124	\f[V]\[ti]/.gitconfig\f[R]
	125	.SS Explicit use in Git
	126	.PP
	127	Interactive (say \f[V]y\f[R] to view specific file):
	128	.IP
	129	.nf
	130	\f[C]
	131	git difftool -x zs-diff
	132	\f[R]
	133	.fi
	134	.SH SEE ALSO
	135	.PP
	136	\f[B]zograscope\f[R](7) for common options and list of all tools there.
	137	.SH AUTHORS
	138	xaizek <xaizek@posteo.net>.

File man/zs-find.1 added (mode: 100644) (index 0000000..726fb1e)
	1	'\" t
	2	.\" Automatically generated by Pandoc 2.17.1.1
	3	.\"
	4	.\" Define V font for inline verbatim, using C font in formats
	5	.\" that render this, and otherwise B font.
	6	.ie "\f[CB]x\f[]"x" \{\
	7	. ftr V B
	8	. ftr VI BI
	9	. ftr VB B
	10	. ftr VBI BI
	11	.\}
	12	.el \{\
	13	. ftr V CR
	14	. ftr VI CI
	15	. ftr VB CB
	16	. ftr VBI CBI
	17	.\}
	18	.TH "zs-find" "1" "July 19, 2022" "" ""
	19	.hy
	20	.SH NAME
	21	.PP
	22	\f[I]zs-find\f[R] is a tool for searching in code.
	23	Applications include things like collecting crude statistics about the
	24	code, looking for certain nested configurations or sequences of tokens.
	25	.PP
	26	The syntax and matching abilities are relatively basic and are subject
	27	to significant changes in the future.
	28	.SH INVOCATION
	29	.PP
	30	\f[V]zs-find\f[R] \f[V][options...]\f[R] \f[I][paths\&...]\f[R] :
	31	\f[I]matchers\&...\f[R]
	32	.PP
	33	\f[V]zs-find\f[R] \f[V][options...]\f[R] \f[I][paths\&...]\f[R] :
	34	\f[I][matchers\&...]\f[R] : \f[I][expressions\&...]\f[R]
	35	.PP
	36	\f[V]zs-find\f[R] \f[V][options...]\f[R] \f[I][paths\&...]\f[R] ::
	37	\f[I]expressions\&...\f[R]
	38	.PP
	39	Paths can specify both files and directories.
	40	When no path is specified, \[lq].\[rq] is assumed.
	41	.PP
	42	Either \f[I]matchers\&...\f[R], \f[I]expressions\&...\f[R] or both must
	43	be specified.
	44	.SS Tool-specific Options
	45	.PP
	46	\f[V]-c\f[R], \f[V]--count\f[R]
	47	.PD 0
	48	.P
	49	.PD
	50	only count matches and report statistics
	51	.PP
	52	\f[V]--lang\f[R]
	53	.PD 0
	54	.P
	55	.PD
	56	here this common option also limits set of files to process
	57	.SS Matchers
	58	.PP
	59	.TS
	60	tab(@);
	61	l l.
	62	T{
	63	Matcher
	64	T}@T{
	65	Description
	66	T}
	67	_
	68	T{
	69	\f[V]decl\f[R]
	70	T}@T{
	71	Any sort of declaration
	72	T}
	73	T{
	74	\f[V]stmt\f[R]
	75	T}@T{
	76	Statements
	77	T}
	78	T{
	79	\f[V]func\f[R]
	80	T}@T{
	81	Functions (their definitions only)
	82	T}
	83	T{
	84	\f[V]call\f[R]
	85	T}@T{
	86	Function invocations
	87	T}
	88	T{
	89	\f[V]param\f[R]
	90	T}@T{
	91	Parameters of a function
	92	T}
	93	T{
	94	\f[V]comm\f[R]
	95	T}@T{
	96	Comments of any kind
	97	T}
	98	T{
	99	\f[V]dir\f[R]
	100	T}@T{
	101	Preprocessor-alike directives
	102	T}
	103	T{
	104	\f[V]block\f[R]
	105	T}@T{
	106	Containers of statements
	107	T}
	108	.TE
	109	.SS Expressions
	110	.PP
	111	Each expressions matches a single token.
	112	.PP
	113	.TS
	114	tab(@);
	115	l l.
	116	T{
	117	Expr
	118	T}@T{
	119	What it matches
	120	T}
	121	_
	122	T{
	123	\f[V]x\f[R]
	124	T}@T{
	125	Exactly \f[V]x\f[R]
	126	T}
	127	T{
	128	\f[V]/\[ha]x/\f[R]
	129	T}@T{
	130	Any token that starts with \f[V]x\f[R]
	131	T}
	132	T{
	133	\f[V]/x$/\f[R]
	134	T}@T{
	135	Any token that ends with \f[V]x\f[R]
	136	T}
	137	T{
	138	\f[V]/\[ha]x$/\f[R]
	139	T}@T{
	140	Exactly \f[V]x\f[R]
	141	T}
	142	T{
	143	\f[V]/x/\f[R]
	144	T}@T{
	145	Any token that contains \f[V]x\f[R] as a substring
	146	T}
	147	T{
	148	\f[V]//x/\f[R]
	149	T}@T{
	150	Regular expression \f[V]x\f[R]
	151	T}
	152	T{
	153	\f[V]//\f[R]
	154	T}@T{
	155	Any token
	156	T}
	157	.TE
	158	.SH EXAMPLES
	159	.PP
	160	List all comments in C files:
	161	.IP
	162	.nf
	163	\f[C]
	164	zs-find --lang c : dir
	165	\f[R]
	166	.fi
	167	.PP
	168	Count number of preprocessor directives inside functions in all
	169	supported languages:
	170	.IP
	171	.nf
	172	\f[C]
	173	zs-find --count src/ : func dir
	174	\f[R]
	175	.fi
	176	.PP
	177	Print functions of a specific file if they contain \f[V]return\f[R]
	178	statement:
	179	.IP
	180	.nf
	181	\f[C]
	182	zs-find src/utils/time.hpp : func : return
	183	\f[R]
	184	.fi
	185	.PP
	186	List all statements containing uses of \f[V]exec()\f[R] family of
	187	functions:
	188	.IP
	189	.nf
	190	\f[C]
	191	zs-find : stmt : \[aq]//\[ha](execl[pe]?\|execvp?e?)$/\[aq]
	192	\f[R]
	193	.fi
	194	.PP
	195	List all invocations of \f[V]snprintf\f[R] which have single token as
	196	the first argument:
	197	.IP
	198	.nf
	199	\f[C]
	200	zs-find ../src : call : snprintf \[aq](\[aq] // ,
	201	\f[R]
	202	.fi
	203	.SH SEE ALSO
	204	.PP
	205	\f[B]zograscope\f[R](7) for common options and list of all tools there.
	206	.SH AUTHORS
	207	xaizek <xaizek@posteo.net>.

File man/zs-gdiff.1 added (mode: 100644) (index 0000000..6fc4f73)
	1	.\" Automatically generated by Pandoc 2.17.1.1
	2	.\"
	3	.\" Define V font for inline verbatim, using C font in formats
	4	.\" that render this, and otherwise B font.
	5	.ie "\f[CB]x\f[]"x" \{\
	6	. ftr V B
	7	. ftr VI BI
	8	. ftr VB B
	9	. ftr VBI BI
	10	.\}
	11	.el \{\
	12	. ftr V CR
	13	. ftr VI CI
	14	. ftr VB CB
	15	. ftr VBI CBI
	16	.\}
	17	.TH "zs-gdiff" "1" "July 19, 2022" "" ""
	18	.hy
	19	.SH NAME
	20	.PP
	21	\f[I]zs-gdiff\f[R] is a GUI syntax-aware diff that uses Qt5.
	22	See \f[B]zs-diff\f[R](1) for more details and comparison against other
	23	tools.
	24	.PP
	25	The tool can either accept two files on command-line, be integrated with
	26	\f[V]git\f[R] by its means (yet using external GUI tools from
	27	\f[V]git\f[R] isn\[cq]t very convenient in general) or pick up list of
	28	changed files in the repository (staged or unstaged in index or from a
	29	commit) by itself.
	30	The latter way of using \f[V]zs-gdiff\f[R] with \f[V]git\f[R]
	31	doesn\[cq]t require any configuration and allows going through files
	32	without restarting it, unlike when \f[V]git\f[R] invokes external tools.
	33	.PP
	34	It works, but it\[cq]s far from being polished.
	35	.SH INVOCATION
	36	.SS Manual Form
	37	.PP
	38	\f[V]zs-gdiff\f[R] \f[V][options...]\f[R] \f[I]old-file\f[R]
	39	\f[I]new-file\f[R]
	40	.PP
	41	To be used in a shell.
	42	.SS Git Status Form
	43	.PP
	44	\f[V]zs-gdiff\f[R] [\f[V]--cached\f[R]]
	45	.PP
	46	To be used in a shell to view staged/unstaged changes.
	47	.SS Git Commit Form
	48	.PP
	49	\f[V]zs-gdiff\f[R] \f[I]git-reference\f[R]
	50	.PP
	51	To be used in a shell to view commit changes.
	52	.SS Git Form
	53	.PP
	54	\f[V]zs-gdiff\f[R] \f[V][options...]\f[R] \f[I]path\f[R]
	55	\f[I]old-file\f[R] \f[I]old-hex\f[R] \f[I]old-mode\f[R]
	56	\f[I]new-file\f[R] \f[I]new-hex\f[R] \f[I]new-mode\f[R]
	57	.PP
	58	When Git calls external diff for a changed file.
	59	.SS Git Rename Form
	60	.PP
	61	\f[V]zs-gdiff\f[R] \f[V][options...]\f[R] \f[I]path\f[R]
	62	\f[I]old-file\f[R] \f[I]old-hex\f[R] \f[I]old-mode\f[R]
	63	\f[I]new-file\f[R] \f[I]new-hex\f[R] \f[I]new-mode\f[R]
	64	\f[I]new-path\f[R] \f[I]rename-msg\f[R]
	65	.PP
	66	When Git calls external diff for renamed and possibly changed file.
	67	.SS Tool-specific Options
	68	.PP
	69	\f[V]--cached\f[R]
	70	.PD 0
	71	.P
	72	.PD
	73	use staged changes instead of unstaged
	74	.SH SEE ALSO
	75	.PP
	76	\f[B]zograscope\f[R](7) for common options and list of all tools there.
	77	.SH AUTHORS
	78	xaizek <xaizek@posteo.net>.

File man/zs-grep.1 added (mode: 100644) (index 0000000..c474fb3)
	1	.\" Automatically generated by Pandoc 2.17.1.1
	2	.\"
	3	.\" Define V font for inline verbatim, using C font in formats
	4	.\" that render this, and otherwise B font.
	5	.ie "\f[CB]x\f[]"x" \{\
	6	. ftr V B
	7	. ftr VI BI
	8	. ftr VB B
	9	. ftr VBI BI
	10	.\}
	11	.el \{\
	12	. ftr V CR
	13	. ftr VI CI
	14	. ftr VB CB
	15	. ftr VBI CBI
	16	.\}
	17	.TH "zs-grep" "1" "July 19, 2022" "" ""
	18	.hy
	19
	20	.SH AUTHORS
	21	xaizek <xaizek@posteo.net>.

File man/zs-hi.1 added (mode: 100644) (index 0000000..22ee0ed)
	1	.\" Automatically generated by Pandoc 2.17.1.1
	2	.\"
	3	.\" Define V font for inline verbatim, using C font in formats
	4	.\" that render this, and otherwise B font.
	5	.ie "\f[CB]x\f[]"x" \{\
	6	. ftr V B
	7	. ftr VI BI
	8	. ftr VB B
	9	. ftr VBI BI
	10	.\}
	11	.el \{\
	12	. ftr V CR
	13	. ftr VI CI
	14	. ftr VB CB
	15	. ftr VBI CBI
	16	.\}
	17	.TH "zs-hi" "1" "July 19, 2022" "" ""
	18	.hy
	19	.SH NAME
	20	.PP
	21	\f[I]zs-hi\f[R] is a primitive code highlighter for terminal.
	22	The main purpose is testing and debugging of code parsing, but it can
	23	also be used on its own.
	24	.PP
	25	The only hard-coded color scheme at the moment is for xterm-256color
	26	palette.
	27	.SH INVOCATION
	28	.PP
	29	\f[V]zs-hi\f[R] \f[V][options...]\f[R] \f[I][{path\|-}]\f[R]
	30	.PP
	31	Not providing \f[I]path\f[R] argument is equivalent to specifying
	32	\f[V]-\f[R] and thus reading from standard input.
	33	.SH EXAMPLES
	34	.SS Highlighting standard input
	35	.IP
	36	.nf
	37	\f[C]
	38	pahole -C key_chunk_t vifm \| zs-hi
	39	\f[R]
	40	.fi
	41	.SS Highlighting a file
	42	.IP
	43	.nf
	44	\f[C]
	45	zs-hi utils.c
	46	\f[R]
	47	.fi
	48	.SS Checking if code parses correctly
	49	.PP
	50	Whether the parser is able to handle given sources can be checked like
	51	this:
	52	.IP
	53	.nf
	54	\f[C]
	55	find -name \[aq]*.[hc]\[aq] -exec zs-hi --dry {} \[rs];
	56	\f[R]
	57	.fi
	58	.PP
	59	It produces output for files with which it has issues.
	60	.SH SEE ALSO
	61	.PP
	62	\f[B]zograscope\f[R](7) for common options and list of all tools there.
	63	.SH AUTHORS
	64	xaizek <xaizek@posteo.net>.

File man/zs-stats.1 added (mode: 100644) (index 0000000..984d24e)
	1	.\" Automatically generated by Pandoc 2.17.1.1
	2	.\"
	3	.\" Define V font for inline verbatim, using C font in formats
	4	.\" that render this, and otherwise B font.
	5	.ie "\f[CB]x\f[]"x" \{\
	6	. ftr V B
	7	. ftr VI BI
	8	. ftr VB B
	9	. ftr VBI BI
	10	.\}
	11	.el \{\
	12	. ftr V CR
	13	. ftr VI CI
	14	. ftr VB CB
	15	. ftr VBI CBI
	16	.\}
	17	.TH "zs-stats" "1" "July 19, 2022" "" ""
	18	.hy
	19	.SH NAME
	20	.PP
	21	\f[I]zs-stats\f[R] is a tool for counting:
	22	.IP \[bu] 2
	23	lines of code
	24	.IP \[bu] 2
	25	size of functions (complete definition)
	26	.IP \[bu] 2
	27	number of functions
	28	.IP \[bu] 2
	29	number of parameters of functions
	30	.IP \[bu] 2
	31	possibly other things in the future
	32	.SH INVOCATION
	33	.PP
	34	\f[V]zs-stats\f[R] \f[V][options...]\f[R] \f[I][paths\&...]\f[R]
	35	.PP
	36	Paths can specify both files and directories.
	37	When no path is specified, \[lq].\[rq] is assumed.
	38	.SS Tool-specific Options
	39	.PP
	40	\f[V]--annotate\f[R]
	41	.PD 0
	42	.P
	43	.PD
	44	print source code annotated with line types
	45	.PP
	46	\f[V]--lang\f[R]
	47	.PD 0
	48	.P
	49	.PD
	50	here this common option also limits set of files to process
	51	.SH OPERATION
	52	.PP
	53	Differences from some similar tools:
	54	.IP \[bu] 2
	55	counts line containing only braces/brackets/parenthesis separately from
	56	code
	57	.IP \[bu] 2
	58	blank lines inside multiline comments are counted as comments
	59	.IP \[bu] 2
	60	blank lines inside string literals are counted as code
	61	.IP \[bu] 2
	62	can be slower due to parsing source code instead of treating it as text
	63	.IP \[bu] 2
	64	supports a few languages and new ones are harder to add
	65	.IP \[bu] 2
	66	trailing blank lines are ignored (because there are no tree nodes for
	67	them, although it\[cq]s possible to add them)
	68	.IP \[bu] 2
	69	last line continuation in macros in C aren\[cq]t recognized due to lack
	70	of tokenization of preprocessor directives; in C++ it might not be
	71	recognized due to SrcML bugs
	72	.SH SEE ALSO
	73	.PP
	74	\f[B]zograscope\f[R](7) for common options and list of all tools there.
	75	.SH AUTHORS
	76	xaizek <xaizek@posteo.net>.

File man/zs-tui.1 added (mode: 100644) (index 0000000..6372028)
	1	.\" Automatically generated by Pandoc 2.17.1.1
	2	.\"
	3	.\" Define V font for inline verbatim, using C font in formats
	4	.\" that render this, and otherwise B font.
	5	.ie "\f[CB]x\f[]"x" \{\
	6	. ftr V B
	7	. ftr VI BI
	8	. ftr VB B
	9	. ftr VBI BI
	10	.\}
	11	.el \{\
	12	. ftr V CR
	13	. ftr VI CI
	14	. ftr VB CB
	15	. ftr VBI CBI
	16	.\}
	17	.TH "zs-tui" "1" "July 19, 2022" "" ""
	18	.hy
	19	.SH NAME
	20	.PP
	21	\f[V]zs-tui\f[R] is a TUI version for processing files, whose scope is
	22	yet to be defined.
	23	So far it lists files or functions along with their size and parameter
	24	count and allows viewing those items in source code as well as viewing
	25	dump of their internal representation.
	26	.PP
	27	It\[cq]s not clear if it\[cq]s worth adding diffing functionality here.
	28	It\[cq]s probably not, which means that this tool will be mostly for
	29	interactive browsing or similar activities and other tools might be
	30	extracted out of it.
	31	.SH INVOCATION
	32	.PP
	33	\f[V]zs-tui\f[R] \f[V][options...]\f[R] \f[I][paths\&...]\f[R]
	34	.PP
	35	Paths can specify both files and directories.
	36	When no path is specified, \[lq].\[rq] is assumed.
	37	.SS Tool-specific Options
	38	.PP
	39	\f[V]--lang\f[R]
	40	.PD 0
	41	.P
	42	.PD
	43	here this common option also limits set of files to process
	44	.SH CONTROLS
	45	.PP
	46	Supported Vim-like shortcuts:
	47	.IP \[bu] 2
	48	\f[V]G\f[R] \[en] to last line
	49	.IP \[bu] 2
	50	\f[V]gg\f[R] \[en] to first line
	51	.IP \[bu] 2
	52	\f[V]j\f[R] \[en] to the item below
	53	.IP \[bu] 2
	54	\f[V]k\f[R] \[en] to the item above
	55	.PP
	56	Other shortcuts:
	57	.IP \[bu] 2
	58	\f[I]files\f[R] view:
	59	.RS 2
	60	.IP \[bu] 2
	61	\f[V]c\f[R] \[en] enter code view
	62	.IP \[bu] 2
	63	\f[V]d\f[R] \[en] enter dump view
	64	.IP \[bu] 2
	65	\f[V]f\f[R] \[en] switch to functions view
	66	.IP \[bu] 2
	67	\f[V]q\f[R] \[en] quit the application
	68	.RE
	69	.IP \[bu] 2
	70	\f[I]functions\f[R] view:
	71	.RS 2
	72	.IP \[bu] 2
	73	\f[V]c\f[R] \[en] enter code view
	74	.IP \[bu] 2
	75	\f[V]d\f[R] \[en] enter dump view
	76	.IP \[bu] 2
	77	\f[V]f\f[R] \[en] switch to files view
	78	.IP \[bu] 2
	79	\f[V]q\f[R] \[en] quit the application
	80	.RE
	81	.IP \[bu] 2
	82	\f[I]code\f[R] view:
	83	.RS 2
	84	.IP \[bu] 2
	85	\f[V]c/q\f[R] \[en] leave code view
	86	.RE
	87	.IP \[bu] 2
	88	\f[I]dump\f[R] view:
	89	.RS 2
	90	.IP \[bu] 2
	91	\f[V]d/q\f[R] \[en] leave dump view
	92	.RE
	93	.SH SEE ALSO
	94	.PP
	95	\f[B]zograscope\f[R](7) for common options and list of all tools there.
	96	.SH AUTHORS
	97	xaizek <xaizek@posteo.net>.

File tools/diff/README.md changed (mode: 100644) (index defcfbb..074b99f)
...	...	Complicated changes of expressions or rewrites of functions might produce
21	21	results that are hard to understand. Small or medium changes should be mostly	results that are hard to understand. Small or medium changes should be mostly
22	22	handled well.	handled well.
23	23
	24		## Documentation ##
	25
	26		See the [manual page][manual] for more details.
	27
24	28	## Comparison ##	## Comparison ##
25	29
	30		(This section is outdated and needs an update.)
	31
26	32	This section presents various kinds of alternative diffs and demonstrates why	This section presents various kinds of alternative diffs and demonstrates why
27	33	syntax-aware ones are useful.	syntax-aware ones are useful.
28	34

...	...	Fine-grained matching would benefit from improvements as well as change
81	87	detection for more complicated cases in general, but changes that were applied	detection for more complicated cases in general, but changes that were applied
82	88	to this piece of code are quite easy to see and reason about.	to this piece of code are quite easy to see and reason about.
83	89
84		## Running without integration ##
85
86		### Outside git repository ###
87
88		Just do:
89
90		```bash
91		zs-diff old-file new-file
92		```
93
94		### Inside git repository ###
95
96		Interactive (say `y` to view specific file):
97
98		```bash
99		git difftool -x zs-diff
100		```
101
102		Non-interactive (there might be errors printed for files that are failed to
103		parse, which is fine):
104
105		```bash
106		GIT_EXTERNAL_DIFF='zs-diff --color' git show --ext-diff
107		```
108
109		## Integrating into Git ##
110
111		### For a single repository ###
112
113		Add `zs-diff` as a diff tool to `git` with these lines (`.git/config`):
114
115		```gitconfig
116		[diff "zs-diff"]
117		command = zs-diff --color
118		```
119
120		Then configure which files it should be used for (`.git/info/attributes`):
121
122		```gitattributes
123		*.[ch] diff=zs-diff
124		*.h.in diff=zs-diff
125
126		*.[ch]pp diff=zs-diff
127
128		Makefile diff=zs-diff
129		Makefile.am diff=zs-diff
130		Makefile.win diff=zs-diff
131
132		*.lua diff=zs-diff
133		```
134
135		This will make it work for `git diff`, but `git show`, `git log` or other
136		subcommands don't use custom diff tools by default and require `--ext-diff`
137		option to be specified and might require use of an alias.
138
139		If parsing or comparison failed for some reason, `git diff --no-ext` will be
140		called to produce diff so in the worst case a regular diff will be displayed.
141
142		### Globally ###
143
144		Same as above, but specify attributes in `~/.config/git/attributes` and use one of the following files for configuration:
145
146		* `~/.config/git/config`
147		* `~/.gitconfig`
148
149	90	[zograscope]: ../../README.md	[zograscope]: ../../README.md
150	91
	92		[manual]: ../../docs/zs-diff.md
151	93	[diff-highlight]: https://github.com/git/git/tree/master/contrib/diff-highlight	[diff-highlight]: https://github.com/git/git/tree/master/contrib/diff-highlight
152	94	[cdiff]: https://github.com/ymattw/cdiff	[cdiff]: https://github.com/ymattw/cdiff
153	95	[icdiff]: https://www.jefftk.com/icdiff	[icdiff]: https://www.jefftk.com/icdiff

File tools/find/README.md changed (mode: 100644) (index b11535f..339732f)
...	...	configurations or sequences tokens.
11	11	The syntax and matching abilities are relatively basic and are subject to	The syntax and matching abilities are relatively basic and are subject to
12	12	significant changes in the future.	significant changes in the future.
13	13
14		## Examples ##
	14		## Documentation ##
15	15
16		List all comments in C files:
17
18		```
19		zs-find --lang c : dir
20		```
21
22		Count number of preprocessor directives inside functions in all supported
23		languages:
24
25		```
26		zs-find --count src/ : func dir
27		```
28
29		Print functions of a specific file if they contain `return` statement:
30
31		```
32		zs-find src/utils/time.hpp : func : return
33		```
34
35		List all statements containing uses of `exec()` family of functions:
36
37		```
38		zs-find : stmt : '//^(execl[pe]?\|execvp?e?)$/'
39		```
40
41		List all invocations of `snprintf` which have single token as the first
42		argument:
43
44		```
45		zs-find ../src : call : snprintf '(' // ,
46		```
	16		See the [manual page][manual] for more details.
47	17
48	18	[zograscope]: ../../README.md	[zograscope]: ../../README.md
	19		[manual]: ../../docs/zs-find.md

File tools/gdiff/README.md changed (mode: 100644) (index e5a0845..457dba4)
5	5	## Description ##	## Description ##
6	6
7	7	`zs-gdiff` is a GUI syntax-aware diff that uses Qt5. See [description of	`zs-gdiff` is a GUI syntax-aware diff that uses Qt5. See [description of
8		zs-diff][zs-diff] for more details and comparison agains other tools.
	8		zs-diff][zs-diff] for more details and comparison against other tools.
9	9
10	10	The tool can either accept two files on command-line, be integrated with `git`	The tool can either accept two files on command-line, be integrated with `git`
11	11	by its means (yet using external GUI tools from `git` isn't very convenient in	by its means (yet using external GUI tools from `git` isn't very convenient in

...	...	There are some issues due to Qt's support for displaying code being in a quite
20	20	bad state. However, the tool is usable. The issues could be resolved or	bad state. However, the tool is usable. The issues could be resolved or
21	21	different GUI toolkit could be used in the future.	different GUI toolkit could be used in the future.
22	22
	23		## Documentation ##
	24
	25		See the [manual page][manual] for more details.
	26
23	27	[zograscope]: ../../README.md	[zograscope]: ../../README.md
	28		[manual]: ../../docs/zs-gdiff.md
24	29	[zs-diff]: ../diff/README.md	[zs-diff]: ../diff/README.md

File tools/hi/README.md changed (mode: 100644) (index f7eea33..801b176)
...	...	testing and debugging of code parsing, but it can also be used on its own.
9	9
10	10	The only hard-coded color scheme at the moment is for xterm-256color palette.	The only hard-coded color scheme at the moment is for xterm-256color palette.
11	11
12		## Checking if code parses correctly ##
	12		## Documentation ##
13	13
14		Whether the parser is able to handle given sources can be checked using command
15		like this:
16
17		```
18		find -name '*.[hc]' -exec zs-hi --dry {} \;
19		```
20
21		It produces output for files with which it has issues.
	14		See the [manual page][manual] for more details.
22	15
23	16	[zograscope]: ../../README.md	[zograscope]: ../../README.md
	17		[manual]: ../../docs/zs-hi.md

File tools/stats/README.md changed (mode: 100644) (index e3521a3..a0a0768)
11	11	* number of parameters of functions	* number of parameters of functions
12	12	* possibly other things in the future	* possibly other things in the future
13	13
14		## Differences ##
	14		## Documentation ##
15	15
16		Differences from some similar tools:
17		* counts line containing only braces/brackets/parenthesis separately from code
18		* blank lines inside multiline comments are counted as comments
19		* blank lines inside string literals are counted as code
20		* can be slower due to parsing source code instead of treating it as text
21		* supports a few languages and new ones are harder to add
22		* trailing blank lines are ignored (because there are no tree nodes for them,
23		although it's possible to add them)
24		* last line continuation in macros in C aren't recognized due to lack of
25		tokenization of preprocessor directives; in C++ it might not be recognized
26		due to srcml bugs
	16		See the [manual page][manual] for more details.
27	17
28	18	[zograscope]: ../../README.md	[zograscope]: ../../README.md
	19		[manual]: ../../docs/zs-stats.md

File tools/tui/README.md changed (mode: 100644) (index 1f63aa9..23dbbc6)
...	...	It's not clear if it's worth adding diffing functionality here. It's probably
13	13	not, which means that this tool will be mostly for interactive browsing or	not, which means that this tool will be mostly for interactive browsing or
14	14	similar activities and other tools might be extracted out of it.	similar activities and other tools might be extracted out of it.
15	15
	16		## Documentation ##
	17
	18		See the [manual page][manual] for more details.
	19
16	20	[zograscope]: ../../README.md	[zograscope]: ../../README.md
	21		[manual]: ../../docs/zs-tui.md

File tools/tui/tui.cpp changed (mode: 100644) (index 261854b..99dd628)
...	...	R"(Usage: zs-tui [options...] [paths...]
45	45
46	46	Paths can specify both files and directories. When no path is specified, "." is	Paths can specify both files and directories. When no path is specified, "." is
47	47	assumed.	assumed.
48
49		Supported Vim-like shortcuts: G, gg, j and k.
50
51		Other shortcuts:
52		* files view:
53		- c -- enter code view
54		- d -- enter dump view
55		- f -- switch to functions view
56		- q -- quit the application
57		* functions view:
58		- c -- enter code view
59		- d -- enter dump view
60		- f -- switch to files view
61		- q -- quit the application
62		* code view:
63		- c/q -- leave code view
64		* dump view:
65		- d/q -- leave dump view
66	48	)";	)";
67	49
68	50	const int InputBufferWidth = 10;	const int InputBufferWidth = 10;

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