.ig
 Copyright (C) 1993,1994 by the author(s).
 
 This software is published in the hope that it will be useful, but
 WITHOUT ANY WARRANTY for any part of this software to work correctly
 or as described in the manuals. See the ShapeTools Public License
 for details.

 Permission is granted to use, copy, modify, or distribute any part of
 this software but only under the conditions described in the ShapeTools 
 Public License. A copy of this license is supposed to have been given
 to you along with ShapeTools in a file named LICENSE. Among other
 things, this copyright notice and the Public License must be
 preserved on all copies.


Author: Andreas Lampen (Andreas.Lampen@cs.tu-berlin.de)

$Header: vbind.1[7.0] Thu Mar 10 12:15:43 1994 andy@cs.tu-berlin.de frozen $
..
.TH vbind 1 "Thu Mar 10 12:15:43 1994" "AtFStk-1.12" "ShapeTools"
.SH NAME
vbind \- bind name to version
.SH SYNOPSIS
\fBvbind\fP [ \fIoptions\fP ] filenames \.\|.
.na
.TP 1.2c
\fIGeneral version binding options:\fP
[\ \fB\-bind\fP\ \fIversion\ binding\fP\ ]
[\ \fB\-before\fP\ \fIbaseline\fP\ ]
[\ \fB\-since\fP\ \fIbaseline\fP\ ]
[\ \fB\-last\fP\ ]
[\ \fB\-lastsaved\fP\ ]
[\ \fB\-uniq\fP\ ]
[\ \fB\-nonuniq\fP\ ]
[\ \fB\-rule\fP\ \fIrulebody\fP\ |\ \fIrulename\fP\ ]
[\ \fB\-rulefile\fP\ \fIfilename\fP\ ]
[\ \fB\-trace\fP\ ]
.TP 1.2c
\fIvbind command specific options:\fP
[\ \fB\-?\fP\ (or\ \fB\-help\fP)\ ]
[\ \fB\-alias\fP\ \fIversion\ alias\fP\ ]
[\ \fB\-date\fP\ \fIdate\fP\ ]
[\ \fB\-vnum\fP\ \fIversion\ number\fP\ ]
[\ \fB\-nomsg\fP\ ]
[\ \fB\-ruledump\fP\ ]
[\ \fB\-ruleerr\fP\ ]
[\ \fB\-rulelist\fP\ ]
[\ \fB\-ruletest\fP\ ]
[\ \fB\-version\fP\ ]
.ad
.SH OVERVIEW
This manual page describes the \fIShapeTools Version Binding\fP
mechanism, available in most commands of the toolkit. The general
version binding options described on this page are available in
many commands such like vl(1), vcat(1), vadm(1), save(1) and retrv(1)
(just to name the most important ones). The vbind command specific
options are private to the vbind command (see below).
.LP
Version binding is the process of selecting one or more versions
from a filenames history in order to provides access to these
version(s). This is conducted by version bind directives (or just
\fIversion bindings\fP), which may be one of the following:
.TP 3.5c
version numbers
"\fC1.2\fP" (version), "\fC1.\fP" (generation), "\fC.2\fP" (revision)
.TP
version alias names
"\fCShapeTools-1.4\fP", or "\fCAtFS-2.0\fP"
.br
Version alias names are symbolic names tagged to single versions.
They must be unique throughout a history.
.TP
date specifications
"\fC10.2.93\fP" or "\fC4.3.\fP" (European), "\fCFeb 10, 1993\fP" or "\fCMar
4\fP{ (American)
.br
A date may additionally contain a time in the form \fIhh:mm\fP or
\fIhh:mm:ss\fP. See sttime(3) for a complete list of recognized date
formats. 
.TP
bind rule names
"\fCmost_recent:\fP" (plain), "\fCfrom_release(VC-4.0):\fP" (with argument)
.br
The colon is not part of the rule name. See the bindrules(7) manual
page for a description on how to define version bind rules.
.LP
By default, version binding selects all versions fulfilling the given
version bind requirements. The \fI-uniq\fP option changes this
behavior and treats only unique identification as success. With this
option given, version bind ignores all histories with more than one
selected version. The \fI-last\fP and \fI-lastsaved\fP options unify a
non unique selection by choosing the last version (modification/saving
time) or the last saved version (saving time) from the bind hit set of
each name.
.LP
The file \fI$SHAPETOOLS/lib/shape/BindRules\fP contains predefined
rules for various cases. You may also define your own rule file and
invoke this by either the \fI-rulefile\fP option or by extending the
search space defined by the SHAPETOOLS environment variable. For
information on how to write version bind rules, see the bindrules(7)
manual page.
.SH VERSION BINDING IN ACTION
Version bind directives can be given either in brackets, directly
following the name to be bound, or as option arguments. Options may be
user to set version bindings to be applied to all name arguments
(\fI-bind\fP and \fI-rule\fP options) or to define version ranges
(\fI-since\fP and \fI-before\fP options).
.LP
\fIVersion identification by version number\fP or \fIversion alias\fP
either results in a unique selection or fails, when no appropriate
version was found.
.TP 4c
\fCfoo[1.2]\fP
Identifies a specific version by it's version number.
.TP
\fCfoo[release-2]\fP
Is interpreted as identification by version alias name.
.LP
\fIVersion identification by date\fP selects the versions from a
history that have been the most recently saved versions at the given
date. Identification by date may lead to multiple versions when
development work in multiple generations happened simultaneously at
the given date. Vbind understands various date formats such as in the
list below. The sttime(3) manual page lists all recognized date formats.
.TP
\fCfoo[Jan 31, 1992]\fP
.TP
\fCfoo[92/01/31]\fP
.TP
\fCfoo[10.5.92 7:00:00]\fP
.LP
\fIVersion bind rules\fP describe general version binding policies.
They are usually not dependent on particular file histories and may be
applied to all histories. Version bind rules may have arguments
enclosed in parentheses following the name.
.TP 4c
\fCfoo[bind_rule:]\fP
.TP
\fCfoo[bind_rule(arg1,arg2,...argN):]\fP
.LP
When the colon at the end of the rule name in brackets is
omitted, vbind first interprets the given string as version alias.
When no version with this alias name was found, vbind treats the
string as rule name and gives it a second try.
.LP
\fIPlain filenames\fP are those not followed by any version bind directive
in square brackets. Without a rule given with the -rule option
on the command line, plain filenames are bound using the \fIdefault
version bind rule\fP. It selects the busy version if there is one, or
the most recent non busy version otherwise.
.TP
\fCeq (state, busy); max (version).\fP
.LP
The \fIdefault version binding\fP may also be indicated by an empty
pair of brackets:
\fCfoo[]\fP
.LP
.SH NAME PATTERNS
The ShapeTools version binding mechanism performs filename
substitution for given name patterns similar to sh(1). This is
necessary, as shell filename substitution does not recognize the names
of saved versions. Magic cookies are are:
.IP \f(CB*\fP 2c
matching any string, including the empty string,
.IP \f(CB?\fP
matching any single character,
.IP \f(CB[c...]\fP
matching any one of the characters enclosed in the square brackets,
.IP \f(CB[l-r]\fP
matching any character lexically between the left (\f(CBl\fP) and the
right (\f(CBr\fP) character, inclusive, and
.IP \f(CB[!c...]\fP
.IP \f(CB[!l-r]\fP
matching any character not recognized by their counterparts above.
.LP
As square brackets on the command line may either be part of a pattern
(e.g. \fC*.[ch]\fP) or a version binding (e.g. \fC*[release-2]\fP),
this may lead to some confusion. The leftmost pair of brackets is
\fIalways\fP interpreted as version binding. Hence, in the first case,
the string will be misinterpreted and you must add an explicit version
binding to avoid this (e.g. \fC*.[ch][]\fP, default version binding
added).
.SH GENERAL VERSION BINDING OPTIONS
.TP
\fB\-before\fP\ \fIbaseline\fP
Define the lower boundary of a time interval for selecting all
versions evolved in this interval. \fIBaseline\fP can be any version
bind directive uniquely selecting a version (e.g. version number,
version alias, or date). The saving date of the baseline version is
the interval start time. The boundary version (exactly matching the
time given) is \fInot\fP included in the result set. 
.TP
\fB\-bind\fP\ \fIversion binding\fP
Use \fIversion binding\fP for binding each name on the command line,
that has no explicit version binding in brackets.
.TP
\fB\-last\fP
Select the last (modification/saving time) version of each nonunique
selection. This causes the resulting version list to contain at most
one version of each history. \fI-last\fP may be combined with other
version bindings.
.TP
\fB\-lastsaved\fP
Like \fI-last\fP, but busy versions are ignored.
.TP
\fB\-nonuniq\fP
Force non-unique version identification. This option can be used to
swich off the default behavior of some commands (e.g. vadm) that
suggests unique version identification.
.TP
\fB\-rule\fP\ \fIrulename\fP\ |\ \fIrulebody\fP
With a name argument, this option sets the named rule as default rule
for binding all names on the command line. Alternatively, a rule body
(a version selection rule without a name) may be given as argument,
which will be evaluated for each name on the command line.
This option disables any previous -bind or -rule definition. It does
not affect names with a version binding in brackets.
.TP
\fB\-rulefile\fP\ \fIfilename\fP
Read in the named rule file and add all contained rules to the
list of known rules. A syntactical error, detected while parsing a
rule causes the according rule to be skipped. Use vbind(1) with the
\fI-ruleerr\fP option for inspecting bind rule files.
Multiple rule files may be specified on the command line.
.TP
\fB\-since\fP\ \fIbaseline\fP
Define the upper boundary of a time interval for selecting all versions
evolved in this interval. \fIBaseline\fP can be any version
bind directive uniquely selecting a version (e.g. version number,
version alias, or date. The saving date of the
baseline version is the interval end time. The boundary version
(exactly matching the time given) is \fInot\fP included in the result
set. 
.TP
\fB\-trace\fP
Trace the evaluation. Each evaluated predicate is reported to
standard output. Additionally, the set of versions fulfilling the
expressed  (the \fIhits set\fP) is displayed after
evaluation of each predicate.
.TP
\fB\-uniq\fP
Require unique version identification. All history names on the
command line, where multiple versions meet the version
bind requirements are ignored.
.SH THE VBIND COMMAND
\fIVbind\fP performs a version binding and returns a \fIbound
filename\fP for each selected version. A bound filename is a filename
followed by a version number enclosed in brackets (e.g. foo[1.2]).
.LP
.TP 2c
\fB\-?, \-help\fP
Display a short usage description.
.TP
\fB\-alias\fP\ \fIversion alias\fP
Use version alias for binding all names on the command line. This
disables any previous -alias, -bind, -date, -rule or -vnum definition.
It does not affect names in pseudo bound version notation.
.TP
\fB\-date\fP\ \fIdate\fP
Use date for binding all names occurring on the command line. This
disables any previous -alias, -bind, date, -rule or -vnum definition.
It does not affect names in pseudo bound version notation.
.TP
\fB\-nomsg\fP\
Suppress output produced by version bind rules.
.TP
\fB\-ruledump\fP
The -ruledump option causes all known version bind rules to be
written to standard output. The generated output contains all rule
definitions in regular format and may be used as input rulefile for
subsequent calls of vbind.
.TP
\fB\-ruleerr\fP
This option makes sense, when testing a new, hand written file
containing bind rules. The -ruleerr option causes syntax errors
detected in the rule file to be reported to standard error. Make sure,
that this option occurs on the command line prior to the rulefile to
be inspected.
.TP
\fB\-rulelist\fP
Write a list of all known rule names to standard output.
.TP
\fB\-ruletest\fP
Interpret all names on the command line as rule names and test the
existence of equally named rules in the list of known rules.
.TP
\fB\-version\fP
Print version identification of vbind command and used libraries.
.TP
\fB\-vnum\fP\ \fIversion number\fP
Use version number for binding all names on the command line. This
disables any previous -alias, -bind, -date, -rule or -vnum definition.
It does not affect names in pseudo bound version notation.
.SH ENVIRONMENT
\fISHAPETOOLS\fP \- list of path names as search space for files
containing version bind rules. The bind rule files must be named
\fIBindRules\fP. Default path is \fI/usr/local/lib/shape\fP.
.SH FILES
$SHAPETOOLS/lib/shape/BindRules
.SH SEE ALSO
vl(1), sttime(3), bindrules(7)
.SH AUTHOR
Andreas.Lampen@cs.tu-berlin.de