pchk.vim	Plugin Checker    			Nov 09, 2020

Author:    Charles E. Campbell      <NcampObell@SdrPchip.AorgM-NOSPAM>
           (remove NOSPAM from Campbell's email first)
Copyright: (c) 2016 by Charles E. Campbell     	pchk-copyright
           The VIM LICENSE applies to pchk.vim and pchk.txt
           (see copyright) except use "pchk" instead of "Vim"

1. Contents			pchk pchk-contents {{{1
	1. Contents.................: pchk-contents
	2. PChk Manual..............: pchk-manual
	3. PChk Usage...............: pchk-usage
	3. PChk History.............: pchk-history

2. PChk Manual			pchkman pchkmanual pchk-manual {{{1

				PChkTry PChkMake PChk PChkStep

    Start a test by editing it, then run one of the following four commands:

	:PChkTry	  : try the test.  Will stop at :PChkSnapshot lines
			    and :PChkPause lines
	:PChkRun          : like PChkTry, but won't stop and won't check;
			    like PChkMake, but it won't create an
			    Expected/tst###.out file
	:PChkMake	  : make an Expected/tst###.out file
	:PChk		  : compare snapshot hashes currently obtained
			    with previously obtained expected test results
	:PChkStep	  : step through each line of a test, not just at
			    the :PChkSnapshot commands.

    Test File Commands         PChkSnapshot PChkFeedkeys PChkPause

	:PChkSnapshot	  : runs a hashing algorithm over the remote display.
			    Result is saved in/compared with Expected/tst###.out
	:PChkFeedkeys ... : send keys to server.  ^X translates to control
			    characters (ie. ^M is a ENTER)
	:PChkPause	  : pause the test (uses input()).  One may
				* <cr> =continue
				* c    =check
				* s    =step
				* t    =try
	:..cmd		  : send cmd to server to execute..
	^\s*#...	  : echomsg comment in client vim (will not be sent
			    to server)
	..cmd..		  : send cmd to server to execute as a normal command
	*..reply..	  : netrw issues prompt; reply to it with this string

    Special Variables:		g:netrw_pchk
	g:netrw_pchk	  : suppresses netrw version number from banner if true
			    (avoid spurious errors due to changes in netrw versions)

3. PChk Usage	pchkusage pchk-usage pchk-userguide {{{1

	PChk provides a testing framework for plugins and requires:

	 * +clientserver (clientserver)
	   ie. :echo has("clientserver") needs to show a "1"

	 * gvim
	   ie. :echo has("gui") needs to show a "1"

	PChk runs a gvim in a server (remote instance) which is started up
	using a vim initialization file called pchk.vimrc; it is searched
	for as:

	  * pchk.vimrc (current directory)
	  * $HOME/.vim/pchk.vimrc
	  * $HOME/pchk.vimrc
	  * $VIMRUNTIME/pchk.vimrc

	The gvim being started uses

		gvim -u vimrc -U NONE --servername PCHKREMOTE

	where "vimrc" is wherever pchk found pchk.vimrc from the list above.

	A typical pchk.vimrc:

		set nocp
		filetype plugin on
		set ve=all
		set directory=$HOME/.vim/VITMP

	The last setting causes swap files to be placed in a directory
	away from the current one (pchk was developed to support netrw
	testing, and letting swap files litter the current directory
	would alter test results).

	PChk uses test files (input) which exercise the plugin.  These test files

	  * have the remote gvim run commands (ex. :let g:netrw_liststyle=3)

	  * send keys to the remote gvim (as if a user had typed them) with
	    a translation of ^[A-Z] into associated control characters

	  * send normal mode commands

	  * send response strings

	  * take a "snapshot"

	  * query remote gvim for some status via an "assert"ion

	PChk writes (output) and uses (input) Expected/*.out files which hold
	the results of the test files.

	The :PChkSnapshot command is of central importance to the PChk plugin.
	It generates a hash (an integer) which is sensitive to:

	  * geometry: each tab, each window, what windows are next to which
	    windows (left, right, above, below)

	  * the contents of each window (text and syntax)

	If any of these things that go into a hash changes, PChk will detect
	that something differs.

	A plugin may cause something to change (such as a setting or variable
	value) that is not captured by a :PChkSnapshot.  To capture such
	changes, a
		:PChkAssert command
	will act as if an ":echo command" was sent to the remote gvim and the
	results therefrom are either entered into the Expected/*.out file or
	compared with it.

	As an example, consider tst007 for netrw:

	    # c : make browsing directory the current directory
	    :let g:netrw_pchk= 1
	    :cd dir001
	    :e .
	    :e dirA
	    :PChkAssert b:netrw_curdir != getcwd()
	    :PChkAssert b:netrw_curdir == getcwd()

	This test does the following:

	    # c : make browsing directory the current directory
		nothing, its just a comment
	    :let g:netrw_pchk= 1
		tells netrw not to include the version in the banner
	    :cd dir001
		changes the directory to dir001
	    :e .
		tells netrw to generate a listing for the current directory
		record/compare a snapshot of the remote gvim state
	    :e dirA
		tells netrw to "edit" a subdirectory (dirA)
		record/compare a snapshot of the remote gvim state
	    :PChkAssert b:netrw_curdir != getcwd()
		record/compare the result of comparing the b:netrw_curdir
		variable with vim's current directory
		issues a "c" normal mode command to netrw (see netrw-c)
	    :PChkAssert b:netrw_curdir == getcwd()
		record/compare the result of comparing the b:netrw_curdir
		variable with vim's current directory

	PChk can be run in one of four ways:

		This command tells PChk to try the current file as a test.  It
		will stop at any :PChkSnapshot lines allowing one to see if
		things are going as expected.  It splits the test window and
		shows the results of the hashing in the right side window.
		This command runs PChk; like PChkTry, but it doesn't stop;
		like PChkMake, but it doesn't record an Expected/tst###.out

		This command tells PChk to run the current file as a test
		and to save the :PChkSnapshot and :PChkAssert results in
		Expected/FILENAME.out for future comparisons.

		This command tells PChk to run the current file as a test,
		comparing the current :PChkSnapshot and :PChkAssert results
		with the previously run Expected/*.out results.

	:PChkSend msg
		This command will send a message for the remote server to

4. PChk History	       		pchk-history {{{1

	v4:	Nov 09, 2020	* made s:PChkRemoteSend(msg) into
				  pchk#PChkSend(msg). Included PChkSend as a
				  command in pchkPlugin.
	v3:	Aug 21, 2016	* PChkRun included
		Nov 27, 2018	* Remote window contents, except for banner,
				  now cleared upon new invocation of PChk
		Nov 27, 2018	* Tests are now always started from the
				  initial starting directory
	v2:	Apr 05, 2016	* included sensitivity to window names
				  (using expand("%:t") )
	v1:	Nov 25, 2015	* initial release
		Feb 19, 2016	* included current window number in s:WinGeoHash()

Modelines: {{{1