blockly 12.4.0 → 12.5.0

package/core/generator.ts

@@ -1,611 +0,0 @@
-/**
- * @license
- * Copyright 2012 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-/**
- * Utility functions for generating executable code from
- * Blockly code.
- *
- * @class
- */
-// Former goog.module ID: Blockly.CodeGenerator
-
-import type {Block} from './block.js';
-import * as common from './common.js';
-import {Names, NameType} from './names.js';
-import type {Workspace} from './workspace.js';
-
-/**
- * Deprecated, no-longer used type declaration for per-block-type generator
- * functions.
- *
- * @deprecated
- * @see {@link https://developers.google.com/blockly/guides/create-custom-blocks/generating-code}
- * @param block The Block instance to generate code for.
- * @param generator The CodeGenerator calling the function.
- * @returns A string containing the generated code (for statement blocks),
- *     or a [code, precedence] tuple (for value/expression blocks), or
- *     null if no code should be emitted for block.
- */
-export type BlockGenerator = (
-  block: Block,
-  generator: CodeGenerator,
-) => [string, number] | string | null;
-
-/**
- * Class for a code generator that translates the blocks into a language.
- */
-export class CodeGenerator {
-  name_: string;
-
-  /**
-   * A dictionary of block generator functions, keyed by block type.
-   * Each block generator function takes two parameters:
-   *
-   * - the Block to generate code for, and
-   * - the calling CodeGenerator (or subclass) instance, so the
-   *   function can call methods defined below (e.g. blockToCode) or
-   *   on the relevant subclass (e.g. JavascripGenerator),
-   *
-   * and returns:
-   *
-   * - a [code, precedence] tuple (for value/expression blocks), or
-   * - a string containing the generated code (for statement blocks), or
-   * - null if no code should be emitted for block.
-   */
-  forBlock: Record<
-    string,
-    (block: Block, generator: this) => [string, number] | string | null
-  > = Object.create(null);
-
-  /**
-   * This is used as a placeholder in functions defined using
-   * CodeGenerator.provideFunction_.  It must not be legal code that could
-   * legitimately appear in a function definition (or comment), and it must
-   * not confuse the regular expression parser.
-   */
-  FUNCTION_NAME_PLACEHOLDER_ = '{leCUI8hutHZI4480Dc}';
-  FUNCTION_NAME_PLACEHOLDER_REGEXP_: RegExp;
-
-  /**
-   * Arbitrary code to inject into locations that risk causing infinite loops.
-   * Any instances of '%1' will be replaced by the block ID that failed.
-   * E.g. `  checkTimeout(%1);\n`
-   */
-  INFINITE_LOOP_TRAP: string | null = null;
-
-  /**
-   * Arbitrary code to inject before every statement.
-   * Any instances of '%1' will be replaced by the block ID of the statement.
-   * E.g. `highlight(%1);\n`
-   */
-  STATEMENT_PREFIX: string | null = null;
-
-  /**
-   * Arbitrary code to inject after every statement.
-   * Any instances of '%1' will be replaced by the block ID of the statement.
-   * E.g. `highlight(%1);\n`
-   */
-  STATEMENT_SUFFIX: string | null = null;
-
-  /**
-   * The method of indenting.  Defaults to two spaces, but language generators
-   * may override this to increase indent or change to tabs.
-   */
-  INDENT = '  ';
-
-  /**
-   * Maximum length for a comment before wrapping.  Does not account for
-   * indenting level.
-   */
-  COMMENT_WRAP = 60;
-
-  /** List of outer-inner pairings that do NOT require parentheses. */
-  ORDER_OVERRIDES: number[][] = [];
-
-  /**
-   * Whether the init method has been called.
-   * Generators that set this flag to false after creation and true in init
-   * will cause blockToCode to emit a warning if the generator has not been
-   * initialized. If this flag is untouched, it will have no effect.
-   */
-  isInitialized: boolean | null = null;
-
-  /** Comma-separated list of reserved words. */
-  protected RESERVED_WORDS_ = '';
-
-  /** A dictionary of definitions to be printed before the code. */
-  protected definitions_: {[key: string]: string} = Object.create(null);
-
-  /**
-   * A dictionary mapping desired function names in definitions_ to actual
-   * function names (to avoid collisions with user functions).
-   */
-  protected functionNames_: {[key: string]: string} = Object.create(null);
-
-  /** A database of variable and procedure names. */
-  nameDB_?: Names = undefined;
-
-  /** @param name Language name of this generator. */
-  constructor(name: string) {
-    this.name_ = name;
-
-    this.FUNCTION_NAME_PLACEHOLDER_REGEXP_ = new RegExp(
-      this.FUNCTION_NAME_PLACEHOLDER_,
-      'g',
-    );
-  }
-
-  /**
-   * Generate code for all blocks in the workspace to the specified language.
-   *
-   * @param workspace Workspace to generate code from.
-   * @returns Generated code.
-   */
-  workspaceToCode(workspace?: Workspace): string {
-    if (!workspace) {
-      // Backwards compatibility from before there could be multiple workspaces.
-      console.warn(
-        'No workspace specified in workspaceToCode call.  Guessing.',
-      );
-      workspace = common.getMainWorkspace();
-    }
-    const code = [];
-    this.init(workspace);
-    const blocks = workspace.getTopBlocks(true);
-    for (let i = 0, block; (block = blocks[i]); i++) {
-      let line = this.blockToCode(block);
-      if (Array.isArray(line)) {
-        // Value blocks return tuples of code and operator order.
-        // Top-level blocks don't care about operator order.
-        line = line[0];
-      }
-      if (line) {
-        if (block.outputConnection) {
-          // This block is a naked value.  Ask the language's code generator if
-          // it wants to append a semicolon, or something.
-          line = this.scrubNakedValue(line);
-          if (this.STATEMENT_PREFIX && !block.suppressPrefixSuffix) {
-            line = this.injectId(this.STATEMENT_PREFIX, block) + line;
-          }
-          if (this.STATEMENT_SUFFIX && !block.suppressPrefixSuffix) {
-            line = line + this.injectId(this.STATEMENT_SUFFIX, block);
-          }
-        }
-        code.push(line);
-      }
-    }
-    // Blank line between each section.
-    let codeString = code.join('\n');
-    codeString = this.finish(codeString);
-    // Final scrubbing of whitespace.
-    codeString = codeString.replace(/^\s+\n/, '');
-    codeString = codeString.replace(/\n\s+$/, '\n');
-    codeString = codeString.replace(/[ \t]+\n/g, '\n');
-    return codeString;
-  }
-
-  /**
-   * Prepend a common prefix onto each line of code.
-   * Intended for indenting code or adding comment markers.
-   *
-   * @param text The lines of code.
-   * @param prefix The common prefix.
-   * @returns The prefixed lines of code.
-   */
-  prefixLines(text: string, prefix: string): string {
-    return prefix + text.replace(/(?!\n$)\n/g, '\n' + prefix);
-  }
-
-  /**
-   * Recursively spider a tree of blocks, returning all their comments.
-   *
-   * @param block The block from which to start spidering.
-   * @returns Concatenated list of comments.
-   */
-  allNestedComments(block: Block): string {
-    const comments = [];
-    const blocks = block.getDescendants(true);
-    for (let i = 0; i < blocks.length; i++) {
-      const comment = blocks[i].getCommentText();
-      if (comment) {
-        comments.push(comment);
-      }
-    }
-    // Append an empty string to create a trailing line break when joined.
-    if (comments.length) {
-      comments.push('');
-    }
-    return comments.join('\n');
-  }
-
-  /**
-   * Generate code for the specified block (and attached blocks).
-   * The generator must be initialized before calling this function.
-   *
-   * @param block The block to generate code for.
-   * @param opt_thisOnly True to generate code for only this statement.
-   * @returns For statement blocks, the generated code.
-   *     For value blocks, an array containing the generated code and an
-   * operator order value.  Returns '' if block is null.
-   */
-  blockToCode(
-    block: Block | null,
-    opt_thisOnly?: boolean,
-  ): string | [string, number] {
-    if (this.isInitialized === false) {
-      console.warn(
-        'CodeGenerator init was not called before blockToCode was called.',
-      );
-    }
-    if (!block) {
-      return '';
-    }
-    if (!block.isEnabled()) {
-      // Skip past this block if it is disabled.
-      return opt_thisOnly ? '' : this.blockToCode(block.getNextBlock());
-    }
-    if (block.isInsertionMarker()) {
-      // Skip past insertion markers.
-      return opt_thisOnly ? '' : this.blockToCode(block.getChildren(false)[0]);
-    }
-
-    // Look up block generator function in dictionary.
-    const func = this.forBlock[block.type];
-    if (typeof func !== 'function') {
-      throw Error(
-        `${this.name_} generator does not know how to generate code ` +
-          `for block type "${block.type}".`,
-      );
-    }
-    // First argument to func.call is the value of 'this' in the generator.
-    // Prior to 24 September 2013 'this' was the only way to access the block.
-    // The current preferred method of accessing the block is through the second
-    // argument to func.call, which becomes the first parameter to the
-    // generator.
-    let code = func.call(block, block, this);
-    if (Array.isArray(code)) {
-      // Value blocks return tuples of code and operator order.
-      if (!block.outputConnection) {
-        throw TypeError('Expecting string from statement block: ' + block.type);
-      }
-      return [this.scrub_(block, code[0], opt_thisOnly), code[1]];
-    } else if (typeof code === 'string') {
-      if (this.STATEMENT_PREFIX && !block.suppressPrefixSuffix) {
-        code = this.injectId(this.STATEMENT_PREFIX, block) + code;
-      }
-      if (this.STATEMENT_SUFFIX && !block.suppressPrefixSuffix) {
-        code = code + this.injectId(this.STATEMENT_SUFFIX, block);
-      }
-      return this.scrub_(block, code, opt_thisOnly);
-    } else if (code === null) {
-      // Block has handled code generation itself.
-      return '';
-    }
-    throw SyntaxError('Invalid code generated: ' + code);
-  }
-
-  /**
-   * Generate code representing the specified value input.
-   *
-   * @param block The block containing the input.
-   * @param name The name of the input.
-   * @param outerOrder The maximum binding strength (minimum order value) of any
-   *     operators adjacent to "block".
-   * @returns Generated code or '' if no blocks are connected.
-   * @throws ReferenceError if the specified input does not exist.
-   */
-  valueToCode(block: Block, name: string, outerOrder: number): string {
-    if (isNaN(outerOrder)) {
-      throw TypeError('Expecting valid order from block: ' + block.type);
-    }
-    const targetBlock = block.getInputTargetBlock(name);
-    if (!targetBlock && !block.getInput(name)) {
-      throw ReferenceError(`Input "${name}" doesn't exist on "${block.type}"`);
-    }
-    if (!targetBlock) {
-      return '';
-    }
-    const tuple = this.blockToCode(targetBlock);
-    if (tuple === '') {
-      // Disabled block.
-      return '';
-    }
-    // Value blocks must return code and order of operations info.
-    // Statement blocks must only return code.
-    if (!Array.isArray(tuple)) {
-      throw TypeError(
-        `Expecting tuple from value block: ${targetBlock.type} See ` +
-          `developers.google.com/blockly/guides/create-custom-blocks/generating-code ` +
-          `for more information`,
-      );
-    }
-    let code = tuple[0];
-    const innerOrder = tuple[1];
-    if (isNaN(innerOrder)) {
-      throw TypeError(
-        'Expecting valid order from value block: ' + targetBlock.type,
-      );
-    }
-    if (!code) {
-      return '';
-    }
-
-    // Add parentheses if needed.
-    let parensNeeded = false;
-    const outerOrderClass = Math.floor(outerOrder);
-    const innerOrderClass = Math.floor(innerOrder);
-    if (outerOrderClass <= innerOrderClass) {
-      if (
-        outerOrderClass === innerOrderClass &&
-        (outerOrderClass === 0 || outerOrderClass === 99)
-      ) {
-        // Don't generate parens around NONE-NONE and ATOMIC-ATOMIC pairs.
-        // 0 is the atomic order, 99 is the none order.  No parentheses needed.
-        // In all known languages multiple such code blocks are not order
-        // sensitive.  In fact in Python ('a' 'b') 'c' would fail.
-      } else {
-        // The operators outside this code are stronger than the operators
-        // inside this code.  To prevent the code from being pulled apart,
-        // wrap the code in parentheses.
-        parensNeeded = true;
-        // Check for special exceptions.
-        for (let i = 0; i < this.ORDER_OVERRIDES.length; i++) {
-          if (
-            this.ORDER_OVERRIDES[i][0] === outerOrder &&
-            this.ORDER_OVERRIDES[i][1] === innerOrder
-          ) {
-            parensNeeded = false;
-            break;
-          }
-        }
-      }
-    }
-    if (parensNeeded) {
-      // Technically, this should be handled on a language-by-language basis.
-      // However all known (sane) languages use parentheses for grouping.
-      code = '(' + code + ')';
-    }
-    return code;
-  }
-
-  /**
-   * Generate a code string representing the blocks attached to the named
-   * statement input. Indent the code.
-   * This is mainly used in generators. When trying to generate code to evaluate
-   * look at using workspaceToCode or blockToCode.
-   *
-   * @param block The block containing the input.
-   * @param name The name of the input.
-   * @returns Generated code or '' if no blocks are connected.
-   * @throws ReferenceError if the specified input does not exist.
-   */
-  statementToCode(block: Block, name: string): string {
-    const targetBlock = block.getInputTargetBlock(name);
-    if (!targetBlock && !block.getInput(name)) {
-      throw ReferenceError(`Input "${name}" doesn't exist on "${block.type}"`);
-    }
-    let code = this.blockToCode(targetBlock);
-    // Value blocks must return code and order of operations info.
-    // Statement blocks must only return code.
-    if (typeof code !== 'string') {
-      throw TypeError(
-        'Expecting code from statement block: ' +
-          (targetBlock && targetBlock.type),
-      );
-    }
-    if (code) {
-      code = this.prefixLines(code, this.INDENT);
-    }
-    return code;
-  }
-
-  /**
-   * Add an infinite loop trap to the contents of a loop.
-   * Add statement suffix at the start of the loop block (right after the loop
-   * statement executes), and a statement prefix to the end of the loop block
-   * (right before the loop statement executes).
-   *
-   * @param branch Code for loop contents.
-   * @param block Enclosing block.
-   * @returns Loop contents, with infinite loop trap added.
-   */
-  addLoopTrap(branch: string, block: Block): string {
-    if (this.INFINITE_LOOP_TRAP) {
-      branch =
-        this.prefixLines(
-          this.injectId(this.INFINITE_LOOP_TRAP, block),
-          this.INDENT,
-        ) + branch;
-    }
-    if (this.STATEMENT_SUFFIX && !block.suppressPrefixSuffix) {
-      branch =
-        this.prefixLines(
-          this.injectId(this.STATEMENT_SUFFIX, block),
-          this.INDENT,
-        ) + branch;
-    }
-    if (this.STATEMENT_PREFIX && !block.suppressPrefixSuffix) {
-      branch =
-        branch +
-        this.prefixLines(
-          this.injectId(this.STATEMENT_PREFIX, block),
-          this.INDENT,
-        );
-    }
-    return branch;
-  }
-
-  /**
-   * Inject a block ID into a message to replace '%1'.
-   * Used for STATEMENT_PREFIX, STATEMENT_SUFFIX, and INFINITE_LOOP_TRAP.
-   *
-   * @param msg Code snippet with '%1'.
-   * @param block Block which has an ID.
-   * @returns Code snippet with ID.
-   */
-  injectId(msg: string, block: Block): string {
-    const id = block.id.replace(/\$/g, '$$$$'); // Issue 251.
-    return msg.replace(/%1/g, "'" + id + "'");
-  }
-
-  /**
-   * Add one or more words to the list of reserved words for this language.
-   *
-   * @param words Comma-separated list of words to add to the list.
-   *     No spaces.  Duplicates are ok.
-   */
-  addReservedWords(words: string) {
-    this.RESERVED_WORDS_ += words + ',';
-  }
-
-  /**
-   * Define a developer-defined function (not a user-defined procedure) to be
-   * included in the generated code.  Used for creating private helper
-   * functions. The first time this is called with a given desiredName, the code
-   * is saved and an actual name is generated.  Subsequent calls with the same
-   * desiredName have no effect but have the same return value.
-   *
-   * It is up to the caller to make sure the same desiredName is not
-   * used for different helper functions (e.g. use "colourRandom" and
-   * "listRandom", not "random").  There is no danger of colliding with reserved
-   * words, or user-defined variable or procedure names.
-   *
-   * The code gets output when CodeGenerator.finish() is called.
-   *
-   * @param desiredName The desired name of the function (e.g. mathIsPrime).
-   * @param code A list of statements or one multi-line code string.  Use '  '
-   *     for indents (they will be replaced).
-   * @returns The actual name of the new function.  This may differ from
-   *     desiredName if the former has already been taken by the user.
-   */
-  provideFunction_(desiredName: string, code: string[] | string): string {
-    if (!this.definitions_[desiredName]) {
-      const functionName = this.nameDB_!.getDistinctName(
-        desiredName,
-        NameType.PROCEDURE,
-      );
-      this.functionNames_[desiredName] = functionName;
-      if (Array.isArray(code)) {
-        code = code.join('\n');
-      }
-      let codeText = code
-        .trim()
-        .replace(this.FUNCTION_NAME_PLACEHOLDER_REGEXP_, functionName);
-      // Change all '  ' indents into the desired indent.
-      // To avoid an infinite loop of replacements, change all indents to '\0'
-      // character first, then replace them all with the indent.
-      // We are assuming that no provided functions contain a literal null char.
-      let oldCodeText;
-      while (oldCodeText !== codeText) {
-        oldCodeText = codeText;
-        codeText = codeText.replace(/^(( {2})*) {2}/gm, '$1\0');
-      }
-      codeText = codeText.replace(/\0/g, this.INDENT);
-      this.definitions_[desiredName] = codeText;
-    }
-    return this.functionNames_[desiredName];
-  }
-
-  /**
-   * Gets a unique, legal name for a user-defined variable.
-   * Before calling this method, the `nameDB_` property of the class
-   * must have been initialized already. This is typically done in
-   * the `init` function of the code generator class.
-   *
-   * @param nameOrId The ID of the variable to get a name for,
-   *    or the proposed name for a variable not associated with an id.
-   * @returns A unique, legal name for the variable.
-   */
-  getVariableName(nameOrId: string): string {
-    return this.getName(nameOrId, NameType.VARIABLE);
-  }
-
-  /**
-   * Gets a unique, legal name for a user-defined procedure.
-   * Before calling this method, the `nameDB_` property of the class
-   * must have been initialized already. This is typically done in
-   * the `init` function of the code generator class.
-   *
-   * @param name The proposed name for a procedure.
-   * @returns A unique, legal name for the procedure.
-   */
-  getProcedureName(name: string): string {
-    return this.getName(name, NameType.PROCEDURE);
-  }
-
-  private getName(nameOrId: string, type: NameType): string {
-    if (!this.nameDB_) {
-      throw new Error(
-        'Name database is not defined. You must initialize `nameDB_` in your generator class and call `init` first.',
-      );
-    }
-    return this.nameDB_.getName(nameOrId, type);
-  }
-
-  /**
-   * Hook for code to run before code generation starts.
-   * Subclasses may override this, e.g. to initialise the database of variable
-   * names.
-   *
-   * @param _workspace Workspace to generate code from.
-   */
-  init(_workspace: Workspace) {
-    // Optionally override
-    // Create a dictionary of definitions to be printed before the code.
-    this.definitions_ = Object.create(null);
-    // Create a dictionary mapping desired developer-defined function names in
-    // definitions_ to actual function names (to avoid collisions with
-    // user-defined procedures).
-    this.functionNames_ = Object.create(null);
-  }
-
-  /**
-   * Common tasks for generating code from blocks.  This is called from
-   * blockToCode and is called on every block, not just top level blocks.
-   * Subclasses may override this, e.g. to generate code for statements
-   * following the block, or to handle comments for the specified block and any
-   * connected value blocks.
-   *
-   * @param _block The current block.
-   * @param code The code created for this block.
-   * @param _opt_thisOnly True to generate code for only this statement.
-   * @returns Code with comments and subsequent blocks added.
-   */
-  scrub_(_block: Block, code: string, _opt_thisOnly?: boolean): string {
-    // Optionally override
-    return code;
-  }
-
-  /**
-   * Hook for code to run at end of code generation.
-   * Subclasses may override this, e.g. to prepend the generated code with
-   * import statements or variable definitions.
-   *
-   * @param code Generated code.
-   * @returns Completed code.
-   */
-  finish(code: string): string {
-    // Optionally override
-    // Clean up temporary data.
-    this.definitions_ = Object.create(null);
-    this.functionNames_ = Object.create(null);
-    return code;
-  }
-
-  /**
-   * Naked values are top-level blocks with outputs that aren't plugged into
-   * anything.
-   * Subclasses may override this, e.g. if their language does not allow
-   * naked values.
-   *
-   * @param line Line of generated code.
-   * @returns Legal line of code.
-   */
-  scrubNakedValue(line: string): string {
-    // Optionally override
-    return line;
-  }
-}