parse a format (see perldoc -f format) as a single token.

lib/PPI/Token.pm

@@ -37,6 +37,7 @@ use PPI::Token::BOM                   ();
 use PPI::Token::Whitespace            ();
 use PPI::Token::Comment               ();
 use PPI::Token::Pod                   ();
+use PPI::Token::Format                ();
 use PPI::Token::Number                ();
 use PPI::Token::Number::Binary        ();
 use PPI::Token::Number::Octal         ();

lib/PPI/Token/Format.pm

@@ -0,0 +1,84 @@
+package PPI::Token::Format;
+
+=pod
+
+=head1 NAME
+
+PPI::Token::Format - A format for the write function
+
+=head1 INHERITANCE
+
+  PPI::Token::Pod
+  isa PPI::Token
+      isa PPI::Element
+
+=head1 DESCRIPTION
+
+A single C<PPI::Token::Format> object represents a single format section
+
+=head1 METHODS
+
+This class provides no additional methods beyond those provided by its
+L<PPI::Token> and L<PPI::Element> parent classes.
+
+=cut
+
+use strict;
+use Params::Util qw{_INSTANCE};
+use PPI::Token   ();
+
+# VERSION
+
+our @ISA = "PPI::Token";
+
+#####################################################################
+# PPI::Element Methods
+
+### XS -> PPI/XS.xs:_PPI_Token_Pod__significant 0.900+
+sub significant() { 1 }
+
+
+
+
+
+#####################################################################
+# Tokenizer Methods
+
+sub __TOKENIZER__on_line_start {
+	my $t = $_[1];
+
+	# Add the line to the token first
+	$t->{token}->{content} .= $t->{line};
+
+	# Check the line to see if it is a =cut line
+	if ( $t->{line} =~ /^\.$/  ) {
+		# End of the token
+		$t->_finalize_token;
+	}
+
+	0;
+}
+
+1;
+
+=pod
+
+=head1 SUPPORT
+
+See the L<support section|PPI/SUPPORT> in the main module.
+
+=head1 AUTHOR
+
+Adam Kennedy E<lt>[email protected]<gt>
+
+=head1 COPYRIGHT
+
+Copyright 2001 - 2011 Adam Kennedy.
+
+This program is free software; you can redistribute
+it and/or modify it under the same terms as Perl itself.
+
+The full text of the license can be found in the
+LICENSE file included with this module.
+
+=cut

lib/PPI/Token/Whitespace.pm

@@ -186,7 +186,11 @@ sub __TOKENIZER__on_line_start {
 		# anything to the "use v6..." line. So return as if
 		# we didn't find anything at all.
 		return 1;
-	}
+	} elsif ( $line =~ /^\s*format\s*[A-Za-z0-9_]+\s*=\s*$/ ) {
+        $t->_new_token( 'Format', $line );
+        $t->{class} = 'PPI::Token::Format';
+        return 0;
+    }
 
 	1;
 }

t/ppi_token_format.t

@@ -0,0 +1,52 @@
+#!/usr/bin/perl
+
+# Unit testing for PPI::Token::Format
+
+use lib 't/lib';
+use PPI::Test::pragmas;
+use Test::More tests => 4;
+
+use PPI;
+
+
+use lib 't/lib';
+use Helper 'check_with';
+
+my $Document = PPI::Document->new(\<<'END_PERL');
+#!/usr/bin/env perl
+use strict;
+
+format BYDEPTH_TOP =
+Top disk utilization in @*, @* level(s) deep
+                        $BASEPATH, $DEPTH
+================================================================================
+
+subpath                                                         disk utilization
+-------                                                         ----------------
+.
+
+__END__
+
+=head1 SYNOPSIS
+
+  ⋮
+  -d, --depth DEPTH[,...]  displays disk usage DEPTH levels into hierarchy
+                           (default: 2); separate multiple DEPTHs with commas
+  --[no-]by-depth          [suppresses] displays usage by depth in hierarchy
+  -q, --[no-]quiet         suppress progress messages (implied for '-r')
+  FILE                     is the output of a previous 'find DIR -printf ...'
+                           invocation, as described below; use '-' for stdin
+
+=cut
+END_PERL
+
+isa_ok( $Document, 'PPI::Document' );
+my $formats = $Document->find('Token::Format');
+is( scalar @{$formats}, 1, 'Found the 1 format' );
+
+my $uses = $Document->find('Statement::Include');
+is( scalar @{$uses}, 1, 'Found the 1 include' );
+
+my $pods = $Document->find('Token::Pod');
+is( scalar @{$pods}, 1, 'Found the 1 pod section' );
+