1. Overview
2. Search Method Call
3. Search Method Definition
4. Search Class Definition
5. Search Class Field
6. Search Field Reference
7. Search Variable
8. Search Multiple References
9. Smart Query BNF Syntax

1. Overview

How to specify a search query to find the relevant code is a complex task, what could be better than simply typing about the same code as you do in your daily development work? This is what our smart query system all about.

Smart query provides a powerful way for you to freely enter queries using the same interface to perform different searches, from single item search to complex combination of multiple search terms. Our query parser processes the input and builds an internal query consisting of method calls, method definitions, class definitions, field definitions, field references, and variables to feed into the search engine. You can pretty much use this form to perform most searches that can be also done using other advanced individual forms, as shown below.

The query you enter should be familiar to you, as it is very close to the existing programming language syntax, mostly in C++, Java and C# syntax. The objective is to allow typing simple programming code into the text box, and yet result in very complex search queries. Through smart form, you are able to search single items, as well as complex combination of multiple items.

To the best of our knowledge, this is the first time that complex search queries can be specified in such a simple and straightforward manner. We will continue to innovate in this space.

Through this documentation, we will illustrate how to specify a query with many examples. The complete syntax is included in the last section. The following are some general guidelines:

• single word  (printf), or qualified identifier with dots (java.lang.tring.tostring) can be used to specify a type or a type member. A type member is a method or a field.
• scope (::) symbol may be used in addition to dot ( .) to specify a method, an operator, or a field that belong to a class, for example, string::substring.
• question mark (?) is used to indicate any names when used.
• explicit words may be used at the beginning to specify the type of the searches.  class for class definitions, method or func for method definitions, methodref or call for method refs, field for field definition, fieldref for field references, var for variables.
• definitions may be specified with {}at the end, or use explicit words at the beginning.
• semicolon (;) may be used to specify multiple search terms

2. Search Method Call

To search a method call, the simplest way is to enter the method or function name as the query, then click the Search button. You can also use the prefix methodref, call or classref at the beginning to explicitly specify the search type to be method calls. The special classref prefix takes a class name to indicate searching all invocations of any method defined in that class.

Examples	Description
printf printf() methodref printf call printf	Search the printf method call
java.lang.String.substring java.lang.String::substring	Search method call of substring method in java.lang.String class
float::tostring float.tostring	Search method call of tostring method in Float class
float::? float.? classref float	Search all method calls of any methods defined in Float class
int string.substring(int)	Search method call of this specific method: the substring method defined in class string that has one argument of int and returns int type
main(int, char **) main(int args, char** argv)	Search function call of main method that takes 2 arguments, 1st arg is of int type, 2nd arg is of char** type
(int, string)	Search any method call that takes 2 arguments, with 1st arg of int type and 2nd arg of string type
object ?(int, string)	Search any method call that returns object type and takes 2 arguments, with 1st arg of int type and 2nd arg of string type

3. Search Method Definition

To search a method definition, you can add {} after a method ref query, or use prefix: method or func before a method ref query.

Examples	Description
printf {} printf() {} method printf func printf	Search the printf method definition
java.lang.String.substring {} java.lang.String::substring {}	Search method definition of substring method in java.lang.String class
float::tostring {} float.tostring {}	Search method definition of tostring method in Float class
int string.substring(int) {}	Search method definition of this specific method: the substring method defined in class string that has one argument of int and returns int type
main(int, char **) {} main(int args, char** argv) {}	Search function call of main method that takes 2 arguments, 1st arg is of int type, 2nd arg is of char** type
(int, string) {}	Search any method definition that takes 2 arguments, with 1st arg of int type and 2nd arg of string type
object ?(int, string) {}	Search any method definition that returns object type and takes 2 arguments, with 1st arg of int type and 2nd arg of string type

4. Search Class Definition

To search a class definition, you can use the class, interface, struct or enum prefix before a type name. A type name may be a simple identifier, or a fully qualified name separated by dot (.) . You can use colon (:) to specify base and interface types.

Examples	Description
class string struct rect interface Runnable enum Color	Search class definitions with the prefix words
class java.lang.String : Object	Search definition of the  java.lang.String class whose super class is Object
class ? : Object, Runnable	Search any class definitions whose super class is Object implementing Runnable interface

5. Search Class Field

