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

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

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:
 <nowiki><p4changes num="5" path="//public/jam/src/..."/></nowiki>
 <nowiki><p4changes num="5" path="//public/jam/src/..." desc="short|long|full"/></nowiki>
 <nowiki><p4changes num="5" path="//public/jam/src/..." desc="short|long|full" user="seiwald"/></nowiki>

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

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

=== p4print ===

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

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

The file contents will be rendered as raw text inside a <nowiki><pre></nowiki> 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:

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

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|p4changes tag]], with attributes specified in the following order:

 <nowiki>{{#p4changes:num|path|desc|user}}</nowiki>

=== p4chgcats ===

Changelists grouped into categories according to description keywords.  Usage:

 <nowiki>{{#p4chgcats:path|prefix|format|keyword1|category1|keyword2|category2|...}}</nowiki>

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:

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

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

=== p4diff2 ===

Displays differences between two files or paths.  Usage:

 <nowiki>{{#p4diff2:path1|path2|flags}}</nowiki>

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:

 <nowiki>{{#p4info:}}</nowiki>

=== p4job ===

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

 <nowiki>{{#p4job:jobname}}</nowiki>

To extract a particular field from a job:

 <nowiki>{{#p4job:jobname|Field|format}}</nowiki>

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 <nowiki><pre></nowiki> block)
* '''raw''': (wraps multi-line output in a <nowiki><pre></nowiki> block and disables all wiki markup)
* '''template:TEMPLATE''': (wraps output in user-defined template TEMPLATE)

=== p4jobs ===

Displays a table of job data.

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

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:

 <nowiki>{{#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}}</nowiki>

{{#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 [http://www.graphviz.org/ GraphViz] DOT markup graphing the history of a file.  If the [http://www.mediawiki.org/wiki/Extension:GraphViz GraphViz extension] is installed, the graph will be rendered on the page.  Usage:

 <nowiki>{{#p4graph:path|constraint}}</nowiki>

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|p4print tag]], but provides additional options for translating the output.  The syntax is:

 <nowiki>{{#p4print:path|mode}}</nowiki>

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

* '''raw''': All HTML is escaped and the result is displayed in a <nowiki><pre></nowiki> block.  This is exactly equivalent to using the <nowiki><p4print/></nowiki> 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 <nowiki><pre></nowiki> block.  Any wiki markup or allowed HTML in the file will be rendered as in a normal page (within a <nowiki><pre></nowiki> 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|p4variants tag]]:

 <nowiki>{{#p4variants:path}}</nowiki>

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

 <nowiki>[[Special:Perforce/query/arg1@@arg2@@...]]</nowiki>

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]].

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]]