Search Structurally

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

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.

Text constraints

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

Occurrences count

This part is rather obvious, although you need to know your base 2
arithmetic to recognize the max number.

Expression constraints

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

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

18 comments
Comment actions Permalink

I'm glad someone else finds this dialog obtuse. There weren't too many other complaints about it, so I thought it was me.

My name is Russ, and I have a structural searching problem.

0
Comment actions Permalink

Hi,

Please, describe your problem in more detail (given that you have seen
the examples of search patterns).

Russell Egan wrote:

I'm glad someone else finds this dialog obtuse. There weren't too many other complaints about it, so I thought it was me.

My name is Russ, and I have a structural searching problem.



--
Best regards,
Maxim Mossienko
IntelliJ Labs / JetBrains Inc.
http://www.intellij.com
"Develop with pleasure!"

0
Comment actions Permalink

I have a lot of problems understanding Structural Search as well. For
example I would like to use it to search all non static inner classes in
my project, but I don't know if that's possible.

Bas

0
Comment actions Permalink

seems like a promising feature that developers would like to use, but currently to non-intuitive

what about a UI that lets you choose, as a simple example:
"all classes", then constrain it by "inner classes",
"static" -> you get all inner classes returned.

-> required: a better "template" editor.
I think the templates really define some kind of "query
language for syntax tree"

0
Comment actions Permalink

Hi,

Michael Damberger wrote:


-> required: a better "template" editor.
I think the templates really define some kind of "query
language for syntax tree"

It is pretty much the Java syntax (so the attempts to find something by
non Java syntax are pretty funny).

--
Best regards,
Maxim Mossienko
IntelliJ Labs / JetBrains Inc.
http://www.intellij.com
"Develop with pleasure!"

0
Comment actions Permalink

Hi,

Thank you for detailed feedback, it will be incorporated in this and
next version of IDEA. There are some points I would like add.

- Actually, the template syntax is mostly Java syntax so any attempt to
represent, say, method other than create class and place method inside
has no search results.

- Not finding method in libraries is a bug.

- 'Apply constraint within type hierarchy' set to true will also match
superclasses and superinterfaces.

Mikael Karlsson wrote:

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.

     $_ReturnType$ $MethodName$($_ParameterType$ $_Parameter$);
>   }]]>

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

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.

Text constraints

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

Occurrences count

This part is rather obvious, although you need to know your base 2
arithmetic to recognize the max number.

Expression constraints

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

Here's a suggestion for the Search Structurally dialog box:
| Search template: [History] [Save template] [Load template] | > | ---------------------------------------------------------------------------- | > | | class $_1$ { | | > | | $_ReturnType$ $MethodName$($_ParameterType$ $_Parameter$); | | > | | } | | > | | | | > | | | | > | | | | > | ---------------------------------------------------------------------------- | > | Variables: | > | ---------------------------------------------------------------------------- | > | | name type constraints min max | | > | | _1 Type | | > | | _ReturnType Type Manifest | | > | | MethodName Name | | > | | _ParameterType Type | | > | | _Parameter Name | | > | | | | > | ---------------------------------------------------------------------------- | > | Options | > | [ ] Recursive matching | > | [ ] Case Sensitive | > | [ ] Maximum Matches | > | | > | Scope: [ Current File ] [...] | > | | > | [Find] [Cancel] [Help] | > --------------------------------------------------------------------------------]]>
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. :)



--
Best regards,
Maxim Mossienko
IntelliJ Labs / JetBrains Inc.
http://www.intellij.com
"Develop with pleasure!"

0
Comment actions Permalink

Bas Leijdekkers wrote:

I have a lot of problems understanding Structural Search as well. For
example I would like to use it to search all non static inner classes in
my project, but I don't know if that's possible.

Bas


I thought a search like the one in the attached screenshot should be able to find
that. Funny enough, the "Invert condition" switch doesn't do what I'd expect. It
always finds both static and non-static inner classes regardless of this setting.
Either I don't get it's meaning or there is a bug... :/

Sascha



Attachment(s):
search.PNG
0
Comment actions Permalink

