Giters

legionaryu / vscode-cerberus-support

VS Code extension for Cerberus X

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

This file was auto-generated with zdoccer.js 1.4.0

Index

original Markdown from src/.readme.md

VS Code extension for Cerberus X

VS Code extension for Cerberus X enables programming Cerberus X in Visual Studio Code. The goal of this extension is to provide basic and more sophisticated features necessary and useful for working with Cerberus X.

Involved Parties

VS Code extension for Cerberus X was created by Olivier Stuker inspired by Adamredwoods' Visual Studio Code extension for Cerberus Programming Language and Hezkore's BlitzMax Language Basics for Visual Studio Code.

POC: Olivier "Holzchopf" Stuker

License

See LICENSE.md

Testing the extension

From within VS Code, just hit F5 to start a testing instance with VS Code extension for Cerberus X loaded. Then load any .cxs file to activate the extension.

Automatic testing is not yet set up.

Building the extension

Run

vsce package

Needs vsce (see https://code.visualstudio.com/api/working-with-extensions/publishing-extension )

Code Scaffolding

This extension was initialised with Yeoman and VS Code Extension Generator.

Features are provided by singleton classes. To add features, create a new .ts file in src/features containing not more than the features' singleton class and - optionally, and these may even be outsourced - definitions strongly linked to that feature (like type definitions, enumerations, interfaces).

To keep the project folder tidy, we use the following structure:

src/              # entry point (extension.ts)
  assets/         # assets (to be compiled into the extension)
  extension/      # extension source
    features/     # features (everything that can be seen as a module)
    providers/    # providers
  test/           # test suite
syntaxes/         # Cerberus X syntax definition

Documentation

This project is documented using zdoccer.js - a script that creates the README.md from markdown files and Javadoc-documented source in the specified folder.

To document any feature of your project, preceed it with a block comment of the following form:

/**
 * markdown for your feature goes here
 */
<line of code to be documented>

Or a single line comment of the following form:

/** markdown goes here */
<line of code to be documented>

If <line of code to be documented> is not empty, it will be prepended to the markdown block.

To update the README.md, run zdoccer:

npx zdoccer src

Sourcecode Documentation

VS Code extension for Cerberus X is split into multiple singleton classes, grouping similar functionalities or features of same context.

transformed Javadoc from src/extension.ts

function activate(context: vscode.ExtensionContext)

This function is called when the extension is activated. See package.json > "activationEvents" for the definition of events that activate the extension.

Starts the extension, see CxExtension 🡵

function deactivate() {}

this method is called when your extension is deactivated

transformed Javadoc from src/extension/cerberusx.extension.ts

class CxExtension

Extension container

public static activate(context: vscode.ExtensionContext)

Checks the Cerberus X configuration and registers all handlers and providers.

  • param context — hosting vscode.ExtensionContext

transformed Javadoc from src/extension/features/builder/builder.feature.ts

class CxBuilder

Different Cerberus X builders

public static cerberusGetBuildFile(): string

returns currently active build file or empty string if not defined

public static buildHtml(): Promise<void>

Builds HTML5 game

  • returns — Promise resolving on success

public static build(file: string, args: string[]): Promise<void>

Generic build, invokes transcc

  • param file — path to file to build
  • param args — compiler flags
  • returns — Promise resolving on success

public static runHtml(): Promise<void>

Runs HTML5 game

  • returns — Promise resolving on success

transformed Javadoc from src/extension/features/child-process/child-process.feature.ts

class CxChildProcess

Child process helper

public static spawn(title: string, paths: {[name: string]: string}, command: string, args: string[] = []): Promise<void>

Spawns a new child process and outputs stdout and stderr data

  • param title — How the process is described in output
  • param paths — Paths to list, e.g. {transcc: 'path/there'}
  • param command — command to execute
  • param args — command arguments
  • returns — a promise resolving when the process finished

transformed Javadoc from src/extension/features/configuration/configuration.feature.ts

class CxConfiguration

Provides and checks configuration for Cerberus X

public static version: string|undefined

Cerberus X version

public static platform: string|undefined

platform (winnt, macos or linux)

public static transccPath: string|undefined

path to transcc executable

public static makedocsPath: string|undefined

path to makedocs executable

public static cserverPath: string|undefined

path to cserver executable

public static get(section: string): any

Returns Cerberus X configuration value from section

  • param section — key
  • returns — matching value

public static set(section: string, value: any, target: vscode.ConfigurationTarget = vscode.ConfigurationTarget.Workspace): Thenable<void>

Sets a Cerberus X configuration value. Use undefined to unset.

  • param section — key
  • param value — value
  • returns — Thenable<void> resolving when done

public static onConfigurationValid(callback: ()=>void): void

Defines functions to be called when configuration is valid

  • param callback — function to be called

transformed Javadoc from src/extension/features/cxlang/cxlang-semanter.feature.ts

public getDetailsText(): string

Returns the definitions following the identifier as pretty printed string

transformed Javadoc from src/extension/features/documentation/docdecl-html-transformer.ts

class DocDeclHtmlTransformer

Transformer for DocDecl 🡵 -> HTML

public static setWebview(webview: vscode.Webview)

Sets Webview, necessary for URI resolving

  • param webview — valid vscode.Webview

public static transform(decl: DocDecl): string

Transforms given DocDecl 🡵 to string of HTML (full page)

  • param decl — DocDecl to transform
  • returns — html string

transformed Javadoc from src/extension/features/documentation/docdecl.ts

class DocDecl

Any kind of Cerberus X declaration

public static getByUid(uid: string): DocDecl|null

Returns DocDecl by uid (must match exactly, always 6 digits)

  • param uid — 6 digit uid
  • returns — matching DocDecl or null

public getChild(ident: string): DocDecl|null

Returns child decl by ident

  • param ident — identifier to match
  • returns — matching DocDecl or null

public getTextOfChild(kind: string): string

Returns value of child of given kind

  • param kind — kind property that has to match
  • returns — string value of match

public getDocPath(): string

Absolute doc path for this decl

  • returns — doc path as string

public getUident(): string

full path (uident) for this decl (and cache, speeds things up)

  • returns — full path as string

transformed Javadoc from src/extension/features/documentation/documentation.feature.ts

class CxDocumentation

Cerberus X in-editor documentation

public static rootDecl: DocDecl

Root DocDecl

private static currentDecl: DocDecl

currently (navigated to) DocDecl

private static history: DocDecl[] = []

history of navigated DocDecl

private static historyRev: DocDecl[] = []

when going back, this is the stack of "forward" DocDecl

private static panel: vscode.WebviewPanel

panel

private static webview: vscode.Webview

webview (instance needed for navigating and stuff)

public static build(): Promise<void>

Invokes makedocs to build the docs

  • returns — Promise resolving when done

public static init(): void

Registers the feature and prepares components

public static loadDecls()

Loads declarations from docs/html/decls.json

public static canNavBack(): boolean

Whether navigating back is possible

public static canNavFwd(): boolean

Whether navigating forward is possible

transformed Javadoc from src/extension/providers/document-symbol.provider.ts

class CxDocumentSymbolProvider

Provides a vscode.DocumentSymbol tree for the outline

public provideDocumentSymbols( document: vscode.TextDocument, token: vscode.CancellationToken ): vscode.DocumentSymbol[]

Builds the tree. Invoked automatically by VS Code

  • param document — vscode.TextDocument to build the tree for
  • param token — vscode.CancellationToken
  • returns — vscode.DocumentSymbol[]

transformed Javadoc from src/extension/providers/on-type-formatting-edit.provider.ts

class CxOnTypeFormattingEditProvider

Provides a vscode.OnTypeFormattingEditProvider for real-time formatting

public static init(context: vscode.ExtensionContext)

Initializes provider

  • param context — vscode.ExtensionContext

public provideOnTypeFormattingEdits(document: vscode.TextDocument, position: vscode.Position, char: string, options: vscode.FormattingOptions, ctoken: vscode.CancellationToken): vscode.ProviderResult<vscode.TextEdit[]>

Provides on type formatting edits. Invoked automatically by VS Code

  • param document — current vscode.TextDocument
  • param position — vscode.Position after triggering
  • param char — triggering char as string
  • param options — vscode.FormattingOptions
  • param token — vscode.CancellationToken
  • returns — vscode.TextEdits to apply

About

VS Code extension for Cerberus X

License:MIT License

Languages

Language:TypeScript 100.0%