Class P4.P4

An interface to the Helix Core 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 Helix Core 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 Helix Core Server Administrator Guide.

p4.api_level -> number

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

To learn more, see Protocol levels: server/client in Helix Core Server Administrator Guide.

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.

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 Helix Core Server client currently in use.

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

p4:connect() -> boolean

Connect to the Helix Core 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 Helix Core Server.

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

p4.env(string) -> string

Get the value of a Helix Core 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 Helix Core 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 Helix Core 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 Helix Core 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 Helix Core Visual Client (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 Helix Core Server asks the user for input.

Note

Use this method for forms, and not 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 somewhat analogous to how the command-line client supports the use of the -i option for standard input with a p4 shell command, such as p4 client -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 Helix Core 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 Helix Core 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 Helix Core 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 Helix Core 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 Helix Core Server.

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

p4.prog= string

Set the name of the script, as reported to Helix Core 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 Helix Core 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 Helix Core 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 Helix Core Server level. Each iteration of the Helix Core Server is given a level number. As part of the initial communication this value is passed between the client application and the Helix Core Server. This value is used to determine the communication that the Helix Core Server will understand. All subsequent requests can therefore be tailored to meet the requirements of this Server level.

For more information about the Helix Core Server version levels, see the Perforce Knowledge Base article, Helix Core 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 Helix Core 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 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 Helix Core 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 Helix Core Server convention. If used, should be called before connecting to the Helix Core Server.

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

p4.user -> string

Returns the current Helix Core Server username.

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

p4.version= string

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

p4.version -> string

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

p4.warnings -> table

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