# This file describes custom XPath functions per language
# This is rendered using _includes/custom/xpath_fun_doc.html

aliases:
  - &qname_param
    name: javaQualifiedName
    type: "xs:string"
    description: "The qualified name of a Java class, possibly with pairs of brackets to indicate an array type.
                  Can also be a primitive type name."
  - &node_param
    name: element
    type: "xs:element"
    description: "Any element node"
  - &needs_typenode "The context node must be a {% jdoc jast::TypeNode %}"
  - &coord_fun_note |
      The function is not context-dependent, but takes a node as its first parameter.
      The function is only available in XPath 2.0.
  - &needs_node_ctx "The requires the context node to be an element"

langs:
  - name: "All languages"
    ns: "pmd"
    header: "Functions available to all languages are in the namespace `pmd`."
    funs:
      - name: fileName
        returnType: "xs:string"
        shortDescription: "Returns the simple name of the current file"
        description: |
          Returns the current simple file name, without path but including the extension.
          This can be used to write rules that check file naming conventions.

        since: 6.38.0
        notes: *needs_node_ctx
        examples:
          - code: "//b[pmd:fileName() = 'Foo.xml']"
            outcome: "Matches any `<b>` tags in files called `Foo.xml`."

      - name: startLine
        returnType: "xs:int"
        parameters:
          - *node_param
        shortDescription: "Returns the start line of the given node"
        description: |
          Returns the line where the node starts in the source file.
          Line numbers are 1-based.

        since: 6.44.0
        notes: *coord_fun_note
        examples:
          - code: "//b[pmd:startLine(.) > 5]"
            outcome: "Matches any `<b>` node which starts after the fifth line."

      - name: endLine
        returnType: "xs:int"
        parameters:
          - *node_param
        shortDescription: "Returns the end line of the given node"
        description: |
          Returns the line where the node ends in the source file.
          Line numbers are 1-based.

        since: 6.44.0
        notes: *coord_fun_note
        examples:
          - code: "//b[pmd:endLine(.) == pmd:startLine(.)]"
            outcome: "Matches any `<b>` node which doesn't span more than one line."

      - name: startColumn
        returnType: "xs:int"
        parameters:
          - *node_param
        shortDescription: "Returns the start column of the given node (inclusive)"
        description: |
          Returns the column number where the node starts in the source file.
          Column numbers are 1-based. The start column is inclusive.

        since: 6.44.0
        notes: *coord_fun_note
        examples:
          - code: "//b[pmd:startColumn(.) = 1]"
            outcome: "Matches any `<b>` node which starts on the first column of a line"

      - name: endColumn
        returnType: "xs:int"
        parameters:
          - *node_param
        shortDescription: "Returns the end column of the given node (exclusive)"
        description: |
          Returns the column number where the node ends in the source file.
          Column numbers are 1-based. The end column is exclusive.

        since: 6.44.0
        notes: *coord_fun_note
        examples:
          - code: "//b[pmd:startLine(.) = pmd:endLine(.) and pmd:endColumn(.) - pmd:startColumn(.) = 1]"
            outcome: "Matches any `<b>` node which spans exactly one character"

  - name: "Java"
    ns: "pmd-java"
    funs:
      - name: typeIs
        returnType: "xs:boolean"
        shortDescription: "Tests a node's static type"
        description: "Returns true if the context node's static Java type is a subtype of the given type.
                      This tests for the resolved type of the Java construct, not the type of the AST node.
                      For example, the AST node for a literal (e.g. `5d`) has type ASTLiteral, however this
                      function will compare the type of the literal (eg here, `double`) against the argument."
        notes: *needs_typenode
        parameters:
          - *qname_param
        examples:
          - code: '//FormalParameter[pmd-java:typeIs("java.lang.String[]")]'
            outcome: "Matches formal parameters of type `String[]` (including vararg parameters)"
          - code: '//VariableDeclaratorId[pmd-java:typeIs("java.lang.List")]'
            outcome: "Matches variable declarators of type `List` or any of its subtypes (including e.g. `ArrayList`)"


      - name: typeIsExactly
        returnType: "xs:boolean"
        shortDescription: "Tests a node's static type, ignoring subtypes"
        description: "Returns true if the context node's static type is exactly the given type.
                      In particular, returns false if the context node's type is
                      a subtype of the given type."
        notes: *needs_typenode
        parameters:
          - *qname_param
        examples:
          - code: '//VariableDeclaratorId[pmd-java:typeIsExactly("java.lang.List")]'
            outcome: "Matches variable declarators of type `List` (but not e.g. `ArrayList`)"


      - name: metric
        returnType: "xs:decimal?"
        shortDescription: "Computes and returns the value of a metric"
        description: "Returns the value of the metric as evaluated on the context node"
        notes: "The context node must be a {% jdoc jast::ASTAnyTypeDeclaration %} or a {% jdoc jast::MethodLikeNode %}"
        parameters:
          - name: "metricKey"
            type: "xs:string"
            description: "The name of an enum constant in {% jdoc jmx::api.JavaOperationMetricKey %} or {% jdoc jmx::api.JavaClassMetricKey %}"