This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: VcsTools/DataSpec/Rcs, Next: VcsTools/File, Prev: VcsTools/DataSpec/HpTnd, Up: Module List Rcs data description ******************** NAME ==== VcsTools::DataSpec::Rcs - Rcs data description SYNOPSIS ======== use VcsTools::DataSpec::Rcs qw($description readHook); use VcsTools::LogParser ; my $ds = new VcsTools::LogParser ( readHook => \&readHook, description => $description ) ; DESCRIPTION =========== This class contains all the custom information needed to retrieve data from an RCS log using the generic *Note VcsTools/LogParser: VcsTools/LogParser, class. The $description hash ref defines the informations that are contained in the log of each version of the RCS file. This class can be used as a template for other VCS systems and other needs. The readHook is used to find the first revision of a branch. For instance a branch is named 1.5.1 in the VCS history, the readHook will find that the actual first revision of the branch is 1.5.1.1. RCS DATA DESCRIPTION ==================== state ----- Taken from 'state' RCS field. It can be either Dead Exp or Product according to the level of confidence. branches -------- Taken from 'branches' RCS field. List the branches of a version. read-only value. author ------ Taken from 'author' RCS field. Name of the author of the revision or the name of the last guy who modified the RCS log. date ---- Date of the archive. Set by RCS. read-only value. misc ---- Miscellaneous comments about this version. AUTHOR ====== Dominique Dumont, Dominique_Dumont@grenoble.hp.com Copyright (c) 1998-1999 Dominique Dumont. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== perl(1)  File: pm.info, Node: VcsTools/File, Next: VcsTools/FileAgent, Prev: VcsTools/DataSpec/Rcs, Up: Module List Perl class to manage a VCS file. ******************************** NAME ==== VcsTools::File - Perl class to manage a VCS file. SYNOPSIS ======== my %dbhash; # may be tied to a MLDBM use VcsTools::LogParser ; use VcsTools::DataSpec::HpTnd qw($description readHook); use Puppet::Storage ; use VcsTools::HmsAgent ; # could be also RcsAgent my $ds = new VcsTools::DataSpec::HpTnd ; my $ds = new VcsTools::LogParser ( description => $description, readHook => \&readHook ) ; Puppet::Storage->dbHash(\%dbhash); Puppet::Storage->keyRoot('root'); my $storage= new Puppet::Storage(name => 'dummy.txt') ; VcsTools::HmsAgent->hmsBase('test'); VcsTools::HmsAgent->hmsHost('a_host'); my $agent = VcsTools::HmsAgent->new ( name => 'dummy.txt', workDir => cwd().'/'.$dir ); my $vf = new VcsTools::File ( storage => $storage , vcsAgent => $agent, name => 'dummy.txt', workDir => $some_dir, dataScanner => $ds ); $vf -> createArchive(); $vf -> checkOut(revision => '1.1', lock => 1) ; $vf -> archiveFile(info =>{log => 'dummy log for 1.2'}); $vf -> showDiff(rev1 => '1.1', rev2 => '1.2'); $vf -> setUpMerge(ancestor => '1.1', below => '1.2', other => '1.1.1.1'); DESCRIPTION =========== This class represents a VCS file. It holds all the interfaces to the "real" world and the history object (See *Note VcsTools/History: VcsTools/History,)). Firthermore, this class will store the file and archive properties (like s the file readable, does the archive exists, is it locked...) in a *Note Storable: Storable, file (within a .store directory) CAVEATS ======= The file must contain the `$Revision: 1.5 $' VCS keyword. The VCS agent (hmsAgent) creation is clumsy. I should use translucent attributes or stuff like that like Tom Christiansen described. In other words, let the user create its agent object and clone it for File usage. This part is subject to change sooner of later. Only the constructors should be impacted. CONVENTION ========== The following words may be non ambiguous for native english speakers, but it is not so with us french people. So I prefer clarify these words: * Log: Refers to the information stored with one version. * History: Refers to a collection of all logs of all versions stored in the VCS base. Constructor =========== new(...) -------- Will create a new File object. Parameters are those of `"new(...)"', *Note Puppet/Body: Puppet/Body, plus : * dataScanner : *Note VcsTools/LogParser: VcsTools/LogParser, (or equivalent) object reference. * workDir : Absolute directory where the file is. * vcsAgent : VCS interface object (e.g. *Note VcsTools/HmsAgent: VcsTools/HmsAgent,). Generic methods =============== check() ------- See `"check()', *Note VcsTools/Source: VcsTools/Source, History handling methods ======================== createHistory() --------------- Will returns the *Note VcsTools/History: VcsTools/History, object for this file and create it if necessary. updateHistory() --------------- Extract the history information from the VCS base and update the VcsTools::History objbect (by calling `"update(...)"', *Note VcsTools/History: VcsTools/History,). This function must be called to re-synchronize your application if the VCS base was changed by someone else. Handling the real file ====================== createLocalAgent() ------------------ Create the file Agent class. getTimeStamp() -------------- Returns the last modification time of the file. (See stat function in *Note Perlfunc: (perl.info)perlfunc,) edit() ------ Will launch a window editor though the file agent (`"edit()"', *Note VcsTools/FileAgent: VcsTools/FileAgent,) getRevision() ------------- See `"getRevision()', *Note VcsTools/Source: VcsTools/Source, checkWritable() --------------- Will return 1 if the file is writable, 0 if not. Will return undef in case of problems. checkExist() ------------ Will return 1 if the file exists, 0 if not. Will return undef in case of problems. chmodFile(...) -------------- Will change the file mode to writable or not. Parameters are : * writable: 1 or 0 Returns 1 if chmod was done and undef in case of problems. writeFile(...) -------------- Write the passed content into the actual VCS file.. Parameters are : content: String or hash ref (See `"writeFile(...)"', *Note VcsTools/FileAgent: VcsTools/FileAgent,) that will be written. Returns 1 if the file was written and undef in case of problems. writeRevContent(...) -------------------- Write the content of a specific version of the VCS file in the passed file name. This method is handy when you want to compare several revisions of a VCS file with a tool which does not support directly your VCS system. For instance to compare 2 versions of foo.c you may call: # creates a v1.2_foo.c file $foo->writeRevContent(revision => 1.2); # creates a v1.3_foo.c file $foo->writeRevContent(revision => 1.3); Then you may call xdiff on v1.2_foo.c and v1.3_foo.c. Parameters are : * revision: writeFile will retrieve this revision of the VCS file and write it to the passed file name. * fileName: file name to write to (default to "v_", e.g. v1.13_bar.c for version 1.13 of the bar.c VCS file) Returns the name of the written file if the file was actually written and undef in case of problems. remove() -------- Unlink the VCS file. Handling the VCS part ===================== Before invoking any VCS functions, the File object will check whether the function can be performed. (For instance, it will not try to perform a check out if the local file is writable.) createVcsAgent() ---------------- Create the VCS interface class. checkArchive() -------------- Calls checkArchive of the VCS interface class. (E.g. `"checkArchive()"', *Note VcsTools/HmsAgent: VcsTools/HmsAgent,) with the working revision as the revision parameter.. changeLock(...) --------------- Delegated to the VCS interface class. E.g. `"changeLock(...)"', *Note VcsTools/HmsAgent: VcsTools/HmsAgent, checkOut(...) ------------- Delegated to the VCS interface class. E.g. `"checkOut(...)"', *Note VcsTools/HmsAgent: VcsTools/HmsAgent, getContent(...) --------------- Delegated to the VCS interface class. E.g. `"getContent(...)"', *Note VcsTools/HmsAgent: VcsTools/HmsAgent, archiveLog(...) --------------- See `"archiveLog()"', *Note VcsTools/Source: VcsTools/Source, getHistory() ------------ Delegated to the VCS interface class. E.g. `"getHistory()"', *Note VcsTools/HmsAgent: VcsTools/HmsAgent, showDiff(...) ------------- Delegated to the VCS interface class. E.g. `"showDiff(...)"', *Note VcsTools/HmsAgent: VcsTools/HmsAgent, archiveFile(...) ---------------- Will archive the current file. Parameters are: * revision: revision number for this new version of the file. Defaults to a number computed by `"guessNewRev(revision)"', *Note VcsTools/History: VcsTools/History,, * info: Hash ref holding relevant informations for this new archive. (See *Note VcsTools/LogParser: VcsTools/LogParser, for the hash content). Defaults to a hash containing 'auto archive' as log information, the current date and the name of the user performing the archive. Note that before performing the archive, the program will check the timestamp of the archive base and will upload its history informations if the archive has been changed since the last upload. This way the archive number decided by the history object will always be correct. TO DO ===== A merge() method which will find the common ancestor of the passed revisions, perform a merge using merge(1) and write the result in the local file. A patch() method which will report the modif made from one revision to an other revision on a branch. This can be handy to report a bug fix on a branch under change control. AUTHOR ====== Dominique Dumont, Dominique_Dumont@grenoble.hp.com Copyright (c) 1998-1999 Dominique Dumont. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== perl(1), Tk(3), Puppet::Any(3), VcsTools::DataSpec::HpTnd(3), VcsTools::Version(3), VcsTools::File(3)  File: pm.info, Node: VcsTools/FileAgent, Next: VcsTools/History, Prev: VcsTools/File, Up: Module List Perl class to handle a file *************************** NAME ==== VcsTools::FileAgent - Perl class to handle a file SYNOPSIS ======== my $agent = "VcsTools::FileAgent" ; my $fa = new $agent(name => 'test.txt', workDir => $some_dir); $fa->writeFile(content => "dummy content\n") ; $fa->readFile() ; $fa->stat() ; DESCRIPTION =========== This class is used as a file agent to perform some operation such as pipe, stat, read, write. This class will take care of going in and out of the directory where the file is and will perform basic error handling. This class will use *Note VcsTools/Process: VcsTools/Process, to launch child processes. Note that one FileAgent class must be created for one file. Constructor =========== new(...) -------- Creates a new class. Parameters are : * name: file name (mandatory) * workDir: local directory where the file is. * trace: If set to 1, debug information are printed. Will create a FileAgent for file 'a_name' in directory 'workDir'. Note that new will create the 'workDir' if it does not exist. Methods ======= edit() ------ Will run a non-blocking gnuclient session to edit the file. merge(...) ---------- Will connect to xemacs (with gnudoit) and will run a non-blocking ediff session. See the ediff documentation. Parameters are : * ancestor: the file name which contains the ancestor of the 2 files to merge * below: the file name which contains one of the revision to merge. * other: the file name which contains the other revision to merge. Returns 1 when the ediff is launched. Returns undef in case of problems. Note that merge will return once ediff is luanched, not when the ediff session is done. writeFile(...) -------------- Will write a string (or an array joined with "\n") into the file. parameters are : * content: string | ref_to_string_array * name: optional file name that will be written to (defaults to the name passed to the constructor). readFile() ---------- Will read the content of the file. Returns a ref to an array containing the file lines getRevision() ------------- Will read the content of the file and return the revision number. Return 0 of the $Revision: 1.6 $ keyword is present in the file but not set by the VCS system. stat() ------ Will perform a stat (see perlfunc(3)) on the file and return the stat array. exist() ------- Will return '1' or '0' if the file exists or not. ('-e' test). changeMode(...) --------------- Will perform a chmod (see perlfunc(3)) on the file. Parameters are : * mode: 0xxx mode remove() -------- Will unlink (see perlfunc(3)) the file . parameters are : * name: optional file name that will be written to (defaults to the name passed to the constructor). Error handling ============== In case of problems, all function will return undef. In this case of problem, you can call the error() method to get a string describing the problem of the last command. AUTHOR ====== Dominique Dumont, Dominique_Dumont@grenoble.hp.com Copyright (c) 1998-1999 Dominique Dumont. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== perl(1), VcsTools::Process(3)  File: pm.info, Node: VcsTools/History, Next: VcsTools/HmsAgent, Prev: VcsTools/FileAgent, Up: Module List Perl class to manage a VCS history. *********************************** NAME ==== VcsTools::History - Perl class to manage a VCS history. SYNOPSIS ======== require VcsTools::DataSpec::HpTnd ; # for instance my $ds = new VcsTools::DataSpec::HpTnd ; my $hist = new VcsTools::History ( keyRoot => 'history root', name => 'History test', dataScanner => $ds ); DESCRIPTION =========== This class represents a whole history of a VCS file. It holds all the necessary *Note VcsTools/Version: VcsTools/Version, objects that makes the complete history of the file. Generally, RCS based systems such as VCS or HMS store a few information with each revision. These information are generally 'Author', 'date', 'branches', 'log'. On top of the common informations, you can specify your own set of information (for instance, 'merged from', 'bug fixed') according to the policies defined on your work place. On top of the functionnality of the Version object (See `"DESCRIPTION"', *Note VcsTools/Version: VcsTools/Version,), you can perform various queries related to the history such as : * Sort revisions: it will return a pair of revisions sorted by age. Oldest and child. But it will return an error if these two versions are not parents of each others. * List a genealogy of versions between 2 revisions of a file. This will take into account the branches. For instance between 1.1 and 1.2.1.2, it will return 1.1 1.2 1.2.1.1 1.2.1.2), but between 1.3 and 1.2.1.2 it will return an error, since these two versions are not parents of each others. * Build a cumulated log of several revisions. I.e a log description of all changes made to several consecutive versions (which is handy to build a log of a merge). This function will return an if these two versions are not parents of each others. Furthermore, this class can be used with a GUI by using *Note Puppet/VcsTools/History: Puppet/VcsTools/History, instead. CONVENTION ========== The following words may be non ambiguous for native english speakers, but it is not so with us french people. So I prefer clarify these words: * Log: Refers to the information stored with one version. * History: Refers to a collection of all logs of all versions stored in the VCS base. Constructor =========== new(...) -------- Will create a new history object. Parameters are those of *Note Puppet/Body: Puppet/Body, plus : * revision : revision number of this version * dataScanner : *Note VcsTools/DataSpec/Rcs: VcsTools/DataSpec/Rcs, or *Note VcsTools/DataSpec/HpTnd: VcsTools/DataSpec/HpTnd, (or equivalent) object reference Methods ======= update(...) ----------- Parameters are: * history: huge string or array ref of all VCS logs, or history hash ref using the format described in data scanner This method will: * Parse the content of the history. * Create all Version objects found in the history * Update all Version objects with the informations found in each log. Note that calling this method will clobber all informations previously stored in the Version objects. hasVersion(revision) -------------------- Returns 1 if the VCS file contains this revision of the file. guessNewRev(revision) --------------------- Returns a fitting revision number to follow the passed revision. For instance : * guessNewRev(1.2) returns 1.3 if 1.3 does not exist * guessNewRev(1.2) returns 1.2.1.1 if 1.3 already exists * guessNewRev(1.2) returns 1.2.2.1 if 1.3 and branch 1.2.1 already exist sortRevisions($rev1, $rev2) --------------------------- Returns ($rev1, $rev2) if $rev1 is the ancestor of $rev2, ($rev2, $rev1) in the other case. Returns undef if the revisions are not parents. listGenealogy($rev1, $rev2) --------------------------- Returns a list of all revision between $rev1 and $rev2. Include the youngest revision in the list, but not the older. Croaks if the revision are not parents. getInfo($rev) ------------- Returns an info array containing all informations relevant to $rev. buildCumulatedInfo($rev1, $rev2) -------------------------------- Returns an info array made of a concatenation of all revision between $rev1 and $rev2. Croaks if the revisions are not parents. addNewVersion(...) ------------------ Parameters are: * revision: revision to add (e.g. '1.2.1.1') * info: hash ref containing the informations related to this revision. This method will add a new version in this history. Do not call this method unless the VCS system actually has a new version, i.e. the user just performed an archive. getVersionObj(revision) ----------------------- Returns the object ref of the Version object representing the passed revision. Will create the objects as necessary. Returns undef if the asked revision does not exist. AUTHOR ====== Dominique Dumont, Dominique_Dumont@grenoble.hp.com Copyright (c) 1998-1999 Dominique Dumont. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== perl(1), VcsTools::DataSpec::HpTnd(3), VcsTools::DataSpec::Rcs(3) VcsTools::Version(3), Puppet::VcsTools::History(3)  File: pm.info, Node: VcsTools/HmsAgent, Next: VcsTools/LogParser, Prev: VcsTools/History, Up: Module List Perl class to manage ONE HMS files.. ************************************ NAME ==== VcsTools::HmsAgent - Perl class to manage ONE HMS files.. SYNOPSIS ======== VcsTools::HmsAgent->hmsHost ('a_host') ; VcsTools::HmsAgent->hmsBase ('a_base') ; my $h = new VcsTools::HmsAgent ( name => $file, workDir => $some_dir ); $h -> getHistory() ; $h -> checkOut(revision => '1.51.1.1', lock => 1) ; $h -> getContent(revision => '1.52') ; $h -> checkArchive() ; $h -> changeLock(lock => 1,revision => '1.51.1.1' ) ; $h -> archiveLog(log => "new dummy\nhistory\n", state => 'Dummy', revision => '1.52') ; $h -> showDiff(rev1 => '1.41') ; $h -> showDiff(rev1 => '1.41', rev2 => '1.43') ; $h -> checkIn(revision => '1.52', 'log' => "dummy log\Nof a file\n") ; DESCRIPTION =========== This class is used to manage a HMS file. All functions are executed in blocking mode. If you want to use other VCS system than HMS, you should copy or inherit this file to implement your own new class. HMS === HMS is Hewlett-Packard proprietary VCS system based on RCS. This product is part of HP SoftCM. Class data ========== These items are translucent attributes (See *Note Perltootc: (perl.info)perltootc, by Tom Christiansen). Using the following method, you may set or query the value for the data class. * hmsHost: The HMS server name. * hmsBase: The HMS base name. * hmsDir: The directory relative to the HMS base where the file is archived. * trace: If set to 1, debug information are printed. (default 0) * test: If set to 1, each command will return the command to be executed instead of the command result.(default 0) These parameters may be overridden for an object by * Passing a named parameters to the constructor (eg. `hmsHost => 'tralfamadore'') * By invoking the corresponding object method (eg. `$obj->hmsHost('tralfamadore')'). Contructor ========== new(...) -------- Creates a new HMS agent object. Note that one HmsAgent must be created for each HMS file. Parameters are (not including the class data): * name: file name (mandatory) * workDir: local directory where the file is. If 'hmsHost' or 'hmsBase' parameters are not provided, HMS will rely on the system or user .fmrc file. See fci(1) for more details. Methods ======= spawn(...) ---------- Spawn a new HMS agent object inheriting the attributes of the spawner object. Parameters are : * name: file name (mandatory) * subDir: Specify the directory of the spawned object relative to the directory of the spawner object. Both hmsDir and workDir of the spawned object will be set. checkOut(...) ------------- Parameters are : * revision: file revision to check out. If not specified, the VCS system will decide itself which revision to check out. * lock: boolean. whether to lock the file or not. Checks out revision x.y and lock it if desired. Returns an array ref containing the output of the 'fci' in case of success, undef in case of problems. In case of problem, you can call the error() method to get the STDOUT of the command. getContent(...) --------------- Parameters are : * revision: file revision to check out. Get the content of file revision x.y. Returns an array ref of the file content in case of success, undef in case of problems. In case of problem, you can call the error() method to get the STDOUT of the command. checkArchive() -------------- Check the state of the archive with respect to the passed revision. Parameters are : * revision: revision number of the user's working file. May be undef. Returns an array ref made of [$rev,$locker,$time] or undef in case of problems. * $time is the time of the last modification of the archive (in epoch, decimal time) * if the revision the the user is working on is locked, $locker returns the name of the locker, 'unlocked' otherwise. * $revision is there for historical reasons. It is set to the revision number of the user's working file if this revision is locked. set to undef otherwise. changeLock(...) --------------- Parameters are : * revision: file revision to check out. * lock: whether to lock the file or not. Change the lock of the file for revision x.y. Returns an array ref containing the output of the 'futil' in case of success, undef in case of problems. In case of problem, you can call the error() method to get the STDOUT of the command. archiveLog(...) --------------- Will modify the log (not the file) of a specified revision of the file. Parameters are : * revision * log: log to store in the history of revision * state: new state to store Returns an array ref containing the output of the 'futil' in case of success, undef in case of problems. In case of problem, you can call the error() method to get the STDOUT of the command. getHistory() ------------ Gets the complete history of file. Returns an array ref containing the history in case of success, undef in case of problems. In case of problem, you can call the error() method to get the STDOUT of the command. showDiff(...) ------------- Parameters are : * rev1: first revision to compare * rev2: 2nd revision to compare. If not specified, the comparison is made between the local file and revision 'rev1'. Gets the diff between current file and revision rev1 or between rev1 and rev2 if rev2 is specified. Returns an array ref containing the diff output in case of success, undef in case of problems. In case of problem, you can call the error() method to get the STDOUT of the command. create() -------- Create the HMS file. If needed this method will also create the HMS path in the HMS base. Returns an array ref containing the output of the 'fci' commmand in case of success, undef in case of problems. In case of problem, you can call the error() method to get the STDOUT of the command. checkIn(...) ------------ Archive (check in) the current file. Parameters are : * revision * log: log to store in the history of revision Returns an array ref containing the output of the 'fci' commmand in case of success, undef in case of problems. In case of problem, you can call the error() method to get the STDOUT of the command. list() ------ Returns a hash reference containing all HMS files found in the HMS base in the directory of this file and all sub-directories (i.e list recursively all files found in and below /hmsBase/hmsDir). The hash will contains the locker and locked revision (if any) and the last modification time of the HMS archive. For instance, list will return : {'foo' => {rev => '1.0', locker => 'bob', time => '935143309'}, 'subdir/bar' => {rev => undef , locker => undef, time => '935143305'}} Returns undef in case of problem. AUTHOR ====== Dominique Dumont, Dominique_Dumont@grenoble.hp.com Copyright (c) 1998-1999 Dominique Dumont. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== perl(1), VcsTools::Process(3)  File: pm.info, Node: VcsTools/LogParser, Next: VcsTools/Process, Prev: VcsTools/HmsAgent, Up: Module List Perl class to translate RCS based log to info hash ************************************************** NAME ==== VcsTools::LogParser - Perl class to translate RCS based log to info hash SYNOPSIS ======== my $ds = new VcsTools::LogParser (description => $big_hash); my @log = ; my $info = $ds->scanHistory(\@log) ; my $piledInfo = $ds->pileLog ( 'pile_test', [ [ '3.10', $info->{'3.10'}], ['3.11', $info->{'3.11'}], ['3.12', $info->{'3.12'}], ['3.13', $info->{'3.13'}], ] ) ; print $ds->buildLogString ($piledInfo); DESCRIPTION =========== This class is used to translate the log of a VCS file into a hash containing all relevant informations and vice-versa. Currently, LogParser should work on all RCS based VCS systems. It has been tested with RCS and HP HMS. The description hash ref defines the informations that are contained in the log of each version of the VCS file. LogParser can also concatenate several logs into one according to the rules defined in the description hash. Contructor ========== new(...) -------- * description: has ref containing the description of the fields that can be found in the VCS log. * readHook: Sub ref. See scanHistory method. Methods ======= scanHistory(log) ---------------- Analyse the history of a file and returns a hash ref containing all relevant informations. The keys of the hash are made from the revision numbers found in the history log. The log can be either a string or an array ref. Once the log has been analysed and the informations have been stored in the info hash according to the description, the 'readHook' passed to the constructor will be called with the info hash ref as parameter. This gives user the possibility to add its custom treatments to get more informations from the log. getDescription() ---------------- Return the hash ref describing the VCS log. buildLogString(info_hash_ref) ----------------------------- Returns a log string from the info hash. The log string may be archived as is in the VCS base. pileLog(...) ------------ Returns an info hash made of all informations about revision passed in the array ref. Parameters are: * The first parameter is the name of the concerned Vcs file. This field is necessary to build a readable cumulated log. * The second parameter is an array ref made where each element is an array ref made of the version number and the info hash ref of this revision. (See example below) DESCRIPTION FORMAT ================== Each element of the array is a hash ref. This hash ref contains : * name : name of the field as seen by the user or by the VCS system. * var : variable name used in internal hash (default = name), and through the VcsTools objects. * type : is either line, enum or array or text (see below) * values : array ref containing the possible values of enum type (ignored for other types) * mode : specifies if the value must be hidden (h) from the user or if it can be only read or also modified by the user (h|r|w) (default 'w') * pile: specify how the information are cumulated. (optional) For array data type, it can be 'push'. In this case, the array elements are pushed, then sorted and redundant infos are discarded. For text data type, is can be 'concat'. In this case, the text strings are concatenated together and with each file name and revision number. * vcs_mode: if 'r', the info is read from the VCS system but not written to (ex: the archival date) (optional, defaults to 'w') * help : The help information can either be a string that will be displayed with a Tk::Dialog or a pointer to a Pod file that will be displayed with a Tk::pod window. In case of pod information, the help hash must be like : { 'class' => 'Your::Class', 'section' => 'DECRIPTION' # optionnal } EXAMPLE ======= Here's an example of a cumulated log : From pile_test v3.12: - coupled with tcapIncludes - does not compile in ANSI From pile_test v3.11: bugs fixed : - GREhp10971 : TC_P_ABORT address format doesn't respect addr option. AUTHOR ====== Dominique Dumont, Dominique_Dumont@grenoble.hp.com Copyright (c) 1998-1999 Dominique Dumont. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== perl(1)  File: pm.info, Node: VcsTools/Process, Next: VcsTools/RcsAgent, Prev: VcsTools/LogParser, Up: Module List Perl functions to handle child process (blocking mode) ****************************************************** NAME ==== VcsTools::Process - Perl functions to handle child process (blocking mode) SYNOPSIS ======== my $res = openPipe ( command => 'll', trace => $trace ) ; $res = pipeIn (command => 'bc', trace => $trace, input => "3+4+2\nquit\n" ); $res = mySystem ( command => 'echo >/dev/console', trace => $trace, ); DESCRIPTION =========== This package provides functions which are the standard perl functions (system, open, and open2) with some sugar coating to avoid duplicated code. Common parameters ================= The functions mySystem, openPipe and pipeIn accepts these parameters: * command: the command to run * trace: If set to 1, the command will be printed on STDERR before execution. * expect: hash ref specifying how the process exit code must be interpreted. Defaults to ( 0 => 1, 255 => 0 ). * workDir: where to run the command (defaults to the current directory). If specified all functions will perform a chdir to 'workDir' before executing the command and will chdir back before returning. Error checking ============== In case of errors all functions returns undef. In this case you can get the error cause by calling the getError function. Functions ========= mySystem(...) ------------- Will run a system() call. Returns 1 in case of succes, undef in case of problems. openPipe(...) ------------- Will open a pipe on command and read its STDOUT. Returns an array ref in case of succes, undef in case of problems. The array will contain chomped lines of the STDOUT of the command. pipeIn(...) ----------- Will open a pipe on the STDIN and STDOUT of command (see open2), send the content of the 'input' parameter to the process and read its STDOUT. Returns an array ref in case of succes, undef in case of problems. The array will contain chomped lines of the STDOUT of the command. Parameters are: * input: string to send to the command getError() ---------- Return a string containing the error message of the last command which had some problem. It works a bit like the errno variable. AUTHOR ====== Dominique Dumont, Dominique_Dumont@grenoble.hp.com Copyright (c) 1998-1999 Dominique Dumont. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== perl(1)  File: pm.info, Node: VcsTools/RcsAgent, Next: VcsTools/Source, Prev: VcsTools/Process, Up: Module List Perl class to manage ONE RCS files.. ************************************ NAME ==== VcsTools::RcsAgent - Perl class to manage ONE RCS files.. SYNOPSIS ======== my $h = new VcsTools::RcsAgent ( name => $file, workDir => $some_dir ); $h -> getHistory() ; $h -> checkOut(revision => '1.51.1.1', lock => 1) ; $h -> getContent(revision => '1.52') ; $h -> checkArchive() ; $h -> changeLock(lock => 1,revision => '1.51.1.1' ) ; $h -> archiveLog(log => "new dummy\nhistory\n", state => 'Dummy', revision => '1.52') ; $h -> showDiff(rev1 => '1.41') ; $h -> showDiff(rev1 => '1.41', rev2 => '1.43') ; $h -> checkIn(revision => '1.52', 'log' => "dummy log\Nof a file\n") ; DESCRIPTION =========== This class is used to manage a RCS file. All functions are executed in blocking mode. If you want to use other VCS system than RCS, you should copy or inherit this file to implement your own new class. Class data ========== These items are translucent attributes (See *Note Perltootc: (perl.info)perltootc, by Tom Christiansen). Using the following method, you may set or query the value for the data class. * trace: If set to 1, debug information are printed. (default 0) * test: If set to 1, each command will return the command to be executed instead of the command result.(default 0) These parameters may be overridden for an object by * Passing a named parameters to the constructor (eg. `trace => 1') * By invoking the corresponding object method (eg. `$obj->trace(1)'). Contructor ========== new(...) -------- Creates a new RCS agent class. Note that one RcsAgent must be created for each RCS file. Parameters are (not including the class data): * name: file name (mandatory) * workDir: local directory where the file is. * trace: If set to 1, debug information are printed. * test: each command will return the command to be executed instead of the command result. Methods ======= spawn(...) ---------- Spawn a new RCS agent object inheriting the attributes of the spawner object. Parameters are : * name: file name (mandatory) * subDir: Specify the directory of the spawned object relative to the directory of the spawner object. Note that the workDir of the spawned object will be set. create() -------- Create a new archive. If the RCS sub-directory is not present, it will also be created. Returns undef in case of problems. checkOut(...) ------------- Parameters are : * revision: file revision to check out. * lock: boolean. whether to lock the file or not. Checks out revision x.y and lock it if desired. Returns an array ref containing the output of the 'ci' in case of success, undef in case of problems. In case of problem, you can call the error() method to get the STDOUT of the command. getContent(...) --------------- Parameters are : * revision: file revision to check out. Get the content of file revision x.y. Returns an array ref of the file content in case of success, undef in case of problems. In case of problem, you can call the error() method to get the STDOUT of the command. checkArchive() -------------- Check the state of the archive with respect to the passed revision. Parameters are : * revision: revision number of the user's working file. May be undef. Returns an array ref made of [$rev,$locker,$time] or undef in case of problems. * $time is the time of the last modification of the archive (in epoch, decimal time) * if the revision the the user is working is locked, $locker returns the name of the locker, 'unlocked' otherwise. * $revision is there for historical reasons. It returns the revision number of the user's working file if this rev is locked. Is undef otherwise. changeLock(...) --------------- Parameters are : * revision: file revision to check out. * lock: whether to lock the file or not. Change the lock of the file for revision x.y. Returns an array ref containing the output of the 'rcs' in case of success, undef in case of problems. In case of problem, you can call the error() method to get the STDOUT of the command. archiveLog(...) --------------- Will modify the log (not the file) of a specified revision of the file. Parameters are : * revision * log: log to store in the history of revision * state: new state to store Returns an array ref containing the output of the 'futil' in case of success, undef in case of problems. In case of problem, you can call the error() method to get the STDOUT of the command. getHistory() ------------ Gets the complete history of file. Returns an array ref containing the history in case of success, undef in case of problems. In case of problem, you can call the error() method to get the STDOUT of the command. showDiff(...) ------------- Parameters are : * rev1: first revision to compare * rev2: 2nd revision to compare. If not specified, the comparison is made between the local file and revision 'rev1'. Gets the diff between current file and revision rev1 or between rev1 and rev2 if rev2 is specified. Returns an array ref containing the diff output in case of success, undef in case of problems. In case of problem, you can call the error() method to get the STDOUT of the command. create() -------- Create the RCS file. Returns an array ref containing the output of the 'ci' commmand in case of success, undef in case of problems. In case of problem, you can call the error() method to get the STDOUT of the command. checkIn(...) ------------ Archive (check in) the current file. Parameters are : * revision * log: log to store in the history of revision Returns an array ref containing the output of the 'ci' commmand in case of success, undef in case of problems. In case of problem, you can call the error() method to get the STDOUT of the command. list() ------ Returns an array reference containing all RCS files found in the RCS directory of this file For instance, list will return ['foo','bar'] if the RCS subdir contains foo,v and bar,v. Returns undef in case of problem. AUTHOR ====== Dominique Dumont, Dominique_Dumont@grenoble.hp.com Copyright (c) 1998-1999 Dominique Dumont. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== perl(1), VcsTools::Process(3)  File: pm.info, Node: VcsTools/Source, Next: VcsTools/Version, Prev: VcsTools/RcsAgent, Up: Module List Perl base class for some VcsTools components ******************************************** NAME ==== VcsTools::Source - Perl base class for some VcsTools components SYNOPSIS ======== No synopsis given. Virtual class. DESCRIPTION =========== This class is just a way not to duplicate functions. Generic methods =============== check() ------- Checks r/w permission of the local file, the revision of the local file and lock state of the file. The file must contain the `$Revision: 1.1 $' keyword. getRevision() ------------- Will return the revision of the local file. Will return undef in case of problems. Handling the VCS part ===================== archiveLog(...) --------------- Will modify the log (not the file) of a specified revision of the file in the VCS base. Parameters are : * info: info hash that contains the new informations to update the log in the VCS base * revision: revision number of the log to update. Returns an array ref containing the output of the VCS command in case of success, undef in case of problems.  File: pm.info, Node: VcsTools/Version, Next: Verilog/Language, Prev: VcsTools/Source, Up: Module List Perl class to manage VCS revision. ********************************** NAME ==== VcsTools::Version - Perl class to manage VCS revision. SYNOPSIS ======== No synopsis given. This object is better used with the History module. DESCRIPTION =========== This class represents one version of a VCS file. It holds all the information relevant to this version including the parent revision, child revision, branches revisions and do on. Its main function is to provides the functionnality to manage versions (inluding branches and merges) of a Vcs file: * Find the common ancestor of 2 revisions (but this does not yet take merges into account) * Find the oldest parent of a revision * Find all children of a revision (taking merges into account) All these information can be stored in a database. See *Note Puppet/Body: Puppet/Body, for more details. CONVENTION ========== The following words may be non ambiguous for native english speakers, but it is not so with us french people. So I prefer clarify these words: * Log: Refers to the information stored with one version. * History: Refers to a collection of all logs of all versions stored in the VCS base. Constructor =========== new(...) -------- Parameters are : * All parameter of `"Constructor"', *Note Puppet/Body: Puppet/Body, * revision : revision number of this version * manager: the ref of the history object. Methods ======= update(...) ----------- Parameters are: * info: hash ref of log informations This methods takes a hash reference containing all informations extracted from the VCS log of this version. Then all other complementary informations (such as upper revision, branches revisions, revision that were eventually merged in this one) are computed and stored in the database. getRevision() ============= Returns the revision number of this object. getUpperRev() ============= Returns the revision number of the "parent" of this object. hasParent() =========== Returns true if this version has a "parent" object. findAncestor(other_revision_number) =================================== Returns the ancestor number of this revision and the other. Returns undef in case of problems. findOldest() ============ Returns the version number of the oldest parent in the revision tree that it can find. getLog() ======== Returns the log of this version object. AUTHOR ====== Dominique Dumont, Dominique_Dumont@grenoble.hp.com Copyright (c) 1998-1999 Dominique Dumont. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== perl(1), Puppet:Body:(3), VcsTools::History(3)  File: pm.info, Node: Verilog/Language, Next: Verilog/Parse, Prev: VcsTools/Version, Up: Module List Verilog language utilities ************************** NAME ==== Verilog::Language - Verilog language utilities SYNOPSIS ======== use Verilog::Language; $result = Verilog::Language::is_keyword ($symbol_string) $result = Verilog::Language::is_compdirect ($symbol_string) $result = Verilog::Language::number_value ($number_string) $result = Verilog::Language::number_bits ($number_string) @vec = Verilog::Language::split_bus ($bus) DESCRIPTION =========== This package provides useful utilities for general use with the Verilog Language. General functions will be added as needed. Verilog::Language::is_keyword ($symbol_string) Return true if the given symbol string is a Verilog reserved keyword. EXAMPLE ======= print Verilog::Language::is_keyword ("module"); 1 print Verilog::Language::is_keyword ("signalname"); undef Verilog::Language::is_compdirect ($symbol_string) Return true if the given symbol string is a Verilog compiler directive. EXAMPLE ======= print Verilog::Language::is_compdirect ("`include"); 1 print Verilog::Language::is_compdirect ("`MYDEFINE"); undef Verilog::Language::number_value ($number_string) Return the numeric value of a Verilog value, or undef if incorrectly formed. Since it is returned as a signed integer, it may fail for over 31 bit integers. EXAMPLE ======= print Verilog::Language::number_value ("32'h13"); 19 print Verilog::Language::number_value ("32'p2"); undef Verilog::Language::number_bits ($number_string) Return the number of bits in a value string, or undef if incorrectly formed, _or_ not specified. EXAMPLE ======= print Verilog::Language::number_bits ("32'h13"); 32 Verilog::Language::split_bus ($bus) Return a list of expanded arrays. When passed a string like "foo[5:1:2,10:9]", it will return a array with ("foo[5]", "foo[3]", ...). It correctly handles connectivity expansion also, so that "x[1:0] = y[3:0]" will get intuitive results. DISTRIBUTION ============ The latest version is available from `http://www.ultranet.com/~wsnyder/verilog-perl'. AUTHORS ======= Wilson Snyder  File: pm.info, Node: Verilog/Parse, Next: Verilog/Parser, Prev: Verilog/Language, Up: Module List parse Verilog language files **************************** NAME ==== Verilog::Parse - parse Verilog language files WARNING ======= This module is no longer supported. Use Verilog::Parser instead. SYNOPSIS ======== use Verilog::Parse; $parser = new Verilog::Parse; sub function {my ($parser, $what, $info) = @_; ...} $parser->callback ("xxx", \&function) $string = $parser->unreadback (); $parser->Verilog::Parse::parse ($FileHandle) DESCRIPTION =========== This package implements parsing of the Verilog language. A file is parsed and callbacks are called for various entities in the file, as they occur. WARNING ======= This module is no longer supported. Use Verilog::Parser instead. $parser->new Create a new parser. $parser->callback ("token", \&function) Request that when the parser hits the given token, function will be called. The tokens that may be parsed are: "COMMENT" Any text in // or /**/ comments. "STRING" Any quoted string, including the quotes. "KEYWORD" A Verilog keyword. (See C) "SYMBOL" A textual non-keyword "OPERATOR" A non-alphanumeric operator. "NUMBER" A number. The callback will get three arguments. The first is the parser (self). The second is the exact type of token, one of those listed above. Third is a string with the symbol, number, etc. $parser->parse ($FileHandle) Read input from the filehandle, and perform callbacks as needed. $parser->unreadback () Return any input string from the file that has not been sent to the callback. This will include whitespace and tokens which did not have a callback. (For example comments, if there is no comment callback.) This is useful for recording the entire contents of the input, for preprocessors, pretty-printers, and such. EXAMPLE ======= Here\'s a simple example which will print every symbol in a verilog file. We also remember what line it occured on, just for the heck of it. sub symbol_cb { # Callback from parser when a symbol occurs sub function (my ($parser, $what, $info) = @_; ...) $signals_and_symbols{$info} = $.; } sub verilog_read_symbols { my $filename = shift; local %signals_and_symbols = (); # Signals already found in module my $fh = new FileHandle; my $parser = new Verilog::Parse; $parser->callback ("SYMBOL", \&symbol_cb); $fh->open("<$filename") or die "Can't read $filename."; $parser->Verilog::Parse::parse ($fh); $fh->close; foreach $sym (sort (keys %signals_and_symbols)) { print "Symbol $sym\n"; } } SEE ALSO ======== `Verilog::ParseSig', `Verilog::Language', FileHandle, BUGS ==== This is being distributed as a baseline for future contributions. Don\'t expect a lot, the parser is still nieve, and there are many awkward cases that aren\'t covered. DISTRIBUTION ============ The latest version is available from `http://www.ultranet.com/~wsnyder/verilog-perl'. AUTHORS ======= Wilson Snyder