perforce-cli 0.2.3

A type-safe builder library for spawning Perforce (p4) commands, with compile-time option state isolation and multi-version support.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
use std::path::{Path, PathBuf};

use crate::cmd::Add;
use crate::cmd::AdminEntry;
#[cfg(not(feature = "lt2016_1"))]
use crate::cmd::Aliases;
use crate::cmd::Annotate;
use crate::cmd::Archive;
use crate::cmd::Attribute;
#[cfg(not(feature = "lt2017_2"))]
use crate::cmd::BackGroundTask;
use crate::cmd::Branch;
use crate::cmd::Branches;
use crate::cmd::CStat;
use crate::cmd::CachePurge;
use crate::cmd::Change;
use crate::cmd::Changes;
use crate::cmd::Clean;
use crate::cmd::Client;
use crate::cmd::Clients;
#[cfg(not(feature = "lt2015_1"))]
use crate::cmd::Clone;
use crate::cmd::Configure;
use crate::cmd::Copy;
use crate::cmd::Counter;
use crate::cmd::Counters;
use crate::cmd::DBSchema;
use crate::cmd::DBStat;
use crate::cmd::DBVerify;
use crate::cmd::Delete;
use crate::cmd::Depot;
use crate::cmd::Depots;
use crate::cmd::Describe;
#[cfg(not(feature = "lt2024_2"))]
use crate::cmd::Diagnostics;
use crate::cmd::Diff;
use crate::cmd::Diff2;
use crate::cmd::Dirs;
use crate::cmd::DiskSpace;
use crate::cmd::Edit;
use crate::cmd::Export;
#[cfg(not(feature = "lt2019_1"))]
use crate::cmd::ExtensionEntry;
use crate::cmd::FileLog;
use crate::cmd::Print;
use crate::cmd::Sync;
use crate::cmd::Where;
use crate::global::GlobalOpts;

pub mod cmd;
pub mod global;
pub mod spawn;

pub mod prelude {
    pub use crate::cmd::*;
    pub use crate::global::*;
    pub use crate::spawn::*;
}

#[derive(Debug, Clone)]
pub struct P4Cli {
    bin: PathBuf,

    global_opts: GlobalOpts,
}

impl Default for P4Cli {
    fn default() -> Self {
        Self {
            bin: PathBuf::from("p4"),
            global_opts: GlobalOpts::default(),
        }
    }
}

impl P4Cli {
    /// Create a new Perforce command-line client.
    ///
    /// `bin` is the path to the Perforce command-line executable.
    pub fn new(bin: impl Into<PathBuf>, global_opts: GlobalOpts) -> Self {
        Self {
            bin: bin.into(),
            global_opts,
        }
    }

    /// Set the Perforce command path.
    pub fn bin(mut self, bin: impl Into<PathBuf>) -> Self {
        self.set_bin(bin);
        self
    }

    /// Set the global options.
    pub fn global_opts(mut self, global_opts: GlobalOpts) -> Self {
        self.set_global_opts(global_opts);
        self
    }

    /// Get the Perforce command path.
    pub fn get_bin(&self) -> &Path {
        &self.bin
    }

    /// Get the global options.
    pub fn get_global_opts(&self) -> &GlobalOpts {
        &self.global_opts
    }

    /// Set the Perforce command path.
    pub fn set_bin(&mut self, bin: impl Into<PathBuf>) {
        self.bin = bin.into();
    }

    /// Set the global options.
    pub fn set_global_opts(&mut self, global_opts: GlobalOpts) {
        self.global_opts = global_opts;
    }

