Perforce MediaWiki extension

p4change

The p4change tag produces a P4Web link to a Perforce changelist. The usage is as follows:

<p4change>1234</p4change>
<p4change style="long">1234</p4change>

The first form produces a simple link containing only the change number:

1234

The second form produces a full line containing additional information fetched from Perforce:

Change 1234 on 2002/01/08 by david_abrahams@morepie 'Newly added files were missing '

p4changes

The p4changes tag produces a list of Perforce changelists. The usage is as follows:

<p4changes num="5" path="//public/jam/src/..."/>
<p4changes num="5" path="//public/jam/src/..." desc="short|long|full"/>
<p4changes num="5" path="//public/jam/src/..." desc="short|long|full" user="seiwald"/>

The following example uses all of the parameters (<p4changes num="3" path="//public/jam/src/..." desc="long" user="seiwald"/>):

• Change 4409 on 2004/08/19 by seiwald@golly-seiwald
  Drop 'rc3' moniker of jam-2.5. Folded rc2 and rc3 RELNOTES into
  the main part of the document. Built new tar/zip balls.
  Only 16 months later.
  
• Change 3072 on 2003/04/09 by seiwald@golly-seiwald
  Bring generated jam files up to date.
  
• Change 3071 on 2003/04/09 by seiwald@golly-seiwald
  Bring generated jam files up-to-date.
  

Note that this is equivalent to running the command: p4 changes -m3 -L -u seiwald //public/jam/src/...

p4print

The p4print tag places the contents of a depot file directly into the page. The usage is as follows:

<p4print path="//public/jam/src/execunix.c"/>

The file contents will be rendered as raw text inside a <pre> tag, with any HTML escaped.

p4variants

The p4variants tag produces a list of branches from a specified path that have changes in them which have not yet been integrated back. This is a time-consuming query, so this tag uses AJAX to load the output on demand rather than automatically including it in the page. The usage is as follows:

<p4variants path="//public/perforce/utils/reviewd/p4review.py"/>

The supplied path may be a single file or a directory (path ending in * or ...). Branches of the user-supplied path are identified by examining integration records with p4 integrated and looking for correspondences between the supplied path and the individual paired files. Unintegrated changelists are found by running p4 interchanges between identified branches and the supplied path, and the results are filtered by running p4 integrate -n to verify that at least one file in each candidate changelist has a pending integrate action.

Here is an example of the above usage (click [find variants] to run the query):

p4changes

Same as the p4changes tag, with attributes specified in the following order:

{{#p4changes:num|path|desc|user}}

p4chgcats

Changelists grouped into categories according to description keywords. Usage:

{{#p4chgcats:path|prefix|format|keyword1|category1|keyword2|category2|...}}

The "prefix" parameter is a markup string that should be prepended to each changelist result. (For example, specify a * here to create a bullet list, or a # for a numbered list.)

The "format" parameter behaves the same as in the #p4job: function.

The "keyword" parameters will be case-insensitively matched against the change descriptions to determine which changelists should go under each category.

The "category" parameters specify the header that should go above each list of changelists. Multiple keywords can map to one category, and vice versa, but each category is listed only once (in the order first given).

Example usage:

{{#p4chgcats://guest/sam_stafford/mediawiki/extensions/...|*|1sents 1paras line|icon|'''Icon changes'''|typo|'''Typo fixes'''}}

Icon changes

• 6270: Pull fixed busy icon from Matt's branch.

Typo fixes

• 6264: Fixed a typo.

p4info

Displays server info (same as "p4 info|grep Server"). Usage:

{{#p4info:}}

p4job

Displays information about a single job. To generate a P4Web link to a job:

{{#p4job:jobname}}

To extract a particular field from a job:

{{#p4job:jobname|Field|format}}

The "format" parameter is a whitespace-separated list of any of the following keywords:

• Nchars: (limits output to N characters)
• Nwords: (limits output to N space-separated words)
• Nlines: (limits output to N newline-separated lines)
• Nsents: (limits output to N punctuation-separated sentences)
• Nparas: (limits output to N blank-line-separated paragraphs)
• line: (normalizes all whitespace to spaces, eliminating linebreaks)
• text: (wraps multi-line output in a <pre> block)
• raw: (wraps multi-line output in a <pre> block and disables all wiki markup)
• template:TEMPLATE: (wraps output in user-defined template TEMPLATE)

p4jobs

Displays a table of job data.

{{#p4jobs:job-expr|fields|maxjobs|format|table-attr|tr-attr|td-attr|query1|action1|query2|action2...}}

The "job-expr" parameter is a standard Perforce job search expression.

The "fields" parameter is a whitespace-separated list of job fields. The table is sorted by the fields in the order given; to sort a particular field in reverse order, put a ! before the field name.

The "maxjobs" parameter limits the number of jobs produced (default 20, max 100).

The "format" parameter formats each field, using the same logic as used by the #p4job: function. A formatting option can be applied to only a certain column by appending #FieldName to the end of it.

The "table-attr", "tr-attr", and "td-attr" are HTML attributes that will be added to the table, each table row, and each table cell.

There can be any number of matched "query"/"action" arguments. Each "query" is either a job search expression or one of the keywords ODD, EVEN, or ALL (which match odd rows, even rows, or all rows of the table). The "action" is applied to each row of the table matching the query, and can be one of:

• attrib:tr-attr
• format:format

where tr-attr is a HTML attribute (or list of attributes) to be applied to the matching table rows, and format is a formatting string following the same logic as the basic "format" parameter (except it is only applied to matching rows). The actions will be applied in the order specified, so later actions can augment or override earlier ones. (Note: simple job queries consisting of one search term and no wildcards will be handled by in-memory searching of the already-fetched data; more complex strings will generate new queries against the Perforce server.)

Example usage:

{{#p4jobs:jam status=open{{!}}status=closed|!Status Job Description|5|80chars 10words line#Description|
cellpadding=4 cellspacing=0||valign=top|
EVEN|attrib:style="background-color:#EEEEEE"}}

p4graph

Generates GraphViz DOT markup graphing the history of a file. If the GraphViz extension is installed, the graph will be rendered on the page. Usage:

{{#p4graph:path|constraint}}

The optional "constraint" parameter specifies which elements the graph should try to keep aligned: "file" or "change" (default is neither).

p4print

Same as the p4print tag, but provides additional options for translating the output. The syntax is:

{{#p4print:path|mode}}

The "mode" can be any one of "raw", "text", or "wiki":

• raw: All HTML is escaped and the result is displayed in a <pre> block. This is exactly equivalent to using the <p4print/> tag. raw is the default mode if none is specified.

• text: The file contents are treated as if they were wiki text, but a space is placed at the beginning of each line to put the file into a <pre> block. Any wiki markup or allowed HTML in the file will be rendered as in a normal page (within a <pre> block), and URLs will be rendered as links. This option should be suitable for most plain text files. (Note that some HTML tags may break up the block, in which case raw is a better choice.)

• wiki: The file contents are treated as if they were wiki text. This is probably only useful for files that contain no formatting at all, files that are specifically wiki-formatted, or very minimal HTML pages.

p4variants

Same as the p4variants tag:

{{#p4variants:path}}

Recent Changes

• Change 8079 on 2012/03/28 by sam_stafford@sam-win-wiki
  Fix rule-based styling in #p4jobs. The logic that handled "extra"
  arguments didn't survive the restructuring I did earlier to fix
  compatibility problems, but it seems to work now.
  
• Change 8077 on 2012/03/15 by sam_stafford@sam-win-wiki
  Make maxJobs limit for #p4jobs: function 1000 instead of 100. 100
  remains the default if you provide an out-of-bounds value.
  
• Change 8072 on 2012/02/29 by sam_stafford@sam-win-wiki
  The variants AJAX now snags errors and reports them. Useful since it's the only thing that uses P4CLIENT.
  
• Change 8071 on 2012/02/29 by sam_stafford@sam-win-wiki
  Fix p4print parser function.
  
• Change 8070 on 2012/02/28 by sam_stafford@sam-win-wiki
  Rework special pages to work with new Mediawiki version. Ugh.
  

Variants

License

Copyright (C) 2008 Perforce Software

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.