Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 Extensions Documentation | 2025.1

# Class P4.P4

An interface to the P4 Server client API.

See the information about examples at https://swarm.workshop.perforce.com/files/guest/perforce_software/extensions/main/README.md
and the examples at a specific release, such as https://swarm.workshop.perforce.com/files/guest/perforce_software/extensions/2019.1

## Class methods

### P4.P4:new -> P4.P4

Constructs a new P4.P4 object.

    p4 = P4.P4:new()

## Instance Methods

### p4.api_level= number -> number

Sets the API compatibility level desired. Using this method allows you to lock your script to the output format of an older P4 Server release and facilitate seamless upgrades. This method, if called, should be called prior to calling p4:connect()

    p4 = P4.P4:new()
    p4.api_level = 86 # Lock to 2019.1 format
    p4:connect()

To learn more, see Protocol levels: server/client in P4 Server Administration Documentation.

### p4.api_level -> number

Returns the current P4 API for C/C++ compatibility level. Each iteration of the P4 Server is given a level number. As part of the initial communication, the client protocol level is passed between client application and the P4 Server. This value, defined in the P4 API for C/C++, determines the communication protocol level that the P4 Server client will understand. All subsequent responses from the P4 Server can be tailored to meet the requirements of that client protocol level.

To learn more, see Protocol levels: server/client in P4 Server Administration Documentation.

### p4.autoconnect()

(Optional) Connects without requiring a password, ticket, or ticket file entry when you run p4:connect() -> boolean. The connection is for the user that is defined in the `ExtP4USER` field of the global configuration. The user can perform operations as allowed by the protection table.

An entry in the tickets file is not required. If an entry exists in the tickets file, that ticket is used and the ticket generated by the autoconnect is ignored. The autoconnect method does not update the tickets file.

The autoconnect method can only be run on the server.

Copy

    local p4 = P4.P4:new()

    p4:autoconnect() -- use config's ExtP4USER
    p4:connect()

    -- optional: ignore any existing P4TICKETS file entry
    p4.ticket_file = "File-that-does-not-exist"

    local result = p4:run("job", "-o", jobNumber)

### p4.charset= string -> string

Sets the character set to use when connecting to a Unicode-enabled server. Do not use when working with non-Unicode-enabled servers.

    p4 = P4.P4:new()
    p4.charset = "utf-8"
    p4:connect()

### p4.charset -> string

Get the name of the character set in use when working with Unicode-enabled servers.

### p4.client= string

Set the name of the client workspace you wish to use. This method, if called, should be called prior to calling p4:connect()

    p4 = P4.P4:new()
    p4.client = "www"
    p4:connect()

### p4.client -> string

Get the name of the P4 Server client currently in use.

    p4 = P4.P4:new()
    print( p4.client )

### p4:connect() -> boolean

Connect to the P4 Server. You must connect before you can execute commands.

    p4 = P4.P4:new()
    p4:connect()

### p4:is_connected() -> boolean

Test whether or not the session is connected.

    p4 = P4.P4:new()
    p4:is_connected()

### p4.cwd -> string

Get the current working directory for this server extension.

    p4 = P4.P4:new()
    print( p4.cwd )

### p4:disconnect() -> boolean

Disconnect from the P4 Server.

    p4 = P4.P4:new()
    p4:connect()
    p4:disconnect()

### p4.env(string) -> string

Get the value of a P4 Server environment variable, taking into account `P4CONFIG` files and (on Windows and macOS) the registry or user preferences.

    p4 = P4.P4:new()
    print p4.env( "P4PORT" )

### p4.errors -> table

Returns the table of errors which occurred during execution of the previous command.

### p4.exception_level = number

Enables or disables the throwing of exceptions. The following two levels are supported:

- `0` disables all exception raising and makes the interface completely procedural.

- `1` causes exceptions to be raised for both errors and warnings. This is the default.

### p4.exception_level -> number

Returns the current exception level.

If 0, exceptions are not used. When set to 1, exceptions are enabled.

### p4.format_spec( "<spectype>", table ) -> string

