library.kdl

// This module defines all of the types and methods available in the ql-grep
// implementation of CodeQL. The goal is that this file serves as both documentation
// and as a specification for the type checker in the query parser/planner.
//
// Each top-level node encodes the API for a single type
//
// Methods with no arguments omit the arguments block
//
// Primitives are a subset of CodeQL:
//   - int
//   - boolean
//   - string

type "File" {
    contains "Function"
    contains "Method"
    contains "Callable"
    contains "Import"
    method "getAnImport" type="Relational<Import>" tag="[tag:library:File:getAnImport]" requires="Imports" \
        docstring=r"Get an import or include directive in this `File`"
}

type "Import" {
    method "getName" type="string" tag="[tag:library:Import:getName]" \
        docstring=r"Get the name of the imported entity; this is a filename for an import or a (possibly qualified) module name"
}

type "Function" {
    contains "Parameter"
    contains "Call"
    method "getAParameter" type="Relational<Parameter>"  tag="[tag:library:Function:getAParameter]" \
        docstring=r"Return any parameter in the function signature; this is intended to be used in a relational context."
    method "getParameter" type="Parameter" status="Unimplemented" {
        parameter "index" type="int"
    }
    method "getType" type="Type" tag="[tag:library:Function:getType]" \
        docstring=r"Get the return type of the `Function`"
    method "getName" type="string" tag="[tag:library:Function:getName]"
    method "getACall" type="Relational<Call>"  tag="[tag:library:Function:getACall]" \
        docstring=r"Return a call expression in the body of this object"
    method "hasParseError" type="boolean" tag="[tag:library:Function:hasParseError]" \
        docstring=r"Returns True if the function contains a parse error"
    method "getFile" type="File" tag="[tag:library:Function:getFile]" \
        docstring=r"Returns the `File` containing this `Function`"
}

type "Method" {
    contains "Parameter"
    contains "Call"
    method "getAParameter" type="Relational<Parameter>" tag="[tag:library:Method:getAParameter]" \
        docstring=r"Return any parameter in the method signature; this is intended to be used in a relational context."
    method "getParameter" type="Parameter" status="Unimplemented" {
        parameter "index" type="int"
    }
    method "getType" type="Type" tag="[tag:library:Method:getType]" \
        docstring=r"Get the return type of the method"
    method "getName" type="string" tag="[tag:library:Method:getName]"
    method "getACall" type="Relational<Call>"  tag="[tag:library:Method:getACall]" \
        docstring=r"Return a call expression in the body of this object"
    method "hasParseError" type="boolean" tag="[tag:library:Method:hasParseError]" \
        docstring=r"Returns True if the method contains a parse error"
    method "getFile" type="File" tag="[tag:library:Method:getFile]" \
        docstring=r"Returns the `File` containing this `Method`"
}

type "Callable" {
    contains "Parameter"
    contains "Call"
    method "getAParameter" type="Relational<Parameter>" tag="[tag:library:Callable:getAParameter]" \
        docstring=r"Return any parameter in signature of the callable; this is intended to be used in a relational context."
    method "getParameter" type="Parameter" status="Unimplemented" {
        parameter "index" type="int"
    }
    method "getType" type="Type" tag="[tag:library:Callable:getType]" \
        docstring=r"Get the return type of the callable"
    method "getName" type="string" tag="[tag:library:Callable:getName]"
    method "getACall" type="Relational<Call>" tag="[tag:library:Callable:getACall]" \
        docstring=r"Return a call expression in the body of this object"
    method "hasParseError" type="boolean" tag="[tag:library:Callable:hasParseError]" \
        docstring=r"Returns True if the callable contains a parse error"
    method "getFile" type="File" tag="[tag:library:Callable:getFile]" \
        docstring=r"Returns the `File` containing this `Callable`"
}

// Parameters are *formal* parameters of function definitions/declarations
type "Parameter" {
    method "getType" type="Type" tag="[tag:library:Parameter:getType]" \
        docstring=r"Return the type of the parameter (`Any` if the language is untyped)."
    method "getName" type="string" tag="[tag:library:Parameter:getName]"
    method "getIndex" type="int" tag="[tag:library:Parameter:getIndex]" \
        docstring=r"Return the index of the parameter in the argument list"
}

type "Call" {
    contains "Expr"
    method "getArgument" type="Expr" tag="[tag:library:Call:getArgument]" {
        parameter "index" type="int"
    }
    method "getAnArgument" type="Expr" status="Unimplemented"
    method "getTarget" type="string" tag="[tag:library:Call:getTarget]" \
        docstring=r"Return the target of the call; this is a string because there is not necessarily a structured declaration available"
}

type "Expr" {
    method "isCompileTimeConstant" type="boolean" status="Unimplemented" \
        docstring=r"Returns `true` if the expression is a literal at compile time"
    method "isStringLiteral" type="boolean" tag="[tag:library:Expr:isStringLiteral]" \
        docstring=r"Returns `true` if the expression is a string literal"
}

type "Type" {
    method "getName" type="string" tag="[tag:library:Type:getName]"
}

type "Regex" {

}

type "string" {
    method "regexpMatch" type="boolean" tag="[tag:library:string:regexpMatch]" {
        parameter "regexp" type="Regex"
    }
}