Hi,

Modifiers are not matched by the search in current version.

Sascha Weinreuter wrote:

Bas Leijdekkers wrote:

>> I have a lot of problems understanding Structural Search as well. For
>> example I would like to use it to search all non static inner classes
>> in my project, but I don't know if that's possible.
>>
>> Bas


I thought a search like the one in the attached screenshot should be
able to find
that. Funny enough, the "Invert condition" switch doesn't do what I'd
expect. It
always finds both static and non-static inner classes regardless of this
setting.
Either I don't get it's meaning or there is a bug... :/

Sascha

------------------------------------------------------------------------



--
Best regards,
Maxim Mossienko
IntelliJ Labs / JetBrains Inc.
http://www.intellij.com
"Develop with pleasure!"

0
Comment actions Permalink

On 15-06-2004 16:39, Sascha Weinreuter wrote:

Bas Leijdekkers wrote:

>> I have a lot of problems understanding Structural Search as well. For
>> example I would like to use it to search all non static inner classes in
>> my project, but I don't know if that's possible.
>>
>> Bas


I thought a search like the one in the attached screenshot should be able to find
that. Funny enough, the "Invert condition" switch doesn't do what I'd expect. It
always finds both static and non-static inner classes regardless of this setting.
Either I don't get it's meaning or there is a bug... :/

Sascha


I thought exactly the same, with the same results. At first I thought
variables could only match java identifiers, but that's not the case
either I think. The uses of structural search appear a bit more limited
than I expected.

Bas

0
Comment actions Permalink

Sorry, I was being facetious. "My name is Bob, and I'm an alcoholic..."

My only problem with Structural Search was that I didn't understand how to use it at all. The options were not self-explanatory, and the help is not written yet. I'm just agreeing with the first post, that the current dialog is tough to understand and use.

0
Comment actions Permalink

I'm trying to use the structural search facility to find
methods that match the predefined pattern

where the variables are defined as follows:
_1 nothing specified, is target: not checked
_ReturnType regular text: AddressPool, is target: checked
MethodName: regex: find.*AddressPool, is target: checked
_ParameterType: nothing specified, is target: not checked
_Parameter: nothing specified, is target: not checked

and the search was restricted to the current file.

This search yields several results, as I expected, although only the method name is highlighted in the
search results pane.

However, if the method name is marked as not being a target of the search, then the result shows the enclosing
class but none of the methods that were found before. Can you please explain what the interaction and significance
is of the various variables (if any) and why, even though
the help states that:
If the last check box, This variable is target of the search, is selected, the search results will show not the entire expression but the selected variable(s) only.
the results do not match what I expect

0
Comment actions Permalink

sure your template syntax matches the java syntax,
only the "attribute" part sure is not java syntax (the checkboxes).

I propose no different syntax, only a "fool proof UI" ;)

You can see that your EAPers have problems with it -
it's clear that it needs to be improved.
Maybe you don't manage it for Pallada - then do it for
next version.

0
Comment actions Permalink

Hi,

I am all for good UI, the only problem is that the significant feedback
started to appear near Pallada release so significant UI and
functionality changes are most like in 5.0.

Michael Damberger wrote:

sure your template syntax matches the java syntax,
only the "attribute" part sure is not java syntax (the checkboxes).

I propose no different syntax, only a "fool proof UI" ;)

You can see that your EAPers have problems with it -
it's clear that it needs to be improved.
Maybe you don't manage it for Pallada - then do it for
next version.



--
Best regards,
Maxim Mossienko
IntelliJ Labs / JetBrains Inc.
http://www.intellij.com
"Develop with pleasure!"

0
Comment actions Permalink

>significant UI and
>functionality changes are most like in 5.0.

that's ok - you cannot implement everything
at the same time.
I'm already looking forward to 5.0 EAP ;)

0
Comment actions Permalink

Hi,

By default (no target specified) the result of the search is match of
whole template (in your example this is the class).
If we mark method name to be the search target then it will be part of
the output (marking method name only is the convenience).
The behavior with specified variables being marked as 'target of the
search' is most likely to be bug.

