Skip to main content

perforce_cli/
lib.rs

1use std::path::{Path, PathBuf};
2
3use crate::cmd::Add;
4use crate::cmd::AdminEntry;
5#[cfg(not(feature = "lt2016_1"))]
6use crate::cmd::Aliases;
7use crate::cmd::Annotate;
8use crate::cmd::Archive;
9use crate::cmd::Attribute;
10#[cfg(not(feature = "lt2017_2"))]
11use crate::cmd::BackGroundTask;
12use crate::cmd::Branch;
13use crate::cmd::Branches;
14use crate::cmd::CStat;
15use crate::cmd::CachePurge;
16use crate::cmd::Change;
17use crate::cmd::Changes;
18use crate::cmd::Clean;
19use crate::cmd::Client;
20use crate::cmd::Clients;
21#[cfg(not(feature = "lt2015_1"))]
22use crate::cmd::Clone;
23use crate::cmd::Configure;
24use crate::cmd::Copy;
25use crate::cmd::Counter;
26use crate::cmd::Counters;
27use crate::cmd::DBSchema;
28use crate::cmd::DBStat;
29use crate::cmd::DBVerify;
30use crate::cmd::Delete;
31use crate::cmd::Depot;
32use crate::cmd::Depots;
33use crate::cmd::Describe;
34#[cfg(not(feature = "lt2024_2"))]
35use crate::cmd::Diagnostics;
36use crate::cmd::Diff;
37use crate::cmd::Diff2;
38use crate::cmd::Dirs;
39use crate::cmd::DiskSpace;
40use crate::cmd::Edit;
41use crate::cmd::Export;
42#[cfg(not(feature = "lt2019_1"))]
43use crate::cmd::ExtensionEntry;
44use crate::cmd::FileLog;
45use crate::cmd::Print;
46use crate::cmd::Sync;
47use crate::cmd::Where;
48use crate::global::GlobalOpts;
49
50pub mod cmd;
51pub mod global;
52pub mod spawn;
53
54pub mod prelude {
55    pub use crate::cmd::*;
56    pub use crate::global::*;
57    pub use crate::spawn::*;
58}
59
60#[derive(Debug, Clone)]
61pub struct P4Cli {
62    bin: PathBuf,
63
64    global_opts: GlobalOpts,
65}
66
67impl Default for P4Cli {
68    fn default() -> Self {
69        Self {
70            bin: PathBuf::from("p4"),
71            global_opts: GlobalOpts::default(),
72        }
73    }
74}
75
76impl P4Cli {
77    /// Create a new Perforce command-line client.
78    ///
79    /// `bin` is the path to the Perforce command-line executable.
80    pub fn new(bin: impl Into<PathBuf>, global_opts: GlobalOpts) -> Self {
81        Self {
82            bin: bin.into(),
83            global_opts,
84        }
85    }
86
87    /// Set the Perforce command path.
88    pub fn bin(mut self, bin: impl Into<PathBuf>) -> Self {
89        self.set_bin(bin);
90        self
91    }
92
93    /// Set the global options.
94    pub fn global_opts(mut self, global_opts: GlobalOpts) -> Self {
95        self.set_global_opts(global_opts);
96        self
97    }
98
99    /// Get the Perforce command path.
100    pub fn get_bin(&self) -> &Path {
101        &self.bin
102    }
103
104    /// Get the global options.
105    pub fn get_global_opts(&self) -> &GlobalOpts {
106        &self.global_opts
107    }
108
109    /// Set the Perforce command path.
110    pub fn set_bin(&mut self, bin: impl Into<PathBuf>) {
111        self.bin = bin.into();
112    }
113
114    /// Set the global options.
115    pub fn set_global_opts(&mut self, global_opts: GlobalOpts) {
116        self.global_opts = global_opts;
117    }
118
119    /// Open files in a client workspace for addition to the depot.
120    pub fn cmd_add(&self) -> Add {
121        Add::new(self.bin.clone(), self.global_opts.clone())
122    }
123
124    /// Perform administrative operations on the server.
125    pub fn cmd_admin(&self) -> AdminEntry {
126        AdminEntry::new(self.bin.clone(), self.global_opts.clone())
127    }
128
129    /// Display command aliases that are currently defined in a .p4aliases file.
130    #[cfg(not(feature = "lt2016_1"))]
131    pub fn cmd_aliases(&self) -> Aliases {
132        Aliases::new(self.bin.clone(), self.global_opts.clone())
133    }
134
135    /// Print file lines along with their revisions.
136    pub fn cmd_annotate(&self) -> Annotate {
137        Annotate::new(self.bin.clone(), self.global_opts.clone())
138    }
139
140    /// Archive obsolete revisions to an archive depot.
141    pub fn cmd_archive(&self) -> Archive {
142        Archive::new(self.bin.clone(), self.global_opts.clone())
143    }
144
145    /// Set per-revision attributes on file revisions.
146    pub fn cmd_attribute(&self) -> Attribute {
147        Attribute::new(self.bin.clone(), self.global_opts.clone())
148    }
149
150    /// Run a background command or trigger on the server.
151    ///
152    /// The returned builder starts with no task target; call
153    /// [`BackGroundTask::execute`] (`-e`) or [`BackGroundTask::trigger`]
154    /// (`-t`) to select the required target before spawning.
155    #[cfg(not(feature = "lt2017_2"))]
156    pub fn cmd_bgtask(&self) -> BackGroundTask {
157        BackGroundTask::new(self.bin.clone(), self.global_opts.clone())
158    }
159
160    /// Create or edit a branch mapping and its view.
161    pub fn cmd_branch(&self) -> Branch {
162        Branch::new(self.bin.clone(), self.global_opts.clone())
163    }
164
165    /// List existing branch mappings.
166    pub fn cmd_branches(&self) -> Branches {
167        Branches::new(self.bin.clone(), self.global_opts.clone())
168    }
169
170    /// Reclaim disk space on a replicated server.
171    ///
172    /// The returned builder starts with no purge goal and has no effect;
173    /// call [`CachePurge::purge_all`] (`-a`), [`CachePurge::free_space`]
174    /// (`-f`), [`CachePurge::revision_count`] (`-m`), or
175    /// [`CachePurge::size`] (`-s`) to select the required goal before
176    /// spawning.
177    pub fn cmd_cachepurge(&self) -> CachePurge {
178        CachePurge::new(self.bin.clone(), self.global_opts.clone())
179    }
180
181    /// Restore client workspace files to match the state of corresponding
182    /// depot files.
183    ///
184    /// Without file arguments, the files in your local working directory are
185    /// used; pass file arguments to
186    /// [`ParameterizedSpawn::spawn_with`](crate::spawn::ParameterizedSpawn::spawn_with)
187    /// to limit the scope.
188    pub fn cmd_clean(&self) -> Clean {
189        Clean::new(self.bin.clone(), self.global_opts.clone())
190    }
191
192    /// Create or edit a client workspace specification and its view.
193    ///
194    /// The returned builder starts in the [`GeneralMode`](crate::cmd::client::GeneralMode)
195    /// state (`p4 client [-f] [-t template] [-T type] [name]`); call
196    /// transition methods such as [`Client::delete`](crate::cmd::client::Client::delete)
197    /// or [`Client::stdout`](crate::cmd::client::Client::stdout) to select
198    /// another syntax form.
199    pub fn cmd_client(&self) -> Client {
200        Client::new(self.bin.clone(), self.global_opts.clone())
201    }
202
203    /// List all client workspaces currently known to the system.
204    ///
205    /// The returned builder starts with no option selected and spawns the
206    /// bare `p4 clients` report as is; set any regular option or filter to
207    /// enter the [`RegularMode`](crate::cmd::clients::RegularMode) state, or
208    /// call [`Clients::unloaded`](crate::cmd::clients::Clients::unloaded)
209    /// (`-U`) to list only unloaded client workspaces.
210    pub fn cmd_clients(&self) -> Clients {
211        Clients::new(self.bin.clone(), self.global_opts.clone())
212    }
213
214    /// List all client workspaces currently known to the system.
215    ///
216    /// This is an alias for [`Self::cmd_clients`], corresponding to the `p4
217    /// workspaces` command.
218    pub fn cmd_workspaces(&self) -> Clients {
219        Clients::new(self.bin.clone(), self.global_opts.clone())
220    }
221
222    /// Clone a new local server from a remote server.
223    ///
224    /// The returned builder cannot be assembled until a remote port is
225    /// selected with [`Clone::port`](crate::cmd::clone::Clone::port) (`-p`)
226    /// and exactly one clone target is selected with
227    /// [`Clone::remote`](crate::cmd::clone::Clone::remote) (`-r`)
228    /// or [`Clone::file`](crate::cmd::clone::Clone::file) (`-f`).
229    /// Unlike most commands, `p4 clone` does not accept the global options.
230    #[cfg(not(feature = "lt2015_1"))]
231    pub fn cmd_clone(&self) -> Clone {
232        Clone::new(self.bin.clone())
233    }
234
235    /// Set, view, and manage server configuration variables.
236    ///
237    /// The returned command starts with no operation selected; call
238    /// [`Configure::set`], [`Configure::unset`], or
239    /// [`Configure::show`] to select the operation.
240    #[cfg_attr(not(feature = "lt2019_2"), doc = "")]
241    #[cfg_attr(
242        not(feature = "lt2019_2"),
243        doc = "The [`Configure::history`](Configure::history) operation selects the `p4 configure history` report."
244    )]
245    #[cfg_attr(not(feature = "lt2023_2"), doc = "")]
246    #[cfg_attr(
247        not(feature = "lt2023_2"),
248        doc = "The [`Configure::patch`](Configure::patch) operation retroactively sets a history comment, and [`Configure::help`](Configure::help) prints the configurables reference."
249    )]
250    pub fn cmd_configure(&self) -> Configure {
251        Configure::new(self.bin.clone(), self.global_opts.clone())
252    }
253
254    /// Copy files and/or the stream spec from one location in the depot to
255    /// another.
256    pub fn cmd_copy(&self) -> Copy {
257        Copy::new(self.bin.clone(), self.global_opts.clone())
258    }
259
260    /// Access, set, increment, or delete a persistent variable.
261    ///
262    #[cfg_attr(
263        feature = "lt2016_1",
264        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."
265    )]
266    #[cfg_attr(
267        not(feature = "lt2016_1"),
268        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."
269    )]
270    pub fn cmd_counter(&self) -> Counter {
271        Counter::new(self.bin.clone(), self.global_opts.clone())
272    }
273
274    /// Display the list of long-term variables used by P4 Server and
275    /// associated scripts.
276    pub fn cmd_counters(&self) -> Counters {
277        Counters::new(self.bin.clone(), self.global_opts.clone())
278    }
279
280    /// Dump change or sync status for the current client workspace.
281    pub fn cmd_cstat(&self) -> CStat {
282        CStat::new(self.bin.clone(), self.global_opts.clone())
283    }
284
285    /// Report information about metadata in the database.
286    pub fn cmd_dbschema(&self) -> DBSchema {
287        DBSchema::new(self.bin.clone(), self.global_opts.clone())
288    }
289
290    /// Display size or simple statistics for one or more database tables.
291    pub fn cmd_dbstat(&self) -> DBStat {
292        DBStat::new(self.bin.clone(), self.global_opts.clone())
293    }
294
295    /// Perform low-level verification of the database tables.
296    pub fn cmd_dbverify(&self) -> DBVerify {
297        DBVerify::new(self.bin.clone(), self.global_opts.clone())
298    }
299
300    /// Create or edit a client workspace specification and its view.
301    ///
302    /// This is an alias for [`Self::cmd_client`], corresponding to the `p4
303    /// workspace` command.
304    pub fn cmd_workspace(&self) -> Client {
305        Client::new(self.bin.clone(), self.global_opts.clone())
306    }
307
308    /// Create or edit a changelist specification.
309    pub fn cmd_change(&self) -> Change {
310        Change::new(self.bin.clone(), self.global_opts.clone())
311    }
312
313    /// Create or edit a changelist specification.
314    ///
315    /// This is an alias for [`Self::cmd_change`], corresponding to the `p4
316    /// changelist` command.
317    pub fn cmd_changelist(&self) -> Change {
318        Change::new(self.bin.clone(), self.global_opts.clone())
319    }
320
321    /// List submitted and pending changelists.
322    pub fn cmd_changes(&self) -> Changes {
323        Changes::new(self.bin.clone(), self.global_opts.clone())
324    }
325
326    /// List submitted and pending changelists.
327    ///
328    /// This is an alias for [`Self::cmd_changes`], corresponding to the `p4
329    /// changelists` command.
330    pub fn cmd_changelists(&self) -> Changes {
331        Changes::new(self.bin.clone(), self.global_opts.clone())
332    }
333
334    /// Open files in a client workspace for deletion from the depot.
335    pub fn cmd_delete(&self) -> Delete {
336        Delete::new(self.bin.clone(), self.global_opts.clone())
337    }
338
339    /// Create, edit, or delete a depot specification.
340    pub fn cmd_depot(&self) -> Depot {
341        Depot::new(self.bin.clone(), self.global_opts.clone())
342    }
343
344    /// Display a list of depots known to the P4 Server.
345    pub fn cmd_depots(&self) -> Depots {
346        Depots::new(self.bin.clone(), self.global_opts.clone())
347    }
348
349    /// Display the details of one or more changelists.
350    pub fn cmd_describe(&self) -> Describe {
351        Describe::new(self.bin.clone(), self.global_opts.clone())
352    }
353
354    /// Generate diagnostic data about the P4 Server.
355    #[cfg(not(feature = "lt2024_2"))]
356    pub fn cmd_diagnostics(&self) -> Diagnostics {
357        Diagnostics::new(self.bin.clone(), self.global_opts.clone())
358    }
359
360    /// Diff workspace content against depot content, or diff stream specs.
361    pub fn cmd_diff(&self) -> Diff {
362        Diff::new(self.bin.clone(), self.global_opts.clone())
363    }
364
365    /// Compare the content at two depot paths, or compare two stream specs.
366    pub fn cmd_diff2(&self) -> Diff2 {
367        Diff2::new(self.bin.clone(), self.global_opts.clone())
368    }
369
370    /// List the subdirectories of the specified depot directories.
371    pub fn cmd_dirs(&self) -> Dirs {
372        Dirs::new(self.bin.clone(), self.global_opts.clone())
373    }
374
375    /// Display disk space information on the server.
376    pub fn cmd_diskspace(&self) -> DiskSpace {
377        DiskSpace::new(self.bin.clone(), self.global_opts.clone())
378    }
379
380    /// Display disk space information on the server.
381    ///
382    /// This is an alias for [`Self::cmd_diskspace`], corresponding to the `p4
383    /// df` command.
384    pub fn cmd_df(&self) -> DiskSpace {
385        DiskSpace::new(self.bin.clone(), self.global_opts.clone())
386    }
387
388    /// Open files in a client workspace for edit.
389    pub fn cmd_edit(&self) -> Edit {
390        Edit::new(self.bin.clone(), self.global_opts.clone())
391    }
392
393    /// Extract journal or checkpoint records.
394    ///
395    /// The returned builder starts with neither `-c` nor `-j` selected; call
396    /// `checkpoint` (`-c`) or `journal` (`-j`) to select one, since only
397    /// those states can be spawned.
398    pub fn cmd_export(&self) -> Export {
399        Export::new(self.bin.clone(), self.global_opts.clone())
400    }
401
402    /// Manage the installation, versioning, and configuration of extensions.
403    ///
404    /// The returned entry selects the operation to perform, such as
405    /// `install` (`--install`), `configure` (`--configure`), or `list`
406    /// (`--list`).
407    #[cfg(not(feature = "lt2019_1"))]
408    pub fn cmd_extension(&self) -> ExtensionEntry {
409        ExtensionEntry::new(self.bin.clone(), self.global_opts.clone())
410    }
411
412    /// Print detailed information about the revisions of files.
413    pub fn cmd_filelog(&self) -> FileLog {
414        FileLog::new(self.bin.clone(), self.global_opts.clone())
415    }
416
417    /// Print the contents of depot file revisions.
418    pub fn cmd_print(&self) -> Print {
419        Print::new(self.bin.clone(), self.global_opts.clone())
420    }
421
422    /// Update the client workspace to reflect the contents of the depot.
423    pub fn cmd_sync(&self) -> Sync {
424        Sync::new(self.bin.clone(), self.global_opts.clone())
425    }
426
427    /// Show where a particular file is located, as determined by the client view.
428    pub fn cmd_where(&self) -> Where {
429        Where::new(self.bin.clone(), self.global_opts.clone())
430    }
431}
432
433#[cfg(test)]
434mod tests {
435    use super::*;
436
437    #[test]
438    fn default_uses_p4_from_path() {
439        let p4 = P4Cli::default();
440
441        assert_eq!(p4.get_bin(), Path::new("p4"));
442    }
443
444    #[test]
445    fn accepts_custom_bin_path() {
446        let p4 = P4Cli::new("C:\\tools\\p4.exe", GlobalOpts::default());
447
448        assert_eq!(p4.get_bin(), Path::new("C:\\tools\\p4.exe"));
449    }
450}