Converts the fields in a table containing the elements of a P4 Server form (spec) into the string representation familiar to users.

The first argument is the type of spec to format: for example, `client`, `branch`, `label`, and so on. The second argument is the table to convert to a string.

### p4.graph= boolean

Enable or disable support for graph depots. You can enable or disable support for graph depots both before and after connecting to the server.

    p4 = P4.P4:new()
    p4.graph = false

### p4.graph -> boolean

Returns whether or not support for P4 Server graph depots is enabled.

    p4 = P4.P4:new()
    print( p4.graph )
    p4.graph = false
    print( p4.graph )

### p4.host= string

Set the name of the current host. If not called, defaults to the value of `P4HOST` taken from any `P4CONFIG` file present, or from the environment as per the usual P4 Server convention. This method, if called, should be called prior to calling p4:connect()

    p4 = P4.P4:new()
    p4.host = "workstation123.example.com"
    p4:connect()

### p4.host -> string

Get the current hostname.

    p4 = P4.P4:new()
    print( p4.host )

### p4.input= ( string|table ) -> boolean

(For forms or specs) - Store input for the next command.

Use this method to submit a client spec, or create a job. The structure of the input can be a string representing the plain text version of a form you would edit in the P4 Visual Client (P4V) (P4V) or a Lua data structure.

Call this method prior to running a command requiring input from the user. When the command requests input, the specified data will be supplied to the command.

You can pass a string. For commands that take multiple inputs from the user, you can pass a table of strings. If you pass a table, the table will be shifted each time P4 Server asks the user for input.

Do not use this method for cases where you have a list of arguments. In this regard, let us compare the Extensions API to the command line client. The command line client has the -x option, which allows you to feed additional arguments to commands from a file or standard input.

For example,

    p4 -x - sync < file-list.txt

This is useful if the operating system has a limit on the length of a shell command. However, if you use the Extensions API, there is no such limit. For example,

    p4.run('sync', file1, file2, ...)

works for any number of arguments. In effect, the equivalent of command arguments is explicit in the p4:run() call.

The p4.input method is similar to how the command-line client supports the use of the -i option for standard input with a p4 shell command, such as the p4 client -i command.

#### Form processing

An example of how a changelist can be created and submitted:

