Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

refactor(generators): Introduce PhpGenerator class, Order enum #7162

Merged
merged 3 commits into from
Jun 14, 2023

Conversation

cpcallen
Copy link
Contributor

@cpcallen cpcallen commented Jun 14, 2023

The basics

  • I branched from develop
  • My pull request is against develop
  • My code follows the style guide
  • I ran npm run format and npm run lint

The details

Resolves

Part of #7085.

Proposed Changes

Introduce a PhpGenerator class to be the class of which phpGenerator is an instance (without any additional properties making it a singleton).
Introduce an Order enum (for now Closure-style) for the operator precedence table.
Don't rename phpGenerator to PHP in generators/php/*.js.

Behaviour Before/After Change

There should be no changes in behaviour.

Reason for Changes

See #7085.

Test Coverage

Passes npm test; no changes to manual testing anticipated.

Documentation

Documentation for the PhpGenerator class and Order enum should be automatically generated by our JSDoc configs.

Additional Information

It is now possible to create multiple phpGenerator objects, which can share (or not share) block generator implementations. Note that new instances do not by default come with any generator functions pre-installed.

import {phpGenerator, PhpGenerator} from 'blockly/php';

const customJSGenerator = new PhpGenerator();

// Optionally copy standard generator functions to new instance:
Object.assign(customPhpGenerator.forBlock, phpGenerator.forBlock);

// Optionally add/replace some/all generator functions:
customPhpGenerator.forBlock('block_type') = function(block) {/* new implementation */};

// Optionally change settings:
customPhpGenerator.INDENT = '\t';  // Use tabs to indent generated code.

We now provide an enum of the operator precedence values (order of operations) constants as a separate export:

import {phpGenerator, Order} from 'blockly/php';

// Old:
phpGenerator.forBlock('answer_expression_block') = function(block) {
  const code = '42';
  return [code, phpGenerator.ORDER_ATOMIC]
}

// New:
phpGenerator.forBlock('answer_expression_block') = function(block) {
  const code = '42';
  return [code, Order.ATOMIC]
}

DEPRECATION: The .ORDER_* constants on phpGenerator are deprecated; they still exist but are no longer part of the documented API and will be removed in a future version of Blockly. We recommend that you update your custom generator code to use the Order enum at your earliest convenience.

@cpcallen cpcallen merged commit eeb8919 into google:develop Jun 14, 2023
@cpcallen cpcallen added the deprecation This PR deprecates an API. label Jun 14, 2023
@github-actions github-actions bot added PR: refactor and removed PR: refactor deprecation This PR deprecates an API. labels Jun 14, 2023
@cpcallen cpcallen deleted the refactor/7085/php branch June 14, 2023 18:01
@cpcallen cpcallen linked an issue Jun 14, 2023 that may be closed by this pull request
@cpcallen cpcallen added the deprecation This PR deprecates an API. label Jun 15, 2023
cpcallen added a commit to cpcallen/blockly that referenced this pull request Jun 15, 2023
These were inadvertently omitted from google#7161 and google#7162, respectively.
cpcallen added a commit that referenced this pull request Jun 20, 2023
…ffects (#7173)

* refactor(generators): Move lang.js -> lang/lang_gernator.js

  Move the LangGenerator definitions into their respective
  subdirectories and add a _generator suffix to their filenames,
  i.e. generators/javascript.js  becomes
  generators/javascript/javascript_generator.js.

  This is to keep related code together and allow the `lang/all.js`
  entrypoints to be moved to the top level generators/ directory.

  No goog module IDs were changed, so playground and test code
  that accesses this modules by filename does not need to be modified.

* refactor(generators) Move lang/all.js -> lang.js

  - Move the entrypoints in generators/*/all.js to correspondingly-named
    files in generators/ instead—i.e., generators/javascript/all.js
    becomes generators/javascript.js.

  - Update build_tasks.js accordingly.

* fix(generators): Add missing exports for LuaGenerator, PhpGenerator

  These were inadvertently omitted from #7161 and #7162, respectively.

* refactor(generators): Make block generator modules side-effect free

  - Move declaration of <lang>Generator instance from
    generators/<lang>/<lang>_generator.js to generators/<lang>.js.
  - Move .addReservedWords() calls from generators/<lang>/*.js to
    generators/<lang>.js
  - Modify generators/<lang>/*.js to export block generator functions
    individually, rather than installing on <lang>Generator instance.
  - Modify generators/<lang>.js to import and install block generator
    functions on <lang>Generator instance.

* fix(tests): Fix tests broken by restructuring of generators

  Where these tests needed block generator functions preinstalled
  they should have been importing the Blockly.<Lang>.all module.

  Where they do not need the provided block generator functions
  they can now create their own empty <Lang>Generator instances.

* chore: Update renamings file

  - Fix a malformation in previous entries that was not detected by
    the renaming file validator test.
  - Add entries describing the work done in this and related recent
    PRs.

* fix: Correct minor errors in PR #7173

  - Fix a search-and-replace error in renamings.json5
  - Fix an incorrect-but-usable import in generator_test.js
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Proposal: Per-language subclasses of CodeGenerator in generators/
3 participants