[catagits/Gitalist.git] / local-lib5 / lib / perl5 / PPI / Structure.pm

package PPI::Structure;

=pod

=head1 NAME

PPI::Structure - The base class for Perl braced structures

=head1 INHERITANCE

  PPI::Structure
  isa PPI::Node
      isa PPI::Element

=head1 DESCRIPTION

PPI::Structure is the root class for all Perl bracing structures. This
covers all forms of C< [ ... ] >, C< { ... } >, and C< ( ... ) > brace
types, and includes cases where only one half of the pair exist.

The class PPI::Structure itself is full abstract and no objects of that
type should actually exist in the tree.

=head2 Elements vs Children

A B<PPI::Structure> has an unusual existance. Unlike a L<PPI::Document>
or L<PPI::Statement>, which both simply contain other elements, a
structure B<both> contains and consists of content.

That is, the brace tokens are B<not> considered to be "children" of the
structure, but are part of it.

In practice, this will mean that while the -E<gt>elements and -E<gt>tokens
methods (and related) B<will> return a list with the brace tokens at either
end, the -E<gt>children method explicitly will B<not> return the brace.

=head1 STRUCTURE CLASSES

Excluding the transient L<PPI::Structure::Unknown> that exists briefly
inside the parser, there are eight types of structure.

=head2 L<PPI::Structure::List>

This covers all round braces used for function arguments, in C<foreach>
loops, literal lists, and braces used for precedence-ordering purposes.

=head2 L<PPI::Structure::For>

Although B<not> used for the C<foreach> loop list, this B<is> used for
the special case of the round-brace three-part semicolon-seperated C<for>
loop expression (the traditional C style for loop).

=head2 L<PPI::Structure::Given>

This is for the expression being matched in switch statements.

=head2 L<PPI::Structure::When>

This is for the matching expression in "when" statements.

=head2 L<PPI::Structure::Condition>

This round-brace structure covers boolean conditional braces, such as
for C<if> and C<while> blocks.

=head2 L<PPI::Structure::Block>

This curly-brace and common structure is used for all form of code
blocks. This includes those for C<if>, C<do> and similar, as well
as C<grep>, C<map>, C<sort>, C<sub> and (labelled or anonymous) 
scoping blocks.

=head2 L<PPI::Structure::Constructor>

This class covers brace structures used for the construction of
anonymous C<ARRAY> and C<HASH> references.

=head2 L<PPI::Structure::Subscript>

This class covers square-braces and curly-braces used after a
-E<gt> pointer to access the subscript of an C<ARRAY> or C<HASH>.

=head1 METHODS

C<PPI::Structure> itself has very few methods. Most of the time, you will be
working with the more generic L<PPI::Element> or L<PPI::Node> methods, or one
of the methods that are subclass-specific.

=cut

use strict;
use Scalar::Util   ();
use Params::Util   qw{_INSTANCE};
use PPI::Node      ();
use PPI::Exception ();

use vars qw{$VERSION @ISA *_PARENT};
BEGIN {
	$VERSION = '1.206';
	@ISA     = 'PPI::Node';
	*_PARENT = *PPI::Element::_PARENT;
}

use PPI::Structure::Block       ();
use PPI::Structure::Condition   ();
use PPI::Structure::Constructor ();
use PPI::Structure::For         ();
use PPI::Structure::Given       ();
use PPI::Structure::List        ();
use PPI::Structure::Subscript   ();
use PPI::Structure::Unknown     ();
use PPI::Structure::When        ();


#####################################################################
# Constructor

sub new {
	my $class = shift;
	my $Token = PPI::Token::__LEXER__opens($_[0]) ? shift : return undef;

	# Create the object
	my $self = bless {
		children => [],
		start    => $Token,
		}, $class;

	# Set the start braces parent link
	Scalar::Util::weaken(
		$_PARENT{Scalar::Util::refaddr $Token} = $self
	);

	$self;
}


#####################################################################
# PPI::Structure API methods

=pod

=head2 start

For lack of better terminology (like "open" and "close") that has not
already in use for some other more important purpose, the two individual
braces for the structure are known within PPI as the "start" and "finish"
braces (at least for method purposes).

The C<start> method returns the start brace for the structure (i.e. the
opening brace).

Returns the brace as a L<PPI::Token::Structure> or C<undef> if the
structure does not have a starting brace.

Under normal parsing circumstances this should never occur, but may happen
due to manipulation of the PDOM tree.

=cut

sub start  { $_[0]->{start}  }

=pod

=head2 finish

The C<finish> method returns the finish brace for the structure (i.e. the
closing brace).

Returns the brace as a L<PPI::Token::Structure> or C<undef> if the
structure does not have a starting brace. This can be quite common if
the document is not complete (for example, from an editor where the user
may be halfway through typeing a subroutine).

=cut

