refactor!: Deprecate Block.getVars()

blocks/procedures.ts

@@ -38,6 +38,7 @@ import type {
 import {Msg} from '../core/msg.js';
 import {Names} from '../core/names.js';
 import * as Procedures from '../core/procedures.js';
+import * as deprecation from '../core/utils/deprecation.js';
 import * as xmlUtils from '../core/utils/xml.js';
 import * as Variables from '../core/variables.js';
 import type {Workspace} from '../core/workspace.js';
@@ -345,9 +346,17 @@ const PROCEDURE_DEF_COMMON = {
   /**
    * Return all variables referenced by this block.
    *
+   * @deprecated v13: Use Blockly.libraryBlocks.procedures.getVarModels()
+   *      .map(m => m.getName())
    * @returns List of variable names.
    */
   getVars: function (this: ProcedureBlock): string[] {
+    deprecation.warn(
+      'Blockly.libraryBlocks.procedures.getVars()',
+      'v13',
+      'v14',
+      'Blockly.libraryBlocks.procedures.getVarModels().map(model => model.getName())',
+    );
     return this.arguments_;
   },
   /**
@@ -1020,9 +1029,17 @@ const PROCEDURE_CALL_COMMON = {
   /**
    * Return all variables referenced by this block.
    *
+   * @deprecated v13: Use Blockly.libraryBlocks.procedures.getVarModels()
+   *      .map(m => m.getName())
    * @returns List of variable names.
    */
   getVars: function (this: CallBlock): string[] {
+    deprecation.warn(
+      'Blockly.libraryBlocks.procedures.getVars()',
+      'v13',
+      'v14',
+      'Blockly.libraryBlocks.procedures.getVarModels().map(model => model.getName())',
+    );
     return this.arguments_;
   },
   /**
@@ -1060,7 +1077,8 @@ const PROCEDURE_CALL_COMMON = {
       if (
         def &&
         (def.type !== this.defType_ ||
-          JSON.stringify(def.getVars()) !== JSON.stringify(this.arguments_))
+          JSON.stringify(def.getVarModels().map((model) => model.getName())) !==
+            JSON.stringify(this.arguments_))
       ) {
         // The signatures don't match.
         def = null;

core/block.ts

@@ -50,6 +50,7 @@ import * as registry from './registry.js';
 import * as Tooltip from './tooltip.js';
 import * as arrayUtils from './utils/array.js';
 import {Coordinate} from './utils/coordinate.js';
+import * as deprecation from './utils/deprecation.js';
 import * as idGenerator from './utils/idgenerator.js';
 import * as parsing from './utils/parsing.js';
 import {Size} from './utils/size.js';
@@ -1139,9 +1140,16 @@ export class Block {
   /**
    * Return all variables referenced by this block.
    *
+   * @deprecated v13: Use Blockly.Block.getVarModels().map(m => m.getId())
    * @returns List of variable ids.
    */
   getVars(): string[] {
+    deprecation.warn(
+      'Blockly.Block.getVars()',
+      'v13',
+      'v14',
+      'Blockly.Block.getVarModels().map(model => model.getId())',
+    );
     const vars: string[] = [];
     for (const field of this.getFields()) {
       if (field.referencesVariables()) {
@@ -1155,7 +1163,6 @@ export class Block {
    * Return all variables referenced by this block.
    *
    * @returns List of variable models.
-   * @internal
    */
   getVarModels(): IVariableModel<IVariableState>[] {
     const vars = [];

demos/blockfactory/factory_utils.js

@@ -964,7 +964,7 @@ FactoryUtils.hasVariableField = function(block) {
   if (!block) {
     return false;
   }
-  return block.getVars().length > 0;
+  return block.getVarModels().length > 0;
 };
 
 /**

generators/dart/procedures.ts

@@ -56,9 +56,9 @@ export function procedures_defreturn(block: Block, generator: DartGenerator) {
   }
   const returnType = returnValue ? 'dynamic' : 'void';
   const args = [];
-  const variables = block.getVars();
+  const variables = block.getVarModels();
   for (let i = 0; i < variables.length; i++) {
-    args[i] = generator.getVariableName(variables[i]);
+    args[i] = generator.getVariableName(variables[i].getId());
   }
   let code =
     returnType +
@@ -92,7 +92,7 @@ export function procedures_callreturn(
   // Call a procedure with a return value.
   const funcName = generator.getProcedureName(block.getFieldValue('NAME'));
   const args = [];
-  const variables = block.getVars();
+  const variables = block.getVarModels();
   for (let i = 0; i < variables.length; i++) {
     args[i] = generator.valueToCode(block, 'ARG' + i, Order.NONE) || 'null';
   }

generators/javascript/procedures.ts

@@ -58,9 +58,9 @@ export function procedures_defreturn(
     returnValue = generator.INDENT + 'return ' + returnValue + ';\n';
   }
   const args = [];
-  const variables = block.getVars();
+  const variables = block.getVarModels();
   for (let i = 0; i < variables.length; i++) {
-    args[i] = generator.getVariableName(variables[i]);
+    args[i] = generator.getVariableName(variables[i].getId());
   }
   let code =
     'function ' +
@@ -93,7 +93,7 @@ export function procedures_callreturn(
   // Call a procedure with a return value.
   const funcName = generator.getProcedureName(block.getFieldValue('NAME'));
   const args = [];
-  const variables = block.getVars();
+  const variables = block.getVarModels();
   for (let i = 0; i < variables.length; i++) {
     args[i] = generator.valueToCode(block, 'ARG' + i, Order.NONE) || 'null';
   }

generators/lua/procedures.ts

@@ -60,9 +60,9 @@ export function procedures_defreturn(
     branch = '';
   }
   const args = [];
-  const variables = block.getVars();
+  const variables = block.getVarModels();
   for (let i = 0; i < variables.length; i++) {
-    args[i] = generator.getVariableName(variables[i]);
+    args[i] = generator.getVariableName(variables[i].getId());
   }
   let code =
     'function ' +
@@ -95,7 +95,7 @@ export function procedures_callreturn(
   // Call a procedure with a return value.
   const funcName = generator.getProcedureName(block.getFieldValue('NAME'));
   const args = [];
-  const variables = block.getVars();
+  const variables = block.getVarModels();
   for (let i = 0; i < variables.length; i++) {
     args[i] = generator.valueToCode(block, 'ARG' + i, Order.NONE) || 'nil';
   }

generators/php/procedures.ts

@@ -26,8 +26,7 @@ export function procedures_defreturn(block: Block, generator: PhpGenerator) {
   const usedVariables = Variables.allUsedVarModels(workspace) || [];
   for (const variable of usedVariables) {
     const varName = variable.getName();
-    // getVars returns parameter names, not ids, for procedure blocks
-    if (!block.getVars().includes(varName)) {
+    if (!block.getVarModels().includes(variable)) {
       globals.push(generator.getVariableName(varName));
     }
   }
@@ -80,9 +79,9 @@ export function procedures_defreturn(block: Block, generator: PhpGenerator) {
     returnValue = generator.INDENT + 'return ' + returnValue + ';\n';
   }
   const args = [];
-  const variables = block.getVars();
+  const variables = block.getVarModels();
   for (let i = 0; i < variables.length; i++) {
-    args[i] = generator.getVariableName(variables[i]);
+    args[i] = generator.getVariableName(variables[i].getId());
   }
   let code =
     'function ' +
@@ -116,7 +115,7 @@ export function procedures_callreturn(
   // Call a procedure with a return value.
   const funcName = generator.getProcedureName(block.getFieldValue('NAME'));
   const args = [];
-  const variables = block.getVars();
+  const variables = block.getVarModels();
   for (let i = 0; i < variables.length; i++) {
     args[i] = generator.valueToCode(block, 'ARG' + i, Order.NONE) || 'null';
   }

generators/python/procedures.ts

@@ -26,8 +26,7 @@ export function procedures_defreturn(block: Block, generator: PythonGenerator) {
   const usedVariables = Variables.allUsedVarModels(workspace) || [];
   for (const variable of usedVariables) {
     const varName = variable.getName();
-    // getVars returns parameter names, not ids, for procedure blocks
-    if (!block.getVars().includes(varName)) {
+    if (!block.getVarModels().includes(variable)) {
       globals.push(generator.getVariableName(varName));
     }
   }
@@ -82,9 +81,9 @@ export function procedures_defreturn(block: Block, generator: PythonGenerator) {
     branch = generator.PASS;
   }
   const args = [];
-  const variables = block.getVars();
+  const variables = block.getVarModels();
   for (let i = 0; i < variables.length; i++) {
-    args[i] = generator.getVariableName(variables[i]);
+    args[i] = generator.getVariableName(variables[i].getId());
   }
   let code =
     'def ' +
@@ -117,7 +116,7 @@ export function procedures_callreturn(
   // Call a procedure with a return value.
   const funcName = generator.getProcedureName(block.getFieldValue('NAME'));
   const args = [];
-  const variables = block.getVars();
+  const variables = block.getVarModels();
   for (let i = 0; i < variables.length; i++) {
     args[i] = generator.valueToCode(block, 'ARG' + i, Order.NONE) || 'None';
   }

tests/mocha/blocks/procedures_test.js

@@ -1973,20 +1973,26 @@ suite('Procedures', function () {
             }
             function assertArgs(argArray) {
               assert.equal(
-                this.defBlock.getVars().length,
+                this.defBlock.getVarModels().length,
                 argArray.length,
                 'Expected the def to have the right number of arguments',
               );
               for (let i = 0; i < argArray.length; i++) {
-                assert.equal(this.defBlock.getVars()[i], argArray[i]);
+                assert.equal(
+                  this.defBlock.getVarModels()[i].getName(),
+                  argArray[i],
+                );
               }
               assert.equal(
-                this.callBlock.getVars().length,
+                this.callBlock.getVarModels().length,
                 argArray.length,
                 'Expected the call to have the right number of arguments',
               );
               for (let i = 0; i < argArray.length; i++) {
-                assert.equal(this.callBlock.getVars()[i], argArray[i]);
+                assert.equal(
+                  this.callBlock.getVarModels()[i].getName(),
+                  argArray[i],
+                );
               }
             }
             test('Simple Add Arg', async function () {

tests/mocha/test_helpers/procedures.js

@@ -47,7 +47,10 @@ function assertCallBlockArgsStructure(callBlock, args) {
       'Call block consts did not match expected.',
     );
   }
-  assert.sameOrderedMembers(callBlock.getVars(), args);
+  assert.sameOrderedMembers(
+    callBlock.getVarModels().map((model) => model.getName()),
+    args,
+  );
 }
 
 /**
@@ -104,7 +107,10 @@ export function assertDefBlockStructure(
     );
   }
 
-  assert.sameOrderedMembers(defBlock.getVars(), args);
+  assert.sameOrderedMembers(
+    defBlock.getVarModels().map((model) => model.getName()),
+    args,
+  );
   assertBlockVarModels(defBlock, varIds);
 }