parse-sb3-blocks/README.md

Parse sb3 blocks, and generate scratchblocks formatted code.

# parse-sb3-blocks
**parse-sb3-blocks** parses Scratch 3.0 block formats, and convert it to [scratchblocks](https://github.com/scratchblocks/scratchblocks) format.

## Usage
### Example
```js
import {toScratchblocks} from 'parse-sb3-blocks';

const sb3blocks = {
    'ND,(]G?KLIy(IZrd2sl.': {
        opcode: 'event_whenflagclicked',
        ...
    }
};

console.log(toScratchblocks('ND,(]G?KLIy(IZrd2sl.', sb3blocks, 'en', {tabs: ' '.repeat(4)}));
```

### toScratchblocks
**toScratchblocks** is a function. This can take three to four arguments:

- scriptStart: The block ID to start parsing from. **This must be a block ID of Connectable** (which includes hat blocks.)
- blocks: serialized SB3 format (project.json format) of blocks.
- locale: Locale to use. `en` should always be available.
- opts: Optional. It can be an object (see below)

#### Options
`opts` can have these properties.

- tabs: Tab characters used by C/E blocks for indenting. **Note that while parse-sb3-blocks can use non-space/tab indent, scratchblocks only accepts tab or spaces.** Pass empty string to remove indents. Defaults to four spaces.
- variableStyle: If set to `none` (default), variables will never have `::variables` at the end. If set to `always`, it will always have `::variables`. If set to `as-needed`, it will have `::variables` if block name conflicts.

### Internal Functions and Parsers
It also exports several classes used internally by the parsers. These are not APIs and is subject to changes at any time.

#### Inputtable and Connectable
Connectable is an instance that can be connected to a stack block via next-parent, including:
- Block (stack, hat, cap)
- CBlock
- EBlock (if-else)
- Definition
- ProcedureCall

Inputtable can be used as an argument. Note that `Icon` is not technically an argument, but is Inputtable.
- Stack (for arguments to C/E blocks)
- Menu (includes fields menu and menu block)
- Variable (variable reporters and custom block arguments)
- Icon (greenFlag, turnLeft, turnRight icon)
- BooleanBlock
- ReporterBlock
- Input and its subclasses NumberInput, StringInput, ColorPickerInput, BroadcastMenuInput, EmptyBooleanInput

Both Connectable and Inputtable implement `toScratchblocks` method. It accepts `locale` and `opts`, similar to the exported `toScratchblocks`.

Instances with class name ending with "Block" have these attributes:
- `id` for block ID
- `opcode` for block opcode
- `inputtables` for object of input key to Inputtable

### Block Mapping
`block-enum.js` provides an enum for block types.

`translations.js` is an auto-generated file which includes all translations. `options.js` is also auto-generated, and contains which block needs options (because of conflicting names).

**Only blocks and menu items in all-blocks.js are supported.**

#### all-blocks.js
all-blocks.js default-exports allBlocks, which is an object with opcode as key and the object (see below) as value.

The object has these keys and values:
- noTranslation: If set to `true`, it will be ignored from the translation generator.
- defaultMessage: Message in default language (English).
- type: The block type. Defaults to `BlockEnum.BLOCK`.
- defaultOptions: The block option for the block when using defaultMessage, in case duplicates exist. It can have category key and the category as a value.
- translationKey: Translation key for scratch-l10n. Defaults to the block opcode, upper-cased.
- boolArg: Array of arguments which must be boolean. Used to fill empty arguments with `EmptyBooleanInput`. If omitted, empty array is used.

## Building
Node 16+ is required for building. Type `npm run build`, which generates locale files.

### env
- `mode`: Unless set to `dev`, the result is minified. Add `docs` to update the JS file used in demo.