sub finish { $_[0]->{finish} }

=pod

=head2 braces

The C<braces> method is a utility method which returns the brace type,
regardless of whether has both braces defined, or just the starting
brace, or just the ending brace.

Returns on of the three strings C<'[]'>, C<'{}'>, or C<'()'>, or C<undef>
on error (primarily not having a start brace, as mentioned above).

=cut

sub braces {
	my $self = $_[0]->{start} ? shift : return undef;
	return {
		'[' => '[]',
		'(' => '()',
		'{' => '{}',
	}->{ $self->{start}->{content} };
}

=pod

=head1 complete

The C<complete> method is a convenience method that returns true if
the both braces are defined for the structure, or false if only one
brace is defined.

Unlike the top level C<complete> method which checks for completeness
in depth, the structure complete method ONLY confirms completeness
for the braces, and does not recurse downwards.

=cut

sub complete {
	!! ($_[0]->{start} and $_[0]->{finish});
}


#####################################################################
# PPI::Node overloaded methods

# For us, the "elements" concept includes the brace tokens
sub elements {
	my $self = shift;

	if ( wantarray ) {
		# Return a list in array context
		return ( $self->{start} || (), @{$self->{children}}, $self->{finish} || () );
	} else {
		# Return the number of elements in scalar context.
		# This is memory-cheaper than creating another big array
		return scalar(@{$self->{children}})
			+ ($self->{start}  ? 1 : 0)
			+ ($self->{finish} ? 1 : 0);
	}
}

# For us, the first element is probably the opening brace
sub first_element {
	# Technically, if we have no children and no opening brace,
	# then the first element is the closing brace.
	$_[0]->{start} or $_[0]->{children}->[0] or $_[0]->{finish};
}

# For us, the last element is probably the closing brace
sub last_element {
	# Technically, if we have no children and no closing brace,
	# then the last element is the opening brace
	$_[0]->{finish} or $_[0]->{children}->[-1] or $_[0]->{start};
}

# Location is same as the start token, if any
sub location {
	my $self  = shift;
	my $first = $self->first_element or return undef;
	$first->location;
}


#####################################################################
# PPI::Element overloaded methods

# Get the full set of tokens, including start and finish
sub tokens {
	my $self = shift;
	my @tokens = (
		$self->{start}  || (),
		$self->SUPER::tokens(@_),
		$self->{finish} || (),
		);
	@tokens;
}

# Like the token method ->content, get our merged contents.
# This will recurse downwards through everything
### Reimplement this using List::Utils stuff
sub content {
	my $self = shift;
	my $content = $self->{start} ? $self->{start}->content : '';
	foreach my $child ( @{$self->{children}} ) {
		$content .= $child->content;
	}
	$content .= $self->{finish}->content if $self->{finish};
	$content;
}

# Is the structure completed
sub _complete {
	!! ( defined $_[0]->{finish} );
}

# You can insert either another structure, or a token
sub insert_before {
	my $self    = shift;
	my $Element = _INSTANCE(shift, 'PPI::Element') or return undef;
	if ( $Element->isa('PPI::Structure') ) {
		return $self->__insert_before($Element);
	} elsif ( $Element->isa('PPI::Token') ) {
		return $self->__insert_before($Element);
	}
	'';
}

# As above, you can insert either another structure, or a token
sub insert_after {
	my $self    = shift;
	my $Element = _INSTANCE(shift, 'PPI::Element') or return undef;
	if ( $Element->isa('PPI::Structure') ) {
		return $self->__insert_after($Element);
	} elsif ( $Element->isa('PPI::Token') ) {
		return $self->__insert_after($Element);
	}
	'';
}

1;

=pod

=head1 SUPPORT

See the L<support section|PPI/SUPPORT> in the main module.

=head1 AUTHOR

Adam Kennedy E<lt>adamk@cpan.orgE<gt>

=head1 COPYRIGHT

