Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
VCS_dev(3)	      User Contributed Perl Documentation	    VCS_dev(3)

NAME
       VCS_dev - Information for VCS::*	developers

SYNOPSIS
       VCS_dev provides	internal API information for generic VCS::*
       programming access in Perl.  This document is for VCS::*	developers,
       not necessarily for users of VCS	itself.

DESCRIPTION
       "VCS" is	an API for abstracting access to all version control systems
       from Perl code. This is achieved	in a similar fashion to	the "DBI"
       suite of	modules. There are "container" classes,	"VCS::Dir",
       "VCS::File", and	"VCS::Version",	and "implementation" classes, such as
       "VCS::Cvs::Dir",	"VCS::Cvs::File", and "VCS::Cvs::Version", which are
       subclasses of their respective "container" classes.

       The container classes are instantiated with URLs. There is a URL	scheme
       for entities under version control. The format is as follows:

	   vcs://localhost/VCS::Cvs/fs/path/?query=1

       The "query" part	is ignored for now. The	path must be an	absolute path,
       meaningful to the given class. The class	is an implementation class,
       such as "VCS::Cvs".

       The "container" classes work as follows:	when the "new" method of a
       container class is called, it will parse	the given URL, using the
       "VCS->parse_url"	method.	It will	then call the "new" of the
       implementation's	appropriate container subclass,	and return the result.
       For example,

	   VCS::Version->new('vcs://localhost/VCS::Cvs/fs/path/file/1.2');

       will return a "VCS::Cvs::Version".

Imp IMPLEMENTATION
       For the purposes	of concretely illustrating the layout of an
       implementation suppose that there is a need for a VCS::Imp or $Imp
       implementation.

       An implementation class is recognised as	follows: its name starts with
       "VCS::",	and "require "VCS/Imp.pm"" will	load the appropriate
       implementation classes corresponding to the container classes -
       "VCS::Imp::Dir",	"VCS::Imp::File" and "VCS::Imp::Version"..

       Hence in	MANIFEST, or Unix file specificaton, syntax the	Imp
       implementation ought to be composed of at least these files:

	   VCS/Imp.pm
	   VCS/Imp/Dir.pm
	   VCS/Imp/File.pm
	   VCS/Imp/Version.pm

       In addition to the usual	module distribution files such as MANIFEST,
       Makefile.PL, etc.

       Implementation classes must include documentation for their special
       requirements, such as mandatory environment variables. See VCS::Cvs for
       an example.

       If a method, or an argument to a	method makes no	sense for a particular
       implementation, then the	implementation may ignore it, but must do so
       quietly.

       The modules that	make up	a VCS implementation might act as wrappers
       around a	command	language interpreter (CLI or shell) command, or	might
       directly	look at	files or talk over the network.	It is recommended that
       before implementing a VCS::*::* class that implements direct access,
       the developer first implement a version that uses the CLI tools,	and
       writes appropriate tests	for it.	Doing this will	ensure that the
       direct-access version, which passes the tests, will be correct.

       o   VCS/Imp.pm

	   The variable	$LOG_CMD is the	CLI command for	obtaining revision
	   history logs.  This module typically	implements five	distinct non-
	   public sub routines:	"sub _boiler_plate_info	{}", "sub _split_log
	   {}",	"sub _parse_log_rev {}", "sub _parse_log_header	{}", "sub
	   _read_pipe {}" is for reading from the CLI.

       o   VCS/Imp/Dir.pm

	   This	module implements three	public sub routines/methods: "sub new
	   {}",	"sub name {}", "sub content {}".

       o   VCS/Imp/File.pm

	   Revisions should be returned	in reverse time	order (latest first,
	   oldest last).  This module implements three public sub
	   routines/methods: "sub new {}", "sub	name {}", "sub versions	{}".

       o   VCS/Imp/Version.pm

	   The variable	$DIFF_CMD is the CLI command for doing diffs.  The
	   variable $UPDATE_CMD	is the CLI command for doing updates.  This
	   module implements nine public sub routines/methods: "sub new	{}",
	   "sub	name {}", "sub version {}", "sub tags {}", "sub	text {}", "sub
	   diff	{}", "sub author {}", "sub date	{}", "sub reason {}".

EXAMPLES
       If you prefer there is a	pod stub in Imp_pod.tpl	that you could
       catenate	onto the tail of your VCS/$Imp.pm file,	making sure to edit
       the template with "s/Imp/$Your_VCS_Name/g".  For	simple version control
       system APIs (i.e. with a	CLI interface and no need for XS, C, or	header
       file worries) an	easy way to get	started	would be to use	h2xs like so:

	   h2xs	-AXf -n	VCS::Imp

       then add	a VCS/Imp/VCS directory	and put	appropriate File.pm, Dir.pm
       and Version.pm modules in it (add them the the MANIFEST as well).  If
       calling in to your version control system requires XS then omit the
       "-X" and	"-f" switches and specify the header file name.

       You might also be interested in looking at the other implementations
       for tips	on how to map your version control systems' CLI	commands to
       VCS::* methods.	For parsing details it can prove helpful to see	an
       example of the output of	some of	the other version control systems.
       (e.g. the output	of the $LOG_CMD	in typical usage).

   Cvs
       o   VCS/Cvs.pm

	   The variable	$LOG_CMD is 'cvs log'.

       o   VCS/Cvs/Dir.pm

       o   VCS/Cvs/File.pm

       o   VCS/Cvs/Version.pm

	   The variable	$DIFF_CMD is 'cvs diff -u2'.  The variable $UPDATE_CMD
	   is 'cvs update -p'.

   Rcs
       o   VCS/Rcs.pm

	   The variable	$LOG_CMD is 'rlog'.

       o   VCS/Rcs/Dir.pm

       o   VCS/Rcs/File.pm

       o   VCS/Rcs/Version.pm

	   The variable	$DIFF_CMD is 'rcsdiff -u2'.  The variable $UPDATE_CMD
	   is 'co -p'.

   Hms
       o   VCS/Hms.pm

	   The variable	$LOG_CMD is 'flog'.

       o   VCS/Hms/Dir.pm

       o   VCS/Hms/File.pm

       o   VCS/Hms/Version.pm

	   The variable	$DIFF_CMD is 'fdiff'.  The variable $UPDATE_CMD	is
	   'fco	-p'.  flog output is reversed here.

TODO
       Where are the wrappers around rcs's ci or CVS's cvs ci?	(This is
       listed as a known BUG in	that VCS is currently read only).

       Does Hms	have a fci command?

       See the pod in VCS/File.pm for other unimplemented things.

SEE ALSO
       VCS, and	the generic implementation in VCS::Dir,	VCS::File, and
       VCS::Version.

       The CVS implementation is in VCS::Cvs along with	the unpodded
       VCS/Cvs/*.pm modules.

       The Hms implementation is in VCS::Hms along with	the unpodded
       VCS/Hms/*.pm modules.

       The rcs implementation is in VCS::Rcs along with	the unpodded
       VCS/Rcs/*.pm modules.

perl v5.32.0			  2016-06-05			    VCS_dev(3)

NAME | SYNOPSIS | DESCRIPTION | Imp IMPLEMENTATION | EXAMPLES | TODO | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=VCS_dev&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help