To search a class field, you need to specify a class name followed by a field name. If you use the scope symbol (::) as separator, or use the special prefix word: field , you can use the field name directly, e.g., array::length; However, if you use dot (.) as separator, you need to append the dollar sign ($ ) in front of the field name, e.g., array.$length. As you might have noted, the dollar sign is used to distinguish fields (also variables) from methods. A field type can be specified before a field name.

As usual, braces {} are used to indicate a definition. If the prefix field is used, you don't need to add {} at the end.

Examples	Description
array.$length   { }  array::$length  { } field array.length	Search the field definitions of the length field defined in the array class
float Rect.$width  { } float Rect::$width { } field float Rect.width	Search definition of the width field in the Rect class, the type of the field is float
field width	Search any field definitions whose name is width, the field might belong to any classes

6. Search Field Reference

To search a field reference, you need to specify a class name followed by a field name. If you use the scope symbol (::) as separator, or use the special prefix word: fieldref , you can use the field name directly, e.g., array::length; However, if you use dot (.) as separator, you need to append the dollar sign ($ ) in front of the field name, e.g., array.$length. As you might have noted, the dollar sign is used to distinguish fields (also variables) from methods. A field type can be specified before a field name.

Examples	Description
array.$length    array::$length  fieldref array.length	Search the field references of the length field defined in the array class
float Rect.$width   float Rect::$width  fieldref float Rect.width	Search references of the width field in the Rect class, the type of the field is float
fieldref width	Search any field references whose name is width, the field might belong to any classes

7. Search Variable

To search a variable, you need to specify at least a variable name. If you use the special prefix word: var , you can use the variable name directly, e.g., obj; However, if you don't use the var prefix, you need to add the dollar sign ($ ) in front of the variable name, e.g., $var. As you might have noted, the dollar sign is used to distinguish fields (also variables) from methods. A variable type can be specified before a variable name.

Examples	Description
$x    var x	Search variable x
java.awt.panel $p   var java.awt.panel p	Search variable p, whose type is the java.awt.panel class

8. Search Multiple References

The sections we discussed so far are focused on single item searches; However, many times, you may want to find sample code that invokes multiple method calls, uses several variables, refers to a few field references. You can very easily achieve this, in a way that should be familiar to you.

This is the most powerful feature of our smart query interface. Using the similar syntax as you program every day, you are about to enter the most complex queries very easily. The basic idea is that you enter a segment of code snippets, our query parser automatically figures out what to search in terms of individual elements.

To specify multiple references, you need to use semicolon (;) to separate each reference. The references you can enter for each semicolon can be method calls, field references and variables. The syntax for each reference is exactly same as what we discussed in sections above. If you want to confine searches to a specific method definition, you can specify the method header as well.

Examples	Description
fopen; fread; fclose; call fopen; call fread; call fclose;	Search any method that contains these three function calls: fopen, fread and fclose
$pos; fieldref length;java.lang.string.substring	Search any method that contains variable pos, field reference of length, and method call of the substring method in java.lang.string class
main() {thread.start; exit(); }	Search any main method that contains method call of the start method of thread class, and also method call of the exit method.

9. Appendix - Smart Query BNF Grammar

This appendix contains summaries of the lexical and syntactic grammars  (BNF) for the smart query that a user can input to the Codase web interface. Our query parser fully implements the grammar specified here. 

A.1 Tokens

DOT         = "."

COMMA       = ","

COLON       = ":"

SEMICOLON   = ";"

SCOPE       = "::"

QUESTION    = "?"

STAR        = "*"

CLASS       = "class"

STRUCT      = "struct"

ENUM        = "enum"

INTERFACE   = "interface"

LPAREN      = "("

RPARAN      = ")"

LBRACKET    = "["

RBRACKET    = "]"

LBRACE      = "{"

RBRACE      = "}"

LT           = "<"

GT           = ">"

IDENTIFIER  // same as java identifier

OverloadableOperator: one of

 +  -  *  /  &  |  ^  %  =  >  <  !  ~  ++  --  ==  <=  >=  !=  <<  >>  ->  []

A.2 Starting Markers

Each of the following words marks a specific language construct when used as the first word of a statement. They are considered as normal identifiers when used anywhere else.

CLASSREF    = "classref"

METHOD      = "method"

FUNC        = "func"

METHODREF   = "methodref"

