Perforce MediaWiki extension.md #1

{{ Project | Perforce MW extension |

`  curator  = Sam Stafford                        |`\
`  path     = //guest/sam_stafford/mediawiki/     |`\
`  download = //guest/sam_stafford/mediawiki/extensions/Perforce/ |`\
`  language = PHP                                 |`\
`  license  = GPL }}`

Tags implemented by this extension
----------------------------------

The Perforce MediaWiki extension implements the following tags:

### 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:

:   <p4change>1234</p4change>

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

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

### 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 (**&lt;p4changes
num="3" path="//public/jam/src/..." desc="long" user="seiwald"/&gt;**):
<p4changes num="3" path="//public/jam/src/..." desc="long" user="seiwald"/>

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 &lt;pre&gt; 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):

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

Parser functions implented by this extension
--------------------------------------------

### p4changes

Same as the [p4changes tag](#p4changes "wikilink"), 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'''}}`

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

### p4diff2

Displays differences between two files or paths. Usage:

`{{#p4diff2:path1|path2|flags}}`

The **path** arguments are required, should be in depot syntax, and may
include revision specifiers. The **flags** argument may contain the
**-d** or **-q** flags as implemented by the standard **p4 diff2**
command; the output of the parser function will be the output of the
**p4 diff2** command enclosed in a wiki-style preformatted text block.

The **flags** argument may also include the **-A** flag (implemented by
this extension), which will reduce the output to a sum of added +
changed lines.

### 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 &lt;pre&gt; block)
-   **raw**: (wraps multi-line output in a &lt;pre&gt; 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|`\
`EVEN|attrib:style="background-color:#EEEEEE"|`\
`status=open|format:template:Bold#Description}}`

{{\#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"|
status=open|format:template:Bold\#Description}}

### p4graph

Generates [GraphViz](http://www.graphviz.org/) DOT markup graphing the
history of a file. If the [GraphViz
extension](http://www.mediawiki.org/wiki/Extension:GraphViz) 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](#p4print "wikilink"), 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
    &lt;pre&gt; block. This is exactly equivalent to using the
    &lt;p4print/&gt; 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 &lt;pre&gt; block. Any wiki markup or allowed HTML in the
    file will be rendered as in a normal page (within a &lt;pre&gt;
    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 "wikilink"):

`{{#p4variants:path}}`

The Special:Perforce page
-------------------------

The <Special:Perforce> page can be used to put some of the parser
function queries in a dedicated dynamically generated page. This is
primarily useful in cases where the query results are arbitrarily large
and you don't want to embed them directly into the page, but you want to
provide easy access to them.

The link syntax is:

`[[Special:Perforce/query/arg1@@arg2@@...]]`

with *query* being a Perforce parser function name minus the leading
"\#p4". For example:
<Special:Perforce/changes/50@@//public/jam/src/...@@long>

This syntax doesn't work too well for some of the functions with tricky
argument lists; the main one it's useful for is
[\#p4graph](#p4graph "wikilink").

The default <Special:Perforce> page contains some generic information
about your Perforce server and a small collection of Perforce-related
links.

About This Project
------------------

{{ RecentChanges | //guest/sam\_stafford/mediawiki/extensions/Perforce/
}}

### Variants

{{\#p4variants://guest/sam\_stafford/mediawiki/extensions/Perforce/...}}

{{ License | GPL | 2008 | Perforce Software }}

[Category:MediaWiki-Perforce
integrations](Category:MediaWiki-Perforce_integrations "wikilink")