Bonny Rais wrote:

I'm trying to use the structural search facility to find
methods that match the predefined pattern
class $_1$ { > $_ReturnType$ $MethodName$($_ParameterType$ $_Parameter$); > } > ]]>
where the variables are defined as follows:
_1 nothing specified, is target: not checked
_ReturnType regular text: AddressPool, is target: checked
MethodName: regex: find.*AddressPool, is target: checked
_ParameterType: nothing specified, is target: not checked
_Parameter: nothing specified, is target: not checked

and the search was restricted to the current file.

This search yields several results, as I expected, although only the method name is highlighted in the
search results pane.

However, if the method name is marked as not being a target of the search, then the result shows the enclosing
class but none of the methods that were found before. Can you please explain what the interaction and significance
is of the various variables (if any) and why, even though
the help states that:
If the last check box, This variable is target of the search, is selected, the search results will show not the entire expression but the selected variable(s) only.
the results do not match what I expect



--
Best regards,
Maxim Mossienko
IntelliJ Labs / JetBrains Inc.
http://www.intellij.com
"Develop with pleasure!"

0
Comment actions Permalink

Maxim,
I've dome some more experimenting and am even more confused:
When I used the methodCall template ($Instance$.$MethodCall$($Parameter$))
The search matched method calls with and without the presence of $Instance$ and this can be explained,
I suppose, by the fact that $Instance$
has count constraint.

I am not sure how the '.' following this is treated - is it a literal or a regex '.'?

Then, when I tried to use my template to find occurances of method declarations matching constraints
($returnType$ $methodDecl$( $argument$))where:
returnType has a pattern 'ISP.*', count, is target
methodDecl has a pattern 'find.ISP.', count, is target
argument has no pattern, count, is not a target

The search did not find anything in the current file (the scope) although a regular search does match the patterns.

My questions are:
1. Are the spaces in my pattern significant? Should I be using regex '.' instead?
2. Are the parentheses expected to be matched in the text or are they directives to the structural search that this is a method call?
3. How to I distinguish, when specifying a template, between commas and other syntactical separators and text I need to match
(It seems that the $argument$ section specification does not require commas, etc).

A short description of how the template itself is parsed and treated and therefore has to be created would be very helpful.

Cheers,

Bonny

0
Comment actions Permalink

Hi,

- Template code is Java code (!!!!!!!!) (and it is parsed by the same
parser as your Java code). Given that correct pattern for method is:
class $Class$ {
$returnType$ $methodDecl$( $argumenttype$ $argument$);
}
- whitespace is not significant
- . is java selection operator, meaning of () depends on context (method
parameter list or method call invokation list, etc):
- variables with multiple occurences could have some white space, ',' or
other insignificant delimiters, as appropriate by Java language


Bonny Rais wrote:

Maxim,
I've dome some more experimenting and am even more confused:
When I used the methodCall template ($Instance$.$MethodCall$($Parameter$))
The search matched method calls with and without the presence of $Instance$ and this can be explained,
I suppose, by the fact that $Instance$
has count constraint.

I am not sure how the '.' following this is treated - is it a literal or a regex '.'?

Then, when I tried to use my template to find occurances of method declarations matching constraints
($returnType$ $methodDecl$( $argument$))where:
returnType has a pattern 'ISP.*', count, is target
methodDecl has a pattern 'find.ISP.', count, is target
argument has no pattern, count, is not a target

The search did not find anything in the current file (the scope) although a regular search does match the patterns.

My questions are:
1. Are the spaces in my pattern significant? Should I be using regex '.' instead?
2. Are the parentheses expected to be matched in the text or are they directives to the structural search that this is a method call?
3. How to I distinguish, when specifying a template, between commas and other syntactical separators and text I need to match
(It seems that the $argument$ section specification does not require commas, etc).

A short description of how the template itself is parsed and treated and therefore has to be created would be very helpful.

Cheers,

Bonny



--
Best regards,
Maxim Mossienko
IntelliJ Labs / JetBrains Inc.
http://www.intellij.com
"Develop with pleasure!"

0

Please sign in to leave a comment.