Interface DocumentBuilder

updateBuildOptions

build

• build<T extends AstNode>(
      documents: LangiumDocument<T>[],
      options?: BuildOptions,
      cancelToken?: Cancellation.CancellationToken,
  ): Promise<void>

  Execute all necessary build steps for the given documents.

  Type Parameters

  • T extends AstNode

  Parameters

  • documents: LangiumDocument<T>[]

    Set of documents to be built.
  • Optionaloptions: BuildOptions

    Options for the document builder.
  • OptionalcancelToken: Cancellation.CancellationToken

    Indicates when to cancel the current operation.

  Returns Promise<void>

  Throws

  OperationCanceled if a user action occurs during execution

onBuildPhase

• onBuildPhase(
      targetState: DocumentState,
      callback: DocumentBuildListener,
  ): Disposable

  Notify the given callback when a set of documents has been built reaching the specified target state.

  Parameters

  • targetState: DocumentState
  • callback: DocumentBuildListener

  Returns Disposable

onDocumentPhase

• onDocumentPhase(
      targetState: DocumentState,
      callback: DocumentPhaseListener,
  ): Disposable

  Notify the specified callback when a document has been built reaching the specified target state. Unlike onBuildPhase the listener is called for every single document.

  There are two main advantages compared to onBuildPhase:

  1. If the build is cancelled, onDocumentPhase will still fire for documents that have reached a specific state. Meanwhile, onBuildPhase won't fire for that state.
  2. The DocumentBuilder ensures that all DocumentPhaseListener instances are called for a built document. Even if the build is cancelled before those listeners were called.

  Parameters

  • targetState: DocumentState
  • callback: DocumentPhaseListener

  Returns Disposable

onUpdate

• onUpdate(callback: DocumentUpdateListener): Disposable

  Notify the given callback when a document update was triggered, but before any document is rebuilt. Listeners to this event should not perform any long-running task.

  Parameters

  • callback: DocumentUpdateListener

  Returns Disposable

resetToState

• resetToState<T extends AstNode>(
      document: LangiumDocument<T>,
      state: DocumentState,
  ): void

  Reset the state of a document to the specified state, removing any derived data as needed.

  Type Parameters

  • T extends AstNode

  Parameters

  • document: LangiumDocument<T>

    The document to reset.
  • state: DocumentState

    The state to reset the document to.

  Returns void

update

• update(
      changed: URI[],
      deleted: URI[],
      cancelToken?: Cancellation.CancellationToken,
  ): Promise<void>

  This method is called when a document change is detected. It updates the state of all affected documents, including those with references to the changed ones, so they are rebuilt.

  Parameters

  • changed: URI[]

    URIs of changed or created documents
  • deleted: URI[]

    URIs of deleted documents
  • OptionalcancelToken: Cancellation.CancellationToken

    allows to cancel the current operation

  Returns Promise<void>

  Throws

  OperationCancelled if cancellation is detected during execution

waitUntil

• waitUntil(
      state: DocumentState,
      cancelToken?: Cancellation.CancellationToken,
  ): Promise<void>

  Wait until the workspace has reached the specified state for all documents.

  Parameters

  • state: DocumentState

    The desired state. The promise won't resolve until all documents have reached this state
  • OptionalcancelToken: Cancellation.CancellationToken

    Optionally allows to cancel the wait operation, disposing any listeners in the process

  Returns Promise<void>

  Throws

  OperationCancelled if cancellation has been requested before the state has been reached

• waitUntil(
      state: DocumentState,
      uri?: URI,
      cancelToken?: Cancellation.CancellationToken,
  ): Promise<undefined | URI>

  Wait until the document specified by the uri has reached the specified state.

  Parameters

  • state: DocumentState

    The desired state. The promise won't resolve until the document has reached this state.
  • Optionaluri: URI

    The specified URI that points to the document. If the URI does not exist, the promise will resolve once the workspace has reached the specified state.
  • OptionalcancelToken: Cancellation.CancellationToken

    Optionally allows to cancel the wait operation, disposing any listeners in the process.

  Returns Promise<undefined | URI>

  The URI of the document that has reached the desired state, or undefined if the document does not exist.

  Throws

  OperationCancelled if cancellation has been requested before the state has been reached