    /// Open files in a client workspace for addition to the depot.
    pub fn cmd_add(&self) -> Add {
        Add::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Perform administrative operations on the server.
    pub fn cmd_admin(&self) -> AdminEntry {
        AdminEntry::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Display command aliases that are currently defined in a .p4aliases file.
    #[cfg(not(feature = "lt2016_1"))]
    pub fn cmd_aliases(&self) -> Aliases {
        Aliases::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Print file lines along with their revisions.
    pub fn cmd_annotate(&self) -> Annotate {
        Annotate::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Archive obsolete revisions to an archive depot.
    pub fn cmd_archive(&self) -> Archive {
        Archive::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Set per-revision attributes on file revisions.
    pub fn cmd_attribute(&self) -> Attribute {
        Attribute::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Run a background command or trigger on the server.
    ///
    /// The returned builder starts with no task target; call
    /// [`BackGroundTask::execute`] (`-e`) or [`BackGroundTask::trigger`]
    /// (`-t`) to select the required target before spawning.
    #[cfg(not(feature = "lt2017_2"))]
    pub fn cmd_bgtask(&self) -> BackGroundTask {
        BackGroundTask::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Create or edit a branch mapping and its view.
    pub fn cmd_branch(&self) -> Branch {
        Branch::new(self.bin.clone(), self.global_opts.clone())
    }

    /// List existing branch mappings.
    pub fn cmd_branches(&self) -> Branches {
        Branches::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Reclaim disk space on a replicated server.
    ///
    /// The returned builder starts with no purge goal and has no effect;
    /// call [`CachePurge::purge_all`] (`-a`), [`CachePurge::free_space`]
    /// (`-f`), [`CachePurge::revision_count`] (`-m`), or
    /// [`CachePurge::size`] (`-s`) to select the required goal before
    /// spawning.
    pub fn cmd_cachepurge(&self) -> CachePurge {
        CachePurge::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Restore client workspace files to match the state of corresponding
    /// depot files.
    ///
    /// Without file arguments, the files in your local working directory are
    /// used; pass file arguments to
    /// [`ParameterizedSpawn::spawn_with`](crate::spawn::ParameterizedSpawn::spawn_with)
    /// to limit the scope.
    pub fn cmd_clean(&self) -> Clean {
        Clean::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Create or edit a client workspace specification and its view.
    ///
    /// The returned builder starts in the [`GeneralMode`](crate::cmd::client::GeneralMode)
    /// state (`p4 client [-f] [-t template] [-T type] [name]`); call
    /// transition methods such as [`Client::delete`](crate::cmd::client::Client::delete)
    /// or [`Client::stdout`](crate::cmd::client::Client::stdout) to select
    /// another syntax form.
    pub fn cmd_client(&self) -> Client {
        Client::new(self.bin.clone(), self.global_opts.clone())
    }

    /// List all client workspaces currently known to the system.
    ///
    /// The returned builder starts with no option selected and spawns the
    /// bare `p4 clients` report as is; set any regular option or filter to
    /// enter the [`RegularMode`](crate::cmd::clients::RegularMode) state, or
    /// call [`Clients::unloaded`](crate::cmd::clients::Clients::unloaded)
    /// (`-U`) to list only unloaded client workspaces.
    pub fn cmd_clients(&self) -> Clients {
        Clients::new(self.bin.clone(), self.global_opts.clone())
    }

    /// List all client workspaces currently known to the system.
    ///
    /// This is an alias for [`Self::cmd_clients`], corresponding to the `p4
    /// workspaces` command.
    pub fn cmd_workspaces(&self) -> Clients {
        Clients::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Clone a new local server from a remote server.
    ///
    /// The returned builder cannot be assembled until a remote port is
    /// selected with [`Clone::port`](crate::cmd::clone::Clone::port) (`-p`)
    /// and exactly one clone target is selected with
    /// [`Clone::remote`](crate::cmd::clone::Clone::remote) (`-r`)
    /// or [`Clone::file`](crate::cmd::clone::Clone::file) (`-f`).
    /// Unlike most commands, `p4 clone` does not accept the global options.
    #[cfg(not(feature = "lt2015_1"))]
    pub fn cmd_clone(&self) -> Clone {
        Clone::new(self.bin.clone())
    }

    /// Set, view, and manage server configuration variables.
    ///
    /// The returned command starts with no operation selected; call
    /// [`Configure::set`], [`Configure::unset`], or
    /// [`Configure::show`] to select the operation.
    #[cfg_attr(not(feature = "lt2019_2"), doc = "")]
    #[cfg_attr(
        not(feature = "lt2019_2"),
        doc = "The [`Configure::history`](Configure::history) operation selects the `p4 configure history` report."
    )]
    #[cfg_attr(not(feature = "lt2023_2"), doc = "")]
    #[cfg_attr(
        not(feature = "lt2023_2"),
        doc = "The [`Configure::patch`](Configure::patch) operation retroactively sets a history comment, and [`Configure::help`](Configure::help) prints the configurables reference."
    )]
    pub fn cmd_configure(&self) -> Configure {
        Configure::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Copy files and/or the stream spec from one location in the depot to
    /// another.
    pub fn cmd_copy(&self) -> Copy {
        Copy::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Access, set, increment, or delete a persistent variable.
    ///
    #[cfg_attr(
        feature = "lt2016_1",
        doc = "The returned builder starts in the bare query form `p4 counter countername`; use [`Counter::set`], [`Counter::delete`], [`Counter::increment`], or [`Counter::multi`] to select another form."
    )]
    #[cfg_attr(
        not(feature = "lt2016_1"),
        doc = "The returned builder starts in the bare query form `p4 counter countername`; use [`Counter::set`], [`Counter::show_previous`], [`Counter::delete`], [`Counter::increment`], [`Counter::multi`], or [`Counter::cas`] to select another form."
    )]
    pub fn cmd_counter(&self) -> Counter {
        Counter::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Display the list of long-term variables used by P4 Server and
    /// associated scripts.
    pub fn cmd_counters(&self) -> Counters {
        Counters::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Dump change or sync status for the current client workspace.
    pub fn cmd_cstat(&self) -> CStat {
        CStat::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Report information about metadata in the database.
    pub fn cmd_dbschema(&self) -> DBSchema {
        DBSchema::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Display size or simple statistics for one or more database tables.
    pub fn cmd_dbstat(&self) -> DBStat {
        DBStat::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Perform low-level verification of the database tables.
    pub fn cmd_dbverify(&self) -> DBVerify {
        DBVerify::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Create or edit a client workspace specification and its view.
    ///
    /// This is an alias for [`Self::cmd_client`], corresponding to the `p4
    /// workspace` command.
    pub fn cmd_workspace(&self) -> Client {
        Client::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Create or edit a changelist specification.
    pub fn cmd_change(&self) -> Change {
        Change::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Create or edit a changelist specification.
    ///
    /// This is an alias for [`Self::cmd_change`], corresponding to the `p4
    /// changelist` command.
    pub fn cmd_changelist(&self) -> Change {
        Change::new(self.bin.clone(), self.global_opts.clone())
    }

    /// List submitted and pending changelists.
    pub fn cmd_changes(&self) -> Changes {
        Changes::new(self.bin.clone(), self.global_opts.clone())
    }

    /// List submitted and pending changelists.
    ///
    /// This is an alias for [`Self::cmd_changes`], corresponding to the `p4
    /// changelists` command.
    pub fn cmd_changelists(&self) -> Changes {
        Changes::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Open files in a client workspace for deletion from the depot.
    pub fn cmd_delete(&self) -> Delete {
        Delete::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Create, edit, or delete a depot specification.
    pub fn cmd_depot(&self) -> Depot {
        Depot::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Display a list of depots known to the P4 Server.
    pub fn cmd_depots(&self) -> Depots {
        Depots::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Display the details of one or more changelists.
    pub fn cmd_describe(&self) -> Describe {
        Describe::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Generate diagnostic data about the P4 Server.
    #[cfg(not(feature = "lt2024_2"))]
    pub fn cmd_diagnostics(&self) -> Diagnostics {
        Diagnostics::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Diff workspace content against depot content, or diff stream specs.
    pub fn cmd_diff(&self) -> Diff {
        Diff::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Compare the content at two depot paths, or compare two stream specs.
    pub fn cmd_diff2(&self) -> Diff2 {
        Diff2::new(self.bin.clone(), self.global_opts.clone())
    }

    /// List the subdirectories of the specified depot directories.
    pub fn cmd_dirs(&self) -> Dirs {
        Dirs::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Display disk space information on the server.
    pub fn cmd_diskspace(&self) -> DiskSpace {
        DiskSpace::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Display disk space information on the server.
    ///
    /// This is an alias for [`Self::cmd_diskspace`], corresponding to the `p4
    /// df` command.
    pub fn cmd_df(&self) -> DiskSpace {
        DiskSpace::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Open files in a client workspace for edit.
    pub fn cmd_edit(&self) -> Edit {
        Edit::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Extract journal or checkpoint records.
    ///
    /// The returned builder starts with neither `-c` nor `-j` selected; call
    /// `checkpoint` (`-c`) or `journal` (`-j`) to select one, since only
    /// those states can be spawned.
    pub fn cmd_export(&self) -> Export {
        Export::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Manage the installation, versioning, and configuration of extensions.
    ///
    /// The returned entry selects the operation to perform, such as
    /// `install` (`--install`), `configure` (`--configure`), or `list`
    /// (`--list`).
    #[cfg(not(feature = "lt2019_1"))]
    pub fn cmd_extension(&self) -> ExtensionEntry {
        ExtensionEntry::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Print detailed information about the revisions of files.
    pub fn cmd_filelog(&self) -> FileLog {
        FileLog::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Print the contents of depot file revisions.
    pub fn cmd_print(&self) -> Print {
        Print::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Update the client workspace to reflect the contents of the depot.
    pub fn cmd_sync(&self) -> Sync {
        Sync::new(self.bin.clone(), self.global_opts.clone())
    }

    /// Show where a particular file is located, as determined by the client view.
    pub fn cmd_where(&self) -> Where {
        Where::new(self.bin.clone(), self.global_opts.clone())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn default_uses_p4_from_path() {
        let p4 = P4Cli::default();

        assert_eq!(p4.get_bin(), Path::new("p4"));
    }

    #[test]
    fn accepts_custom_bin_path() {
        let p4 = P4Cli::new("C:\\tools\\p4.exe", GlobalOpts::default());

        assert_eq!(p4.get_bin(), Path::new("C:\\tools\\p4.exe"));
    }
}