/ 
Mac-Pasteboard-0.000_01
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 -binary.

-echo

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

The default is -noecho.

-id=n

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.

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 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.

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

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

exit

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

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 either module YAML::Syck or 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 http://developer.apple.com/documentation/Carbon/Conceptual/understanding_utis/ 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

This command displays the documentation for 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

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 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

paste [flavor]

This command pastes the given flavor from the current pasteboard. The default flavor is 'com.apple.traditional-mac-plain-text'. 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 [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 http://developer.apple.com/documentation/Carbon/Conceptual/understanding_utis/index.html for the concept of conformance.

pbpaste

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

synch [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.

BUGS

Bugs can be reported to the author by mail, or through http://rt.cpan.org/.

AUTHOR

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

COPYRIGHT

Copyright 2008 by Thomas R. Wyant, III (wyant at cpan dot org). All rights reserved.

LICENSE

This script is free software; you can use it, redistribute it and/or modify it under the same terms as Perl itself. Please see http://perldoc.perl.org/index-licence.html for the current licenses.

This software is provided without any warranty of any kind, express or implied. The author will not be liable for any damages of any sort relating in any way to this software.