Copy

    local c = p4:run( "change", "-o" )[ 1 ]
    c[ "Description" ] = "example"
    p4:run( "add", "bar" ) -- Now add 'bar' so it's open and can be part of the commit.
    c["Files"] = {}
    c["Files"][ #c[ "Files" ] + 1 ]="//depot/bar"
    p4.input = c
    p4:run( "submit", "-i" )

### p4.messages -> table

Returns a table of P4.Message objects.

### p4.p4config_file -> string

Get the path to the current `P4CONFIG` file.

    p4 = P4.P4:new()
    print( p4.p4config_file )

### p4.parse_spec( "<spectype>", string ) -> table

Parses a P4 Server form (spec) in text form into a table using the spec definition obtained from the server.

The first argument is the type of spec to parse: `client`, `branch`, `label`, and so on. The second argument is the string buffer to parse.

### p4.password= string

Set your P4 Server password or the ticket value to be used for this connection. If no password or ticket is given, it uses the value of `P4PASSWD` from any `P4CONFIG` file in effect, or from the environment according to the normal P4 Server conventions.

    p4 = P4.P4:new()
    p4.password = "mypass"
    p4:connect()

### p4.password -> string

Get the current password or ticket. This might be the password in plain text, or if you’ve used `P4#run_login()`, it’ll be the value of the ticket you’ve been allocated by the server.

    p4 = P4.P4:new()
    print( p4.password )

### p4.port= string

Set the host and port of the P4 Server you want to connect to. If not used, the value defaults to the value of `P4PORT` in any `P4CONFIG` file in effect. If there is no such value, it defaults to the value of `P4PORT` taken from the environment.

    p4 = P4.P4:new()
    p4.port = "localhost:1666"
    p4:connect()
    ...
    p4.disconnect()

### p4.port -> string

Get the value of the P4PORT of the current P4 Server.

    p4 = P4.P4:new()
    print( p4.port )

### p4.prog= string

Set the name of the script, as reported to P4 Server system administrators.

    p4 = P4.P4:new()
    p4.prog = "sync-script"
    p4:connect()
    ...
    p4.disconnect()

### p4.prog -> string

Get the name of the program as reported to the P4 Server.

    p4 = P4.P4:new()
    p4.prog = "sync-script"
    print( p4.prog )

### p4:reset()

Reset messages, warnings, and errors from a previous run() call to its default value.

### p4:run( command, [arguments…]​ ) -> table

Runs the specified P4 Server method call with the arguments supplied. The arguments should be passed as quoted and comma-separated strings, with no leading space. For example:

    p4:run("print","-o","test-print","-q","//depot/Jam/MAIN/src/expand.c")

The method returns a table of results whether the command succeeds or fails. The array table, however, can be empty. Whether the elements of the table are strings or tables depends on (a) server support for tagged output for the command, and (b) whether tagged output was disabled by calling `p4.tagged = false`.

In the event of errors or warnings, and depending on the exception level in force at the time, the method will throw an exception. If the current exception level is below the threshold for the error or warning, the method returns the output as normal, and the caller must explicitly review `p4.errors` and `p4.warnings`.

### p4.server_level -> number

Returns the current P4 Server level. Each iteration of the P4 Server is given a level number. As part of the initial communication this value is passed between the client application and the P4 Server. This value is used to determine the communication that the P4 Server will understand. All subsequent requests can therefore be tailored to meet the requirements of this Server level.

For more information about the P4 Server version levels, see the Perforce Knowledge Base article, P4 Server Version Levels.

### p4.server_unicode -> boolean

Detects whether or not the server is in unicode mode.

### p4.streams= boolean

Enable or disable support for streams. You can enable or disable support for streams both before and after connecting to the server.

    p4 = P4.P4:new()
    p4.streams = false

### p4.streams -> boolean

Detects whether or not support for P4 Server Streams is enabled.

    p4 = P4.P4:new()
    print ( p4.streams )
    p4.streams = false
    print ( p4.streams )

### p4.tagged= boolean

Sets tagged output. By default, tagged output is on.

    p4 = P4.P4:new()
    p4.tagged = false

### p4.tagged -> boolean

Detects whether or not you are in tagged mode.

    p4 = P4.P4:new()
    print ( p4.tagged )
    p4.tagged = false
    print ( p4.tagged )

### p4.ticket_file = string

Sets the location of the `P4TICKETS` file.

    p4 = P4.P4:new()
    p4.ticket_file = "/home/bruno/tickets"

### p4.ticket_file -> string

Get the path to the current `P4TICKETS` file.

    p4 = P4.P4:new()
    print( p4.ticket_file )

### p4.track= -> boolean

Instruct the server to return messages containing performance tracking information. By default, server tracking is disabled.

    p4 = P4.P4:new()
    p4.track = true

### p4.track -> boolean

Detects whether or not performance tracking is enabled.

    p4 = P4.P4:new()
    p4.track = true
    print ( p4.track )
    p4.track = false
    print ( p4.track )

### p4.trust_file=string

Specifies the path to the SSL/TLS trust file. This overrides the P4TRUST environment variable or default location.

### p4.trust_file -> string

Get the path of the trust file.

### p4.user= string

Set the P4 Server username. If not called, defaults to the value of `P4USER` taken from any `P4CONFIG` file present, or from the environment as per the usual P4 Server convention. If used, should be called before connecting to the P4 Server.

    p4 = P4.P4:new()
    p4.user = "bruno"
    p4:connect()
    ...
    p4:disconnect()

### p4.user -> string

Returns the current P4 Server username.

    p4 = P4.P4:new()
    print( p4.user )

### p4.version= string

Set the version of your script, as reported to the P4 Server.

### p4.version -> string

Get the version of your script, as reported to the P4 Server.

### p4.warnings -> table

Returns a table of warnings that arose during execution of the last command.

Your search for returned results