This starts as a rant about my problems with the Search Structurally
functionality, becomes a sort of explanation of the different options
in the dialogs, and ends up with a suggestion on how these things
could be made easier.
I may the densest guy in the world, but I cannot make heads or tails
of the Search Structually tool.
I wanted to find all methods that return a java.util.jar.Manifest
I've got one method in Version.java that returns a Manifest:
I want to find others in the Java Libraries. One such method
is in JarFile.java:
So, I open Search Structurally, type
and search. Nothing. Ok, doesn't it like regular expressions? Try again.
Nothing. Starting to wonder. Trim search template down to
and search in just Version.java. No occurrences found in Current File.
Apparently I'm approaching this the wrong way. I'll try with a template.
'methods of the class' seems fine.
Running this on my Version.java finds all methods in the class. Looks
like I'm on the right track. Let's modify this so that we only find
methods that return Manifest. Edit Variables. I want to specify criteria
for the $_ReturnType$ variable. It should be of the type Manifest. Is that
a text constraint or an expression constraint?
I put in 'Manifest' as a Text constraint and search in Version.java.
Yes, it found my getManifest method. Let's try it on the full Project
It didn't find the getManifest method in java.util.JarFile. Too bad.
Why is that? If I open JarFile.java and search just that file then I
get a hit. Are the standard libraries not searched? Is this a bug?
The Edit Variables dialog is less than obvious. Here's an attempt
to figure out what the different things mean.
I assume that the specified text/regular expression matches against
the actual text in the file.
'Apply constraint within type hierarchy' What does that mean? It seems
to mean something like 'include inherited methods/fields/inner classes
in search scope'. Checking this option on the $MethodName$ variable
in the 'methods of the class' template finds not just methods of
the current class but also all inherited methods.
'Pattern is aligned on word boundary in larger text'? Another puzzler.
Does it mean something like the more common 'match whole words'?
This part is rather obvious, although you need to know your base 2
arithmetic to recognize the max number.
This would have to be constraints that are applied to the type of the
matched item. I guess this only applies when the matched item is an
expression, rather than, say, a keyword or a method name.
'Value is read' Not too hard. Check this box to only match expressions
where a value is read, i.e. where a field or variable is read. Inverting
that conditon gives all locations where... what? All locations where
a field or variable is not read, i.e. where a variable is written, a
value returned, primitive values (0, 1, 2, ...).
'Value is written' Check this box to only match expressions where a field
or variable is assigned a value. Inverting the condition gives the complement.
'Text/regular expression for java expression type' This pattern is applied
to the type of the matched item, as opposed to the text constraint which
applies to the actual text.
'Apply constraint within type hierarchy' It's that one again. And apparently
with a different meaning this time. Here I guess it means 'Match against
superclasses as well'. Using a pattern 'SuperClass' will match all expressions
with a type of SuperClass. Checking 'Apply constraints within type hierarchy'
will match all expressions with type SuperClass or any subclass of SuperClass.
Another way to put it is that the pattern is matched against the type of
the expression and all supertypes (implemented interfaces/extended classes).
'This variable is a target for the search' Specifies whether a match
of this variable should be listed as a hit in the results.
Bits and pieces:
In the templates, why are some variables prefixed with '_'.
How to fix? Going to the Edit Variables dialog all the time is just murder,
and that's ignoring the difficulty of understanding the dialog. I think that
we need immediate access to the variables from the Search Structurally dialog.
Putting together a pattern is a parallel process with both the template and
Here's a suggestion for the Search Structurally dialog box:
The variables table is updated automatically when the template is edited.
The type column of the variables table shows the expected type of the element
matched by this variable. The type can, given enough context, be deduced
automatically or it can be specified by the user. The type defines which constraints
are available for that specific variable.
Some example types and their constraints:
Type (A class or primitive type), name, match in hierarchy
Name (Variable name, parameter name, field name, etc), name
I think I'll stop here before I make too much of a fool of myself. :)