CALL        = "call"

FIELD       = "field"

FIELDREF    = "fieldref"

VAR         = "var"  

A.3 Syntactic Grammar

This section describes the grammar in BNF syntax. Each production rules starts with a name followed by a colon (:) sign. Each rule consists of one line or multiple lines of sub rules, with each line representing an option for the production rule. Brackets, [ ], indicates an option, 0 or 1 times. Braces, { }, indicates the enclosed item can appear 0 or more times. The vertical bar, |, indicates one of the items in the group must appear. Capital terms are tokens defined in the above section.

A.3.1 Compile Unit

This is the starting rule. The query parser starts the parsing from here.

CompileUnit:

      ClassDef

      MethodDef

      FieldDef

      Ref

      RefBlock   

A.3.2 Identifier and Qualified Identifier

 Ident:

      IDENTIFIER

Qualident:

      Ident { DOT Ident }

A.3.3 Dollar identifier

An identifier starts with a dollar sign, e.g., $width, $x. This is used as name for fields and variables.

DollarIdent:

      Ident starting with dollar ($) sign

A.3.4 Types

BasicType:

   byte

   short

   char

   int

   long

   float

   double

   boolean

TypeArgument:

      type

TypeArguments:

      LT TypeArgument { COMMA TypeArgument } GT

Type:

      Qualident  [ TypeArguments ]  { STAR }  { LBRACKET RBRACKET }

      BasicType  { STAR }  { LBRACKET RBRACKET }

TypeList:

      Type { COMMA Type}

A.3.5 Scoped Member Access

The scope (::) token is used as in c++ to separate a member name from its enclosing class, for example, java.lang.String::substring, represents the substring method in the java.lang.string class.

ScopedMember:

      QualIdent  SCOPE  Ident   

ScopedOperator:

      QualIdent SCOPE OverloadableOperator 

A.3.6 Classes

TypeParameters:

      LT Ident { COMMA Ident } GT

ClassDef:

      CLASS | STRUCT | ENUM |INTERFACE   QualIdent | QUESTION   [TypeParameters] [COLON TypeList]

ClassRef: // invoke any methods of a class

      CLASSREF QualIdent

      QualIdent SCOPE QUESTION  // java.lang.thread::?

      QualIdent DOT QUESTION    // java.lang.thread.?

A.3.7 Methods

ParamTypeList:

      Type [Ident]  { COMMA Type [Ident]}

Signature:

      LPAREN  [ParamTypeList]  RPAREN

MethodHeader:          

      QualIdent [ Signature] // e.g., printf, string.tostring

      ScopedMember [ Signature ]

      Signature      // e.g., (int, string) to return all methods with the specified param types

      Type QualIdent [SCOPE Ident] Signature

      Type QUESTION  Signature              // e.g. int ?()

      OverloadableOperator [ Signature ]

      Type OverloadableOperator  Signature

      ScopedOperator [ Signature ]

      Type QualIdent SCOPE OverloadableOperator Signature

The special question mark, "?", indicates match any name. When there is return type, LPAREN and RPAREN must be present

MethodRef:

      MethodHeader

      METHODREF MethodHeader

      CALL MethodHeader

MethodDef:

      MethodHeader LBRACE [ RefBlock ] RBRACE

      METHOD MethodHeader

      FUNC MethodHeader

A.3.8 Class Fields

FieldHeader:

      [Type] QualIdent DOT DollarIdent

      [Type] QualIdent SCOPE DollarIdent

FieldRef:

      FieldHeader

      FIELDREF FieldHeader

      FIELDREF QualIdent

      FIELDREF ScopedMember

FieldDef:

      FieldHeader LBRACE RBRACE

      FIELD FieldHeader

      FIELD QualIdent

      FIELD ScopedMember

A.3.9 Variables

Variable:

      [VAR]  [Type]  DollarIdent   // int $x

      VAR [Type]  Ident               // var int x

A.3.10 List of References

This provides a way to specify multiple references. This is a very powerful feature of the Codase smart query system. Complex search terms can be specified using this syntax. For example,

void main(string[]) { $x; println; } will search any main method that contains variable x and method call println.

Ref:

      ClassRef

      MethodRef

      FieldRef

      Variable

RefStmt:

      Ref  SEMICOLON

RefBlock:

      RefStmt { RefStmt }