Copyright 2001 - 2009 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
Commit	Line	Data
3fea05b9	1	package PPI::Structure;
	2
	3	=pod
	4
	5	=head1 NAME
	6
	7	PPI::Structure - The base class for Perl braced structures
	8
	9	=head1 INHERITANCE
	10
	11	PPI::Structure
	12	isa PPI::Node
	13	isa PPI::Element
	14
	15	=head1 DESCRIPTION
	16
	17	PPI::Structure is the root class for all Perl bracing structures. This
	18	covers all forms of C< [ ... ] >, C< { ... } >, and C< ( ... ) > brace
	19	types, and includes cases where only one half of the pair exist.
	20
	21	The class PPI::Structure itself is full abstract and no objects of that
	22	type should actually exist in the tree.
	23
	24	=head2 Elements vs Children
	25
	26	A B<PPI::Structure> has an unusual existance. Unlike a L<PPI::Document>
	27	or L<PPI::Statement>, which both simply contain other elements, a
	28	structure B<both> contains and consists of content.
	29
	30	That is, the brace tokens are B<not> considered to be "children" of the
	31	structure, but are part of it.
	32
	33	In practice, this will mean that while the -E<gt>elements and -E<gt>tokens
	34	methods (and related) B<will> return a list with the brace tokens at either
	35	end, the -E<gt>children method explicitly will B<not> return the brace.
	36
	37	=head1 STRUCTURE CLASSES
	38
	39	Excluding the transient L<PPI::Structure::Unknown> that exists briefly
	40	inside the parser, there are eight types of structure.
	41
	42	=head2 L<PPI::Structure::List>
	43
	44	This covers all round braces used for function arguments, in C<foreach>
	45	loops, literal lists, and braces used for precedence-ordering purposes.
	46
	47	=head2 L<PPI::Structure::For>
	48
	49	Although B<not> used for the C<foreach> loop list, this B<is> used for
	50	the special case of the round-brace three-part semicolon-seperated C<for>
	51	loop expression (the traditional C style for loop).
	52
	53	=head2 L<PPI::Structure::Given>
	54
	55	This is for the expression being matched in switch statements.
	56
	57	=head2 L<PPI::Structure::When>
	58
	59	This is for the matching expression in "when" statements.
	60
	61	=head2 L<PPI::Structure::Condition>
	62
	63	This round-brace structure covers boolean conditional braces, such as
	64	for C<if> and C<while> blocks.
