/ 
Mac-Pasteboard-0.105
River stage one • 1 direct dependent • 1 total dependent
/ pbtool

NAME

pbtool - Manipulate Mac OS X pasteboards/clipboards.

SYNOPSIS

$ pbtool
pbtool> paste
Flags = 0 (kPasteboardFlavorNoFlags)
Able was I ere I saw Elba.
pbtool> clear
pbtool> copy "Madam, I'm Adam."
pbtool> exit

OPTIONS

Pbtool takes the following options:

--binary

This option specifies that no end-of-line translation is done on output. Despite its name, it should be fine for text. To turn this off, specify -nobinary.

The default is --no-binary under Catalina (macOS 10.15) and above, and --binary otherwise.

--default-flavor

--default-flavor public.utf16-external-plain-text

This option specifies the default flavor of text if no flavor is specified in the command.

The default is

--default-flavor public.utf8-plain-text

under Catalina (macOS 10.15) and above, and

--default-flavor com.apple.traditional-mac-plain-text

otherwise.

--echo

This option specifies that input is echoed to standard error. To turn this off, specify --noecho.

The default is --noecho.

--id

--id 42

This option specifies the pasteboard item ID to be used for copy and paste, as an unsigned integer. To specify no item id (which in fact causes copy to use item ID 1, and paste to use the last item that contains the desired flavor), specify -noid.

The default is -noid.

DETAILS

Pbtool is a Perl script that acts as a wrapper for Mac::Pasteboard. Most functions of the package are available through the script, and it adds a couple on its own account. The commands in general operate on the current pasteboard, which initially is the system clipboard. Commands also exist for changing the script's notion of the current pasteboard.

Input is from standard in, using Term::ReadLine if that is available and the input is a terminal.

Blank input lines and input lines whose first non-blank character is '#' are ignored. Any lines left are broken into tokens on spaces, though quoted text is kept together. Text::ParseWords does the heavy lifting here.

Some input tokens are interpreted based on their leading characters, as follows.

Tokens beginning with '<<' are taken to specify 'here documents'. The remainder of the token specifies the string that ends the here document, which consists of all lines of the input following the 'here document' specification up to but not including the string that specifies its end. The 'here document' replaces the token that specifies it. If multiple here documents are specified on an input line, they are taken out of the input in left-to-right order.

Tokens beginning with '<' are taken to specify an input file, whose name is the rest of the token. The file is read, and its contents replace the token.

Tokens beginning with '>' or '>>' are taken to specify an output file, whose name is the rest of the token. Output of the command goes to that file, which is opened for appending if the token begins with '>>', or for output if it begins with '>'. The token is removed from the list of tokens passed to the command.

Beginning in version 0.012_01 you can specify a pbtool command on the command line that runs the script, like this:

$ pbtool copy_file some_text.txt

This will execute the specified pbtool command, and then exit.

The actual commands are:

clear [name]

This command clears the current pasteboard. If a name is given, the named pasteboard becomes the current pasteboard, and it is cleared. If no name is given and there is no current pasteboard, the system clipboard becomes the current pasteboard and is cleared.

copy

pbtool> copy data [flavor [flags]]

This command copies the given data to the current pasteboard as the given flavor and the given flavor flags. The flavor flags default to 0, and the flavor to 'com.apple.traditional-mac-plain-text'. If there is no current pasteboard the system clipboard becomes the current pasteboard, but you get an error anyway because you do not own it at this point, not having cleared it.

If the id setting is set to a number, your data is copied to the item with that ID. If it is set to undef, it is copied to item id 1.

copy_file

pbtool> copy_file file_name [flavor [flags]]

This command copies the contents of the given file to the current pasteboard as the given flavor and the given flavor flags. The flavor flags default to 0, and the flavor to defaultFlavor. If there is no current pasteboard the system clipboard becomes the current pasteboard, but you get an error anyway because you do not own it at this point, not having cleared it.

The file's encoding is assumed to be that implied by the flavor, if any.

If the id setting is set to a number, your data is copied to the item with that ID. If it is set to undef, it is copied to item id 1.

create

pbtool> create [name]

The named pasteboard is created if necessary, and becomes the current pasteboard. If no name is specified, you get the system clipboard, named 'com.apple.pasteboard.clipboard'.

dump

pbtool> dump

This command copies the current pasteboard object to standard out in Data::Dumper format.

exit

pbtool> exit

This command causes the script to exit. End-of-file also has this effect.

encode

pbtool> encode [boolean]

