.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 .\" .\" Standard preamble: .\" ======================================================================== .de Sh \" Subsection heading .br .if t .Sp .ne 5 .PP \fB\\$1\fR .PP .. .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. | will give a .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' .\" expand to `' in nroff, nothing in troff, for use with C<>. .tr \(*W-|\(bv\*(Tr .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .\" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .hy 0 .if n .na .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "DiagList 3" .TH DiagList 3 "2003-04-25" "perl v5.8.0" "User Contributed Perl Documentation" .SH "NAME" DiagList \- perl module for parsing diag lists .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use DiagList; .Ve .PP .Vb 2 \& my $dlist = DiagList->new('./master_diaglist'); \& my $group = $dlist->find_group('cmp_regr'); .Ve .PP .Vb 1 \& foreach my $buildtag ($group->build_tags) { .Ve .PP .Vb 1 \& my $buildargs = $dlist->build_args($buildtag); .Ve .PP .Vb 4 \& foreach my $diagname ($group->list_diags($buildtag)) { \& my $diag = $group->find_diag($buildtag, $diagname); \& my $runargs = $diag->get_cmdline(); \& } .Ve .PP .Vb 1 \& } .Ve .SH "ABSTRACT" .IX Header "ABSTRACT" .Vb 2 \& This is a perl module for parsing diag lists. It uses \& XML-like syntax to define regression arguments. .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module exists to parse diaglists and return results in a usable format. The Synopsis section above describes common usage. This is an object module with no exported functions. The top-level object is of type DiagList. Sub-objects are returned of type DiagList::Group and DiagList::Diag. The public interface of each is described below. .Sh "DiagList Object" .IX Subsection "DiagList Object" This is the only type of object the user will create explicitly. .IP "new($file, [$fh]) " 4 .IX Item "new($file, [$fh]) " Parse the given diaglist file and return a new DiagList object. Throws an exception if it cannot parse the file. If an optional second argument is provided, it is treated as a file handle to read from. It can be either an IO::File object or a bare file handle. In this case the first argument, \f(CW$file\fR, is used purely for reporting errors. .IP "\fIbuild_list()\fR" 4 .IX Item "build_list()" Returns a list of the build tags that were seen in the file. .IP "build_args($build_tag)" 4 .IX Item "build_args($build_tag)" Returns the build arguments for the specified build tag. Returns undef if a build tag called \f(CW$build_tag\fR was not seen in the file. The build arguments are the ones specified in the group tag defintion. The only processing done is that name=<...> is stripped out completely and sys=<...> is replaced by \-sys=<...>. .IP "\fIbuild_hash()\fR" 4 .IX Item "build_hash()" Returns a reference to a hash where the keys are build tags and the values are the build args. Note that this is a reference into the internal state of the object, so modifying this hash will modify the DiagList object. .IP "\fIgroup_list()\fR" 4 .IX Item "group_list()" Returns a list of group names that were seen in the file. .IP "find_group($groupname)" 4 .IX Item "find_group($groupname)" Returns a DiagList::Group object for the specified \f(CW$groupname\fR. Returns undef if no such \f(CW$groupname\fR was seen in the file. .IP "\fIgroup_hash()\fR" 4 .IX Item "group_hash()" Returns a reference to a hash where keys are group names and values are DiagList::Group objects. Note that this is a reference into the internal state of the object, so modifying the hash will modify the DiagList object. .Sh "DiagList::Group Object" .IX Subsection "DiagList::Group Object" These objects are created by the DiagList object and can be returned to the user via the DiagList methods find_group and group_hash (both described above). The DiagList::Group objects support the following methods. .IP "name([$name])" 4 .IX Item "name([$name])" Accessor function for the group name. If an argument \f(CW$name\fR is provided, the name of the group is set to \f(CW$name\fR. The name of the group is returned, whether or not it has changed. Changing the name with this method is highly discouraged for user code, but it is perfectly acceptable to call \fIname()\fR with no arugments to get the name. .IP "\fIbuild_tags()\fR" 4 .IX Item "build_tags()" Returns a list of build_tags that are applicable to this group. .IP "list_diags($buildtag)" 4 .IX Item "list_diags($buildtag)" Returns a list of diag names in this group that correspond to the given \f(CW$buildtag\fR. .ie n .IP "find_diag($buildtag, $diagname)" 4 .el .IP "find_diag($buildtag, \f(CW$diagname\fR)" 4 .IX Item "find_diag($buildtag, $diagname)" Returns a DiagList::Diag object that corresponds the the given \&\f(CW$diagname\fR and the provided \f(CW$buildtag\fR. Returns undef if no such \&\f(CW$buildtag\fR or no such \f(CW$diagname\fR was found. .IP "diag_hash($buildtag)" 4 .IX Item "diag_hash($buildtag)" Returns a reference to a hash where the keys are diag names and the values are DiagList::Diag objects. Note tha this is a reference into the internal state of the object, so modifying the hash will modify the object. .Sh "DiagList::Diag Object" .IX Subsection "DiagList::Diag Object" DiagList::Diag objects represent the state associated with a diag. They are returned by the DiagList::Group methods \fIfind_diag()\fR and \&\fIdiag_hash()\fR. DiagList::Diag objects support the following methods. .IP "\fIget_alias()\fR" 4 .IX Item "get_alias()" Returns the diag alias, as provided in the diaglist file. .IP "\fIget_nametag()\fR" 4 .IX Item "get_nametag()" Returns the diag nametag, as provided in the diaglist file. .IP "\fIget_name()\fR" 4 .IX Item "get_name()" Returns the diag name which is the diag alias with : appended. .IP "\fIget_full_name()\fR" 4 .IX Item "get_full_name()" Returns the full diag name with alias, nametag, and group, separated by ':'. .IP "\fIget_file()\fR" 4 .IX Item "get_file()" Returns the first file mentioned in the diag line. .IP "\fIget_owner()\fR" 4 .IX Item "get_owner()" Get debug owner form diag list. .IP "\fIget_cmdline()\fR" 4 .IX Item "get_cmdline()" Returns the command-line for the diag. This includes arguments specified in the DiagList::Group object that contains this object, followed by arguments specified on the diag command line. If the containing group happens to be a buildtag (i.e., has a sys=), the sys= is stripped out of the diag command\-line. .IP "\fIget_cmd_argv()\fR" 4 .IX Item "get_cmd_argv()" This is the same as get_cmdline, except that it processes the command-line with a shell and returns a list that can be treated as an argv list. Using this instead of get_cmdline allows diaglist entries to be written the same way they would be on the command\-line. .Sh "Syntax of the Diaglist file" .IX Subsection "Syntax of the Diaglist file" The syntax of the Diaglist file is somewhat strange. It makes the most sense to describe how it evolved than to try to explain the entire syntax all at once. .PP \fIDiag Lines\fR .IX Subsection "Diag Lines" .PP A diag line is a line in the diaglist that specifies a diag. Its syntax is: .PP .Vb 1 \& .Ve .PP Where is a name for the diag, and are arguments to \fBsims\fR used to run the diag. For instance: .PP .Vb 1 \& mydiag mydiag.s -max_cycle=300000 .Ve .PP creates a diag alias \*(L"mydiag\*(R", which \fBsims\fR will invoke as \*(L"mydiag.s \&\-max_cycle=300000\*(R". One argument is special, however. If an argument is "debugowner=", that argument is removed from the command-line before it is passed to \fBsims\fR. The debugowner is available to clients of the DiagList module via the \fIget_owner()\fR function, but it is not part of the command line because there is nothing \fBsims\fR to do with it at runtime. It is useful, however, for informing the \fBdiagstatus\fR database of who owns which diags. .PP \fIGroups\fR .IX Subsection "Groups" .PP The main organizational structure in the diaglist is a group. A group defines a list of diags for a regression and arguments to use for all diags in that regression. The syntax for a group is an XML-like tag. The definition can contain arguments. .PP For example: .PP .Vb 1 \& .Ve .PP .Vb 2 \& abc abc.s -abc \& def def.s -def .Ve .PP .Vb 1 \& .Ve .PP This defines regression group named \*(L"foo\*(R". The arguments for the group are prepended to each diag command line. \fBsims\fR uses Getopt::Long to parse its arguments, so if conflicting options are repeated on its command\-line, the later option takes precedence. This means that diag-line options override group options if they are in conflict. If group foo were run in \fBsims\fR, it would run a diag with alias \*(L"abc\*(R" and arguments \*(L"\-foo1 \-foo2 abc.s \-abc\*(R" and an alias \*(L"def\*(R" with arguments \*(L"\-foo1 \-foo2 def.s \-def\*(R". .PP Groups can be opened multiple times, and they may have different arguments each time. Arguments are only used in the diags contained in that particular tag. For example: .PP .Vb 1 \& .Ve .PP .Vb 2 \& abc abc.s -abc \& def def.s -def .Ve .PP .Vb 1 \& .Ve .PP .Vb 1 \& .Ve .PP .Vb 1 \& ghi ghi.s -ghi .Ve .PP .Vb 1 \& .Ve .PP This would run \*(L"abc\*(R" and \*(L"def\*(R" exactly the same as before. The diag \&\*(L"ghi\*(R" would be run with \*(L"\-foo3 ghi.s \-ghi\*(R" and would not include \&\*(L"\-foo1 or \-foo2\*(R". .PP Group definitions may nest, but this does \fBnot\fR imply any relationship between the groups. .PP .Vb 2 \& \& .Ve .PP .Vb 1 \& abc abc.s -abc .Ve .PP .Vb 2 \& \& .Ve .PP This defines two different regressions, \*(L"foo\*(R" and \*(L"bar\*(R". In regression \*(L"foo\*(R", \*(L"abc\*(R" will have arguments \*(L"\-foo1 abc.s \-abc\*(R". In regression \*(L"bar\*(R", it will have arguments \*(L"\-bar1 abc.s \-abc\*(R". There is no notion of group \*(L"foo\*(R" containing group \*(L"bar\*(R" or anything like that. They just happen to have some diag lines in common. .PP Note that this means that a diag alias by itself does not define a unique test (diag plus arguments). The alias/group combination is necessary, but not sufficient, to make a diag unique. More on that later. .PP \fINesting tags\fR .IX Subsection "Nesting tags" .PP One special tag, specifies arguments to all enclosed diags, regardless of their group. .PP .Vb 3 \& \& \& .Ve .PP .Vb 1 \& abc abc.s -abc .Ve .PP .Vb 3 \& \& \& .Ve .PP This means that in group \*(L"foo\*(R", the diag \*(L"abc\*(R" will run as \*(L"\-runrun \&\-foo1 abc.s \-abc\*(R" and in group \*(L"bar\*(R", it will be \*(L"\-runrun \-bar1 abc.s \&\-abc\*(R". .PP You can nest tags. Inner tags will append to the argument list so inner will override outer tags if any arguments are in conflict. Please note that a tag does \fBnot\fR define a regression, so there is no group called \&\*(L"runargs\*(R". .PP Another special tag that applies to all enclosed diags, regardless of their group, is . Just as described for the diag line, does not affect the command line at all, but it does provide information to the \fBdiagstatus\fR database about who owns which diags. .PP .Vb 1 \& .Ve .PP .Vb 1 \& ... .Ve .PP .Vb 1 \& .Ve .PP This is the same as having \*(L"debugowner=someuser\*(R" on every diag line in its scope. Note that if a diag line contains a \*(L"debugowner=...\*(R" and it is inside a tag, the diag line will take precedence. .PP \fISpecial Groups\fR .IX Subsection "Special Groups" .PP There are two types of special groups, buildtags and nametags. They are syntacticaly just like any other groups, and they define regressions just like any other groups. They have special meanings and restrictions, however. .PP Build Tags .IX Subsection "Build Tags" .PP A buildtag is any group that has "sys=" in its argument list. (Note that all \fBsims\fR options begin with '\-', so any argument of the form "=" is an argument to the diaglist parser). .PP A buildtag defines the model that should be built for the regression and the \fBsims\fR options of how to build the model. .PP .Vb 1 \& .Ve .PP .Vb 1 \& ... .Ve .PP .Vb 1 \& .Ve .PP This creates a buildtag called \*(L"build1\*(R" that specifies that all diags inside it should be run with the \fBsims\fR \*(L"cmp\*(R" model, which can be built with \*(L"\-arg1 \-arg2\*(R". .PP Unlike other groups, buildtags do \fBnot\fR nest. Each diag line must appear in \fBexactly one\fR build tag. All diaglines in all groups inside the scope of the buildtag will be run on the specified model. .PP .Vb 7 \& \& \& \& mydiag mydiag.s -diag1 \& \& \& .Ve .PP When you run regression \*(L"foo\*(R", it will build a cmp model with args \&\*(L"\-arg1 \-arg2\*(R". It will then run \*(L"mydiag\*(R" with arguments \*(L"\-foo1 mydiag.s \-diag1\*(R". Similarly, if you ran regression \*(L"bar\*(R", it would build the same cmp model and run \*(L"mydiag\*(R" with \*(L"\-bar1 mydiag.s \&\-diag1\*(R". Note that \*(L"\-arg1\*(R" and \*(L"\-arg2\*(R" are used at build time for groups \*(L"foo\*(R" and \*(L"bar\*(R", but they do not appear on the diag command-line during the run. .PP A build tag also defines a regression, so you could run a regression \&\*(L"build1\*(R" with the above diaglist. It would build with \*(L"\-arg1 \-arg2\*(R" and would run \*(L"mydiag\*(R" with \*(L"\-arg1 \-arg2 mydiag.s \-diag1\*(R". There is no way for the diaglist parser to tell build-time arguments from run-time arguments when a buildtag is used as a regression group. Fortunately, \fBsims\fR will ignore run-time options at build time and vice\-versa, so using buildtags as groups is perfectly legal. .PP Name Tags .IX Subsection "Name Tags" .PP An ambiguity is possible with multiple groups that contain diags with the same alias. For example: .PP .Vb 1 \& .Ve .PP .Vb 5 \& \& \& mydiag mydiag.s \& \& .Ve .PP .Vb 5 \& \& \& mydiag mydiag.s \& \& .Ve .PP .Vb 1 \& .Ve .PP Note that we use tags instead of putting them in the \&\*(L"foo\*(R" and \*(L"bar\*(R" regressions directly, since we want the \*(L"both\*(R" group to run \*(L"mydiag\*(R" once with \*(L"\-foo1\*(R" and again with \*(L"\-bar1\*(R". The problem with the above diaglist is that both runs of \*(L"mydiag\*(R" have the same alias/group combination when run in group \*(L"both\*(R". Some other identifier is needed to give each diag a unique name. .PP Nametags are used for this purpose. A nametag is a group that has "name=" in its argument list. The name is appended to the alias do define a name that is unique within a group. The alias/nametag/group combination is enough to make a diag unique overall. As with buildtags, nametags do not nest, and each diag must appear in \fBexactly one\fR nametag. We can rewrite the above diaglist as: .PP .Vb 1 \& .Ve .PP .Vb 5 \& \& \& mydiag mydiag.s \& \& .Ve .PP .Vb 5 \& \& \& mydiag mydiag.s \& \& .Ve .PP .Vb 1 \& .Ve .PP Group \*(L"foo_group\*(R" contains the diag \*(L"mydiag:foo\*(R" with args \*(L"\-foo1 mydiag.s\*(R". Group \*(L"bar_group\*(R" contains the diag \*(L"mydiag:bar\*(R" with args \&\*(L"\-bar1 mydiag.s\*(R". Group \*(L"both\*(R" contains two diags: \*(L"mydiag:foo\*(R" with \&\*(L"\-foo1 mydiag.s\*(R" and \*(L"mydiag:bar\*(R" with args \*(L"\-bar1 mydiag.s\*(R". .PP When \fBsims\fR creates a directory to run a directory, it uses :: to get a unique directory name. In contexts where only a single group is relevant, then : is sufficent to name a diag. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIsims\fR\|(1).