65
66	=head2 L<PPI::Structure::Block>
67
68	This curly-brace and common structure is used for all form of code
69	blocks. This includes those for C<if>, C<do> and similar, as well
70	as C<grep>, C<map>, C<sort>, C<sub> and (labelled or anonymous)
71	scoping blocks.
72
73	=head2 L<PPI::Structure::Constructor>
74
75	This class covers brace structures used for the construction of
76	anonymous C<ARRAY> and C<HASH> references.
77
78	=head2 L<PPI::Structure::Subscript>
79
80	This class covers square-braces and curly-braces used after a
81	-E<gt> pointer to access the subscript of an C<ARRAY> or C<HASH>.
82
83	=head1 METHODS
84
85	C<PPI::Structure> itself has very few methods. Most of the time, you will be
86	working with the more generic L<PPI::Element> or L<PPI::Node> methods, or one
87	of the methods that are subclass-specific.
88
89	=cut
90
91	use strict;
92	use Scalar::Util ();
93	use Params::Util qw{_INSTANCE};
94	use PPI::Node ();
95	use PPI::Exception ();
96
97	use vars qw{$VERSION @ISA *_PARENT};
98	BEGIN {
99	$VERSION = '1.206';
100	@ISA = 'PPI::Node';
101	_PARENT = PPI::Element::_PARENT;
102	}
103
104	use PPI::Structure::Block ();
105	use PPI::Structure::Condition ();
106	use PPI::Structure::Constructor ();
107	use PPI::Structure::For ();
108	use PPI::Structure::Given ();
109	use PPI::Structure::List ();
110	use PPI::Structure::Subscript ();
111	use PPI::Structure::Unknown ();
112	use PPI::Structure::When ();
113
114
115
116
117
118	#####################################################################
119	# Constructor
120
121	sub new {
122	my $class = shift;
123	my $Token = PPI::Token::__LEXER__opens($_[0]) ? shift : return undef;
124
125	# Create the object
126	my $self = bless {
127	children => [],
128	start => $Token,
129	}, $class;
130
131	# Set the start braces parent link
132	Scalar::Util::weaken(
133	$_PARENT{Scalar::Util::refaddr $Token} = $self
134	);
135
136	$self;
137	}
138
139
140
141
142
143	#####################################################################
144	# PPI::Structure API methods
145
146	=pod
147
148	=head2 start
149
150	For lack of better terminology (like "open" and "close") that has not
151	already in use for some other more important purpose, the two individual
152	braces for the structure are known within PPI as the "start" and "finish"
153	braces (at least for method purposes).
154
155	The C<start> method returns the start brace for the structure (i.e. the
156	opening brace).
157
158	Returns the brace as a L<PPI::Token::Structure> or C<undef> if the
159	structure does not have a starting brace.
160
161	Under normal parsing circumstances this should never occur, but may happen
162	due to manipulation of the PDOM tree.
163
164	=cut
165
166	sub start { $_[0]->{start} }
167
168	=pod
169
170	=head2 finish
171
172	The C<finish> method returns the finish brace for the structure (i.e. the
173	closing brace).
174
175	Returns the brace as a L<PPI::Token::Structure> or C<undef> if the
176	structure does not have a starting brace. This can be quite common if
177	the document is not complete (for example, from an editor where the user
178	may be halfway through typeing a subroutine).
179
180	=cut
181
182	sub finish { $_[0]->{finish} }
183
184	=pod
185
186	=head2 braces
187
188	The C<braces> method is a utility method which returns the brace type,
189	regardless of whether has both braces defined, or just the starting
190	brace, or just the ending brace.
191
192	Returns on of the three strings C<'[]'>, C<'{}'>, or C<'()'>, or C<undef>
193	on error (primarily not having a start brace, as mentioned above).
194
195	=cut
196
197	sub braces {
198	my $self = $_[0]->{start} ? shift : return undef;
199	return {
200	'[' => '[]',
201	'(' => '()',
202	'{' => '{}',
203	}->{ $self->{start}->{content} };
204	}
205
206	=pod
207
208	=head1 complete
209
210	The C<complete> method is a convenience method that returns true if
211	the both braces are defined for the structure, or false if only one
212	brace is defined.
213
214	Unlike the top level C<complete> method which checks for completeness
215	in depth, the structure complete method ONLY confirms completeness
216	for the braces, and does not recurse downwards.
217
218	=cut
219
220	sub complete {
221	!! ($_[0]->{start} and $_[0]->{finish});
222	}
223
224
225
226
227
228	#####################################################################
229	# PPI::Node overloaded methods
230
231	# For us, the "elements" concept includes the brace tokens
232	sub elements {
233	my $self = shift;
234
235	if ( wantarray ) {
236	# Return a list in array context
237	return ( $self->{start} \|\| (), @{$self->{children}}, $self->{finish} \|\| () );
238	} else {
239	# Return the number of elements in scalar context.
240	# This is memory-cheaper than creating another big array
241	return scalar(@{$self->{children}})
242	+ ($self->{start} ? 1 : 0)
243	+ ($self->{finish} ? 1 : 0);
244	}
245	}
246
247	# For us, the first element is probably the opening brace
248	sub first_element {
249	# Technically, if we have no children and no opening brace,
250	# then the first element is the closing brace.
251	$_[0]->{start} or $_[0]->{children}->[0] or $_[0]->{finish};
252	}
253
254	# For us, the last element is probably the closing brace
255	sub last_element {
256	# Technically, if we have no children and no closing brace,
257	# then the last element is the opening brace
258	$_[0]->{finish} or $_[0]->{children}->[-1] or $_[0]->{start};
259	}
260
261	# Location is same as the start token, if any
262	sub location {
263	my $self = shift;
264	my $first = $self->first_element or return undef;
265	$first->location;
266	}
267
268
269
270
271
272	#####################################################################
273	# PPI::Element overloaded methods
274
275	# Get the full set of tokens, including start and finish
276	sub tokens {
277	my $self = shift;
278	my @tokens = (
279	$self->{start} \|\| (),
280	$self->SUPER::tokens(@_),
281	$self->{finish} \|\| (),
282	);
283	@tokens;
284	}
285
286	# Like the token method ->content, get our merged contents.
287	# This will recurse downwards through everything
288	### Reimplement this using List::Utils stuff
289	sub content {
290	my $self = shift;
291	my $content = $self->{start} ? $self->{start}->content : '';
292	foreach my $child ( @{$self->{children}} ) {
293	$content .= $child->content;
294	}
295	$content .= $self->{finish}->content if $self->{finish};
296	$content;
297	}
298
299	# Is the structure completed
300	sub _complete {
301	!! ( defined $_[0]->{finish} );
302	}
303
304	# You can insert either another structure, or a token
305	sub insert_before {
306	my $self = shift;
307	my $Element = _INSTANCE(shift, 'PPI::Element') or return undef;
308	if ( $Element->isa('PPI::Structure') ) {
309	return $self->__insert_before($Element);
310	} elsif ( $Element->isa('PPI::Token') ) {
311	return $self->__insert_before($Element);
312	}
313	'';
314	}
315
316	# As above, you can insert either another structure, or a token
317	sub insert_after {
318	my $self = shift;
319	my $Element = _INSTANCE(shift, 'PPI::Element') or return undef;
320	if ( $Element->isa('PPI::Structure') ) {
321	return $self->__insert_after($Element);
322	} elsif ( $Element->isa('PPI::Token') ) {
323	return $self->__insert_after($Element);
324	}
325	'';
326	}
327
328	1;
329
330	=pod
331
332	=head1 SUPPORT
333
334	See the L<support section\|PPI/SUPPORT> in the main module.
335
336	=head1 AUTHOR
337
338	Adam Kennedy E<lt>adamk@cpan.orgE<gt>
339
340	=head1 COPYRIGHT
341
342	Copyright 2001 - 2009 Adam Kennedy.
343
344	This program is free software; you can redistribute
345	it and/or modify it under the same terms as Perl itself.
346
347	The full text of the license can be found in the
348	LICENSE file included with this module.
349
350	=cut