This command displays whether data are encoded onto and decoded from the pasteboard. If an argument is passed, it becomes the new setting. The arguments are by convention 1 to encode, and 0 not to encode, though the value of this setting is interpreted in its Perl Boolean sense.

Note that this only affects certain flavors of data.

flavor

pbtool> flavor [new_default_flavor]

This command displays the name of the current default flavor. If an argument is passed, this becomes the new default flavor.

flavors

pbtool> flavors [conforms_to]

This command dumps the flavors of data present on the clipboard which conform to the given flavor, If no conforming flavor is given, all flavors are dumped. If the id is defined, only data from that pasteboard item are dumped. The output is in YAML if module YAML can be loaded, or in Data::Dumper format if that module can be loaded. Either way, what you actually get is an array of anonymous hashes. Each hash has the following keys:

flag_names: a reference to a list of the names of the flags set;
flags: the flavor flags;
flavor: the name of the flavor;
tags: the tags associated with the flavor, if any;
id: the ID of the pasteboard item the flavor came from.

The tags hash will contain zero or more of the following keys:

extension: the preferred file name extension for the flavor;
mime: the preferred MIME type for the flavor;
os: the preferred 4-byte Mac OS document type for the flavor;
pboard: the preferred NSPBoard type for the flavor.

See https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/understanding_utis/understand_utis_intro/understand_utis_intro.html for the concept of conformance. As a trivial example,

pbtool> flavors public.text

gets you all the flavors which the system understands as conforming to the 'public.text' flavor. This is not quite the same as all text data; ad-hoc flavors may contain text, but if the flavors are not known to the system to conform to public.text or some subflavor thereof, you will not see them.

help

pbtool> help

This command displays the documentation for pbtool.

name

pbtool> name

This command displays the name of the current pasteboard. If there is no current pasteboard, the system clipboard is made the current pasteboard, and its name is displayed.

opt

pbtool> opt [ new options ]

This command displays the options currently in effect. If it has any arguments, they are interpreted as options, with the leading '-' on the option name being required. The given options (if any) are set, and the modified values are displayed. For example (assuming all defaults are still in effect):

pbtool> opt -nobinary -id 2
opt -nobinary -noecho -id=2

output

pbtool output (encoding)

This command displays the encoding used for non-binary output to standard out. If no encoding has been specified, the display will be 'none'.

If an argument is specified, it becomes the new encoding. Specifying 'none' as the new encoding removes the the encoding, if any.

paste

pbtool> paste [flavor]

This command retrieves the given flavor from the current pasteboard and copies it to standard out. The default flavor is 'public.utf8-plain-text' if built with UTF-8 support, or 'com.apple.traditional-mac-plain-text' otherwise. The flavor flags are written to standard error. If no pasteboard is current, the system pasteboard is made current. If the id setting is undef, the last occurrence of the desired flavor (if any) is returned; otherwise the flavor is returned from the item whose ID is the given id.

paste_all

pbtool> paste_all [conforms_to]

This command displays all data on the current pasteboard conforming to the given flavor. If no flavor is given, all flavors are displayed. If the id is set, only data from the corresponding item are displayed.

The output is the same as for flavors, but in addition the 'data' key holds the actual data. If there is no current clipboard, the system pasteboard is made the current clipboard.

See https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/understanding_utis/understand_utis_intro/understand_utis_intro.html for the concept of conformance.

pbpaste

pbtool> pbpaste

This command is equivalent to paste, but always uses the system clipboard.

set

This is just an alias for opt.

show

This is a variant on opt that ignores its arguments, so all that happens is that the current values of the options are displayed.

status

pbtool> status [new_value]

This command displays the current status setting of the current pasteboard, optionally setting it first to the given value. If there is no current pasteboard, the system clipboard is made the current pasteboard, and its status is displayed.

synch

pbtool> synch [pasteboard_name]

This command synchronizes with the current pasteboard. If a name is given, that pasteboard is made the current pasteboard, and it is synchronized. If there is no current pasteboard and no name is given, the system clipboard is made the current pasteboard.

The synchronization flags returned by the operation are written to standard out.

unique

pbtool> unique

This command creates a pasteboard with a unique name. Under Mac OS 10.4 and above, this name is available via the name command.

BUGS

Bugs can be reported to the author by mail, or through https://github.com/trwyant/perl-Mac-Pasteboard/issues/.

AUTHOR

Thomas R. Wyant, III (wyant at cpan dot org)

COPYRIGHT AND LICENSE

Copyright (C) 2008, 2011-2024 by Thomas R. Wyant, III

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.