With np4, you can execute Perforce commands according to 4 modes in your choice:
| Async command | Sync command | |
|---|---|---|
| Marshal syntax | cmd() |
cmdSync() |
| Raw syntax | rawCmd() |
rawCmdSync() |
Asynchronous command returns a promise wich will be resolved with the Perforce result while sync command is blocked until Perforce has returned a result.
Marshal syntax consists to use global -G option allowing to provide input and receive result as a JS object.
Raw syntax uses basic text format.
Note that only login command accepts input parameter (password) as a string in both Marshal and Raw modes.
If P4VC is installed, you will be able to launch any p4vc command with visual() method
wich returns a promise wich is resolved when p4vc has closed.
All these method belong to class P4 provided by the module np4: See detail here
Get the module from NPM
$ npm install np4 --saveUse build action (npm or yarn) to build lib/np4.js.
To test it, you need to have installed "Helix Core Apps" and "Helix Versioning Engine" (p4 & p4d).
import {P4} from "np4"
const p4 = new P4(option)or
const P4 = require("np4").P4
const p4 = new P4(option)where option is a set of P4 variables to apply as context when executing p4 commands:
- all P4 environnment variables like P4PORT, P4CHARSET, P4USER, P4CLIENT, ...
- np4 specific option like:
- P4API_TIMEOUT: timeout in ms for p4 commands process
Example:
const p4 = new P4({
P4PORT: "myP4Server:1666",
P4CHARSET: "utf8",
P4API_TIMEOUT: 5000
})
⚠️ WARNING:
P4CLIENT, P4PORt & P4USER will never be overloaded with variable set in a P4CONFIG file
| Name | Description |
|---|---|
| Error | Error instance |
| TimeoutError | Error instance |
setOpts(opt) and addOpts(opt) allow you to set or merge environment variables.
import {P4} from "np4"
const p4 = new P4({P4PORT: "p4server:1666"})
p4.setOpts({env:{P4PORT: "newServer:1666"}})
p4.addOpts({env:{P4USER: "bob", P4CLIENT="bob_client"}}Where:
optis the option parameter injected inspawn()function
⚠️ WARNING:
In the most current case, use only the fieldenvinopt.
Use other fields thanenvis not tested !
cmd(p4Cmd, [input]) and cmdSync(p4Cmd, [input]) allow to execute any p4 command using Marshal syntax (global p4 option -G).
import {P4} from "np4"
const p4 = new P4({P4PORT: "p4server:1666"})
// Asynchro mode
p4.cmd(p4Cmd, input)
.then(out => {
// ...
}
.catch(err) {
throw ("p4 not found");
};
// Asynchro with async-await
try {
let out = await p4.cmd(p4Cmd, input);
} catch (err) {
throw ("p4 not found");
}
// Synchro mode
try {
let out = p4.cmdSync(p4Cmd, input);
} catch (err) {
throw ("p4 not found");
}Where:
p4Cmdis the Perforce command (string) with options separated with space.inputis a optional string or object for input value (like password for login command or client object for client command).
p4.cmd() return a promise which is resolved with the marshalled result of the command as an object (out).
p4.cmdSync() return the marshal result of the command as an object (out).
out has the following structure:
prompt: string printed by perforce before the result (else empty string)stat: if exists, list of all result with code=statinfo: if exists, list of all result with code=infoerror: if exists, list of all result with code=error
rawCmd(p4Cmd, [input]) and rawCmdSync(p4Cmd, [input]) allow to execute any p4 command using text syntax.
Arguments and result are similar to the last method except that the marshalled syntax is replaced with a raw text syntax.
Both raw methods return result as the following structure:
text: success result string or empty stringerror: error result string or empty string
If p4 client can not be executed (perforce not installed, bad path variable, ...), cmd is rejected and cmdSync
is throwed with a P4Error Error instance.
When timeout is reached, cmd is rejected and cmdSync is throwed
with a P4TimeoutError Error instance
with message like 'Timeout <timeout>ms reached'
import {P4} from "np4";
let p4 = new P4({P4PORT: "p4server:1666", P4API_TIMEOUT: 5000});
function P4Error(msg) {
this.name = "p4 error";
this.message = msg;
}
async function p4(cmd, input) {
let out
try {
out = await p4.cmd(cmd, input)
} catch (err) {
if (err instanceof P4.TimeoutError) {
// Time out error
throw new Error("p4 timeout " + err.timeout + " ms");
}
if (err instanceof P4.Error) {
// Time out error
throw new Error("p4 execution error. Check perforce installation");
}
// Critical error : not expected
throw new Error("I don't know what appends");
}
if (out.error !== undefined) {
// p4 command error
throw new P4Error(out.error);
}
return out;
}import {P4} from "np4";
let p4 = new P4({P4PORT: "p4server:1666"});
p4.cmd("depots").then(function(out){console.log(out);});Result is like:
{
"prompt": "",
"stat": [
{
"code": "stat",
"name": "CM",
"time": "1314373478",
"type": "local",
"map": "/perforce/Data/CM/...",
"desc": "Created by xxxx. ..."
},
{
"code": "stat",
"name": "depot",
"time": "1314374519",
"type": "local",
"map": "/perforce/Data/depot/...",
"desc": "Created by xxxx. ..."
}
]
} ...
p4.cmd("mistake")
...Result is:
{
"prompt": "",
"error": [
{
"code": "error",
"data": "Unknown command. Try \"p4 help\" for info.\n",
"severity": 3,
"generic": 1
}
]
} ...
p4.cmd("login", "myGoodPasswd")
...Result is like:
{
"prompt": "Enter password: ↵",
"info": [
{
"code": "info",
"data": "Success: Password verified.",
"level": 5
},
{
"code": "info",
"data": "User toto logged in.",
"level": 0
}
]
} ...
p4.cmd("login -s")
...Result is like:
{
"prompt": "",
"stat": [
{
"code": "stat",
"TicketExpiration": "85062",
"user": "toto"
}
]
} async function clearViewPathes() {
let out = await p4.cmd("client -o")
let client = out.stat[0]
for (let i = 0;; i++) {
if (client["View" + i] === undefined) break
delete client["View" + i]
}
await p4.cmd("client -i", client)
await p4.cmd("sync -f")
}let p4Promise = p4.cmd("clients");
...
let result = null;
if (DoNotNeedResult) {
p4Promise.cancel();
} else {
result = await p4Promise;
}