# sigmatch

Theme:

- Index

Search:
Group by:
Source Edit

This module implements the signature matching for resolving the call to overloaded procs, generic procs and operators.

This file implements features required for IDE support.

Due to Nim's nature and the fact that `system.nim` is always imported, there are lots of potential symbols. Furthermore thanks to templates and macros even context based analysis does not help much: In a context like `let x: |` where a type has to follow, that type might be constructed from a template like `extractField(MyObject, fieldName)`. We deal with this problem by smart sorting so that the likely symbols come first. This sorting is done this way:

- If there is a prefix (foo|), symbols starting with this prefix come first.
- If the prefix is part of the name (but the name doesn't start with it), these symbols come second.
- If we have a prefix, only symbols matching this prefix are returned and nothing else.
- If we have no prefix, consider the context. We currently distinguish between type and non-type contexts.
- Finally, sort matches by relevance. The relevance is determined by the number of usages, so `strutils.replace` comes before `strutils.wordWrap`.
- In any case, sorting also considers scoping information. Local variables get high priority.

# Imports

ast, astalgo, semdata, types, msgs, renderer, lookups, semtypinst, magicsys, idents, lexer, options, parampatterns, trees, linter, lineinfos, lowerings, modulegraphs, concepts, layeredtable, prefixmatches, suggestsymdb, wordrecg

# Types

    CandidateError = object
      sym*: PSym
      firstMismatch*: MismatchInfo
      diagnostics*: seq[string]
      enabled*: bool

  Source Edit

    CandidateErrors = seq[CandidateError]

  Source Edit

    MismatchInfo = object
      kind*: MismatchKind
      arg*: int
      formal*: PSym

  Source Edit

    MismatchKind = enum
      kUnknown, kAlreadyGiven, kUnknownNamedParam, kTypeMismatch, kVarNeeded,
      kMissingParam, kExtraArg, kPositionalAlreadyGiven, kGenericParamTypeMismatch,
      kMissingGenericParam, kExtraGenericParam

  Source Edit

    TCandidate = object
      c*: PContext
      exactMatches*: int
      state*: TCandidateState
      callee*: PType
      calleeSym*: PSym
      calleeScope*: int
      call*: PNode
      bindings*: LayeredIdTable
      magic*: TMagic
      matchedErrorType*: bool
      genericConverter*: bool
      coerceDistincts*: bool
      typedescMatched*: bool
      isNoCall*: bool
      diagnostics*: seq[string]
      firstMismatch*: MismatchInfo
      diagnosticsEnabled*: bool
      newlyTypedOperands*: seq[int] ## indexes of arguments that are newly typechecked in this match
                                    ## used for type bound op additions

  Source Edit

    TCandidateState = enum
      csEmpty, csMatch, csNoMatch

  Source Edit

    TCheckPointResult = enum
      cpNone, cpFuzzy, cpExact

  Source Edit

    TTypeRelFlag = enum
      trDontBind, trNoCovariance, trBindGenericParam, trIsOutParam, trCheckGeneric

  Source Edit

    TTypeRelFlags = set[TTypeRelFlag]

  Source Edit

# Procs

    proc `$`(suggest: Suggest): string {....raises: [], tags: [], forbids: [].}

  Source Edit

    proc `$`(suggest: SuggestInlayHint): string {....raises: [], tags: [], forbids: [].}

  Source Edit

    proc argtypeMatches(c: PContext; f, a: PType; fromHlo = false): bool {....raises: [
        Exception, KeyError, ValueError, OSError, IOError, ERecoverableError], tags: [
        RootEffect, ReadDirEffect, WriteIOEffect, ReadIOEffect, ReadEnvEffect],
        forbids: [].}

  Source Edit

    proc cmpCandidates(a, b: TCandidate; isFormal = true): int {.
        ...raises: [Exception], tags: [RootEffect], forbids: [].}

  Source Edit

    proc cmpTypes(c: PContext; f, a: PType): TTypeRelation {....raises: [KeyError,
        Exception, ValueError, OSError, IOError, ERecoverableError], tags: [
        RootEffect, ReadDirEffect, WriteIOEffect, ReadIOEffect, ReadEnvEffect],
        forbids: [].}

  Source Edit

    proc describeArg(c: PContext; n: PNode; i: int; startIdx = 1;
                     prefer = preferName): string {.
        ...raises: [Exception, KeyError, ValueError], tags: [RootEffect], forbids: [].}

  Source Edit

    proc describeArgs(c: PContext; n: PNode; startIdx = 1; prefer = preferName): string {.
        ...raises: [Exception, KeyError, ValueError], tags: [RootEffect], forbids: [].}

  Source Edit

    proc fieldVisible(c: PContext; f: PSym): bool {.inline, ...raises: [], tags: [],
        forbids: [].}

  Source Edit

    proc inCheckpoint(current, trackPos: TLineInfo): TCheckPointResult {....raises: [],
        tags: [], forbids: [].}

  Source Edit

    proc inferStaticParam(c: var TCandidate; lhs: PNode; rhs: BiggestInt): bool {.
        ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc initCandidate(ctx: PContext; callee: PSym; binding: PNode;
                       calleeScope = -1; diagnosticsEnabled = false): TCandidate {.
        ...raises: [Exception, KeyError], tags: [RootEffect], forbids: [].}

  Source Edit

    proc initCandidate(ctx: PContext; callee: PType): TCandidate {....raises: [],
        tags: [], forbids: [].}

  Source Edit

    proc instTypeBoundOp(c: PContext; dc: PSym; t: PType; info: TLineInfo;
                         op: TTypeAttachedOp; col: int): PSym {....raises: [Exception,
        ValueError, OSError, KeyError, IOError, ERecoverableError], tags: [
        RootEffect, ReadDirEffect, WriteIOEffect, ReadIOEffect, ReadEnvEffect],
        forbids: [].}

  Source Edit

    proc isTracked(current, trackPos: TinyLineInfo; tokenLen: int): bool {.
        ...raises: [], tags: [], forbids: [].}

  Source Edit

    proc isTracked(current, trackPos: TLineInfo; tokenLen: int): bool {....raises: [],
        tags: [], forbids: [].}

  Source Edit

    proc markOwnerModuleAsUsed(c: PContext; s: PSym) {....raises: [], tags: [],
        forbids: [].}

  Source Edit

    proc markUsed(c: PContext; info: TLineInfo; s: PSym; checkStyle = true;
                  isGenericInstance = false) {....raises: [Exception, ValueError,
        OSError, KeyError, IOError, ERecoverableError], tags: [RootEffect,
        ReadDirEffect, WriteIOEffect, ReadIOEffect, ReadEnvEffect], forbids: [].}

  Source Edit

    proc matches(c: PContext; n, nOrig: PNode; m: var TCandidate) {....raises: [
        KeyError, ValueError, OSError, Exception, IOError, ERecoverableError], tags: [
        ReadDirEffect, RootEffect, WriteIOEffect, ReadIOEffect, ReadEnvEffect],
        forbids: [].}

  Source Edit

    proc matchGenericParams(m: var TCandidate; binding: PNode; callee: PSym) {.
        ...raises: [Exception], tags: [RootEffect], forbids: [].}

  matches explicit generic instantiation `binding` against generic params of proc symbol `callee` state is set to `csMatch` if all generic params match, `csEmpty` if implicit generic parameters are missing (matches but cannot instantiate), `csNoMatch` if a constraint fails or param count doesn't match Source Edit

    proc matchUserTypeClass(m: var TCandidate; ff, a: PType): PType {....raises: [
        Exception, ValueError, OSError, KeyError, IOError, ERecoverableError], tags: [
        RootEffect, ReadDirEffect, WriteIOEffect, ReadIOEffect, ReadEnvEffect],
        forbids: [].}

  Source Edit

    proc newCandidate(ctx: PContext; callee: PSym; binding: PNode; calleeScope = -1): TCandidate {.
        ...raises: [Exception, KeyError], tags: [RootEffect], forbids: [].}

  Source Edit

    proc newCandidate(ctx: PContext; callee: PType): TCandidate {....raises: [],
        tags: [], forbids: [].}

  Source Edit

    proc paramTypesMatch(m: var TCandidate; f, a: PType; arg, argOrig: PNode): PNode {....raises: [
        Exception, KeyError, ValueError, OSError, IOError, ERecoverableError], tags: [
        RootEffect, ReadDirEffect, WriteIOEffect, ReadIOEffect, ReadEnvEffect],
        forbids: [].}

  Source Edit

    proc partialMatch(c: PContext; n, nOrig: PNode; m: var TCandidate) {....raises: [
        KeyError, ValueError, OSError, Exception, IOError, ERecoverableError], tags: [
        ReadDirEffect, RootEffect, WriteIOEffect, ReadIOEffect, ReadEnvEffect],
        forbids: [].}

  Source Edit

    proc safeSemExpr(c: PContext; n: PNode): PNode {....raises: [Exception],
        tags: [RootEffect], forbids: [].}

  Source Edit

    proc suggestDecl(c: PContext; n: PNode; s: PSym) {....raises: [ESuggestDone,
        Exception, KeyError, ValueError, OSError, IOError, ERecoverableError], tags: [
        RootEffect, ReadIOEffect, ReadDirEffect, WriteIOEffect, ReadEnvEffect],
        forbids: [].}

  Source Edit

    proc suggestEnum(c: PContext; n: PNode; t: PType) {.
        ...raises: [Exception, KeyError, ValueError, IOError, ESuggestDone],
        tags: [RootEffect, ReadIOEffect, WriteIOEffect], forbids: [].}

  Source Edit

    proc suggestExpr(c: PContext; n: PNode) {....raises: [Exception, KeyError,
        ValueError, OSError, IOError, ERecoverableError, ESuggestDone], tags: [
        RootEffect, ReadIOEffect, ReadDirEffect, WriteIOEffect, ReadEnvEffect],
        forbids: [].}

  Source Edit

    proc suggestExprNoCheck(c: PContext; n: PNode) {....raises: [Exception, KeyError,
        ValueError, OSError, IOError, ERecoverableError, ESuggestDone], tags: [
        RootEffect, ReadIOEffect, ReadDirEffect, WriteIOEffect, ReadEnvEffect],
        forbids: [].}

  Source Edit

    proc suggestPragmas(c: PContext; n: PNode) {.
        ...raises: [KeyError, ValueError, OSError, Exception, IOError, ESuggestDone],
        tags: [ReadDirEffect, RootEffect, ReadIOEffect, WriteIOEffect], forbids: [].}

  Suggests anything that might be a pragma
  - template that has {.pragma.}
  - macros
  - user pragmas
  Source Edit

    proc suggestResult(conf: ConfigRef; s: Suggest) {....raises: [Exception, IOError],
        tags: [RootEffect, WriteIOEffect], forbids: [].}

  Source Edit

    proc suggestSentinel(c: PContext) {....raises: [KeyError, ValueError, OSError,
        Exception, IOError], tags: [ReadDirEffect, RootEffect, ReadIOEffect,
                                    WriteIOEffect], forbids: [].}

  Source Edit

    proc suggestStmt(c: PContext; n: PNode) {....raises: [Exception, KeyError,
        ValueError, OSError, IOError, ERecoverableError, ESuggestDone], tags: [
        RootEffect, ReadIOEffect, ReadDirEffect, WriteIOEffect, ReadEnvEffect],
        forbids: [].}

  Source Edit

    proc suggestSym(g: ModuleGraph; info: TLineInfo; s: PSym; usageSym: var PSym;
                    isDecl = true; isGenericInstance = false) {.inline, ...raises: [],
        tags: [], forbids: [].}

  misnamed: should be 'symDeclared' Source Edit

    proc suggestToSuggestInlayExceptionHintLeft(sug: Suggest;
        propagatedExceptions: seq[PType]): SuggestInlayHint {.
        ...raises: [Exception, KeyError, ValueError], tags: [RootEffect], forbids: [].}

  Source Edit

    proc suggestToSuggestInlayExceptionHintRight(sug: Suggest;
        propagatedExceptions: seq[PType]): SuggestInlayHint {.
        ...raises: [Exception, KeyError, ValueError], tags: [RootEffect], forbids: [].}

  Source Edit

    proc suggestToSuggestInlayTypeHint(sug: Suggest): SuggestInlayHint {....raises: [],
        tags: [], forbids: [].}

  Source Edit

    proc symToSuggest(g: ModuleGraph; s: PSym; isLocal: bool; section: IdeCmd;
                      info: TLineInfo; quality: range[0 .. 100];
                      prefix: PrefixMatch; inTypeContext: bool; scope: int;
                      useSuppliedInfo = false; endLine: uint16 = 0; endCol = 0;
                      extractDocs = true): Suggest {.
        ...raises: [Exception, KeyError, ValueError], tags: [RootEffect, ReadIOEffect],
        forbids: [].}

  Source Edit

    proc typeRel(c: var TCandidate; f, aOrig: PType; flags: TTypeRelFlags = {}): TTypeRelation {....raises: [
        KeyError, Exception, ValueError, OSError, IOError, ERecoverableError], tags: [
        RootEffect, ReadDirEffect, WriteIOEffect, ReadIOEffect, ReadEnvEffect],
        forbids: [].}

  Source Edit

    proc writeMatches(c: TCandidate) {....raises: [ValueError, OSError, KeyError],
                                       tags: [RootEffect, ReadDirEffect],
                                       forbids: [].}

  Source Edit

# Templates

    template trySuggestModuleNames(c: PContext; n: PNode)

  Source Edit

    template trySuggestPragmas(c: PContext; n: PNode)

  Runs suggestPragmas when compiling nimsuggest and we are querying the node Source Edit