From 27f6c1e91532ab4a123852f00054772862e39f5a Mon Sep 17 00:00:00 2001 From: sae220 Date: Mon, 30 Sep 2024 22:08:09 +0900 Subject: [PATCH 1/8] Improve sig snippet to display alias statement --- pxtrunner/renderer.ts | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/pxtrunner/renderer.ts b/pxtrunner/renderer.ts index 225a0e6ec735..7cd345d43e3c 100644 --- a/pxtrunner/renderer.ts +++ b/pxtrunner/renderer.ts @@ -481,7 +481,8 @@ function renderSignaturesAsync(options: ClientRenderOptions): Promise { let cjs = r.compileProgram; if (!cjs) return; let file = cjs.getSourceFile(pxt.MAIN_TS); - let info = decompileCallInfo(file.statements[0]); + let [mainStatement, ...aliasStatements] = file.statements + let info = decompileCallInfo(mainStatement); if (!info || !r.apiInfo) return; const symbolInfo = r.apiInfo.byQName[info.qName]; if (!symbolInfo) return; @@ -497,6 +498,22 @@ function renderSignaturesAsync(options: ClientRenderOptions): Promise { const pySig = pxt.appTarget?.appTheme?.python && ts.pxtc.service.displayStringForSymbol(symbolInfo, /** python **/ true, r.apiInfo).split("\n")[1]; const py: JQuery = pySig && $('').text(pySig); if (options.snippetReplaceParent) c = c.parent(); + + // add alias svgs + let svgs = $('
').append(s); + svgs = aliasStatements.reduce((parentElement, statement) => { + let aliasInfo = decompileCallInfo(statement); + if (!aliasInfo) return parentElement; + const aliasSymbolInfo = r.apiInfo.byQName[aliasInfo.qName]; + if (!aliasSymbolInfo) return parentElement; + if (aliasSymbolInfo.attributes.blockAliasFor !== info.qName) return parentElement; + let aliasBlock = Blockly.Blocks[aliasSymbolInfo.attributes.blockId]; + let aliasXml = aliasBlock?.codeCard?.blocksXml || undefined; + const aliasBlocksHtml = aliasXml ? render(aliasXml) : r.compileBlocks?.success ? r.blocksSvg : undefined; + const aliasSvg = aliasBlocksHtml ? $(aliasBlocksHtml as HTMLElement) : undefined; + return parentElement.append(aliasSvg); + }, svgs); + // add an html widge that allows to translate the block if (pxt.Util.isTranslationMode()) { const trs = $('
'); @@ -507,7 +524,7 @@ function renderSignaturesAsync(options: ClientRenderOptions): Promise { trs.append($('
').text(symbolInfo.attributes.jsDoc)); trs.insertAfter(c); } - fillWithWidget(options, c, js, py, s, r, { showJs: true, showPy: true, hideGutter: true }); + fillWithWidget(options, c, js, py, svgs, r, { showJs: true, showPy: true, hideGutter: true }); }, { package: options.package, snippetMode: true, aspectRatio: options.blocksAspectRatio, assets: options.assetJSON }); } From faa2ede552059eeade7c725b27b699e227324d41 Mon Sep 17 00:00:00 2001 From: sae220 Date: Mon, 30 Sep 2024 22:09:00 +0900 Subject: [PATCH 2/8] Add alias statement to sig snippet --- common-docs/reference/arrays/pop.md | 3 ++- common-docs/reference/arrays/remove-at.md | 3 ++- common-docs/reference/arrays/shift.md | 3 ++- common-docs/reference/arrays/unshift.md | 3 ++- 4 files changed, 8 insertions(+), 4 deletions(-) diff --git a/common-docs/reference/arrays/pop.md b/common-docs/reference/arrays/pop.md index e875e17e15a8..e55cd05f9062 100644 --- a/common-docs/reference/arrays/pop.md +++ b/common-docs/reference/arrays/pop.md @@ -3,7 +3,8 @@ Remove and return the last element from an array. ```sig -["hello"].pop() +["hello"].pop(); +["hello"]._popStatement(); ``` The last element in the array is removed, so the array becomes smaller by one element. diff --git a/common-docs/reference/arrays/remove-at.md b/common-docs/reference/arrays/remove-at.md index 4f16c370e7bb..fba150ebec70 100644 --- a/common-docs/reference/arrays/remove-at.md +++ b/common-docs/reference/arrays/remove-at.md @@ -3,7 +3,8 @@ Remove and return an element from an array at some position. ```sig -[""].removeAt(0) +[""].removeAt(0); +[""]._removeAtStatement(0); ``` The size of the array shrinks by one. The element is removed from the array at the position you want. All the other elements after it are moved (shifted) to down to the next lower position. So, an array that has the numbers diff --git a/common-docs/reference/arrays/shift.md b/common-docs/reference/arrays/shift.md index b17205a84b39..d1ff7b3a2a2a 100644 --- a/common-docs/reference/arrays/shift.md +++ b/common-docs/reference/arrays/shift.md @@ -3,7 +3,8 @@ Remove and return the first element from an array. ```sig -[""].shift() +[""].shift(); +[""]._shiftStatement(); ``` The first element in the array is removed, so the array becomes smaller by one element. diff --git a/common-docs/reference/arrays/unshift.md b/common-docs/reference/arrays/unshift.md index d678ba91b912..b1502948075c 100644 --- a/common-docs/reference/arrays/unshift.md +++ b/common-docs/reference/arrays/unshift.md @@ -3,7 +3,8 @@ Add an element to the front of an array. ```sig -[""].unshift("hello") +[""].unshift("hello"); +[""]._unshiftStatement("hello"); ``` You might have an array with 3 numbers, like 1, 2, and 3. If you want to add another number to the front, From 1d0f82c5241c5589a1f980d12f5bee954495f894 Mon Sep 17 00:00:00 2001 From: sae220 Date: Mon, 30 Sep 2024 22:09:32 +0900 Subject: [PATCH 3/8] Revert _removeAtStatement help doc --- .../reference/arrays/remove-at-statement.md | 33 ------------------- common-docs/reference/arrays/remove-at.md | 1 - libs/pxt-common/pxt-core.d.ts | 2 +- 3 files changed, 1 insertion(+), 35 deletions(-) delete mode 100644 common-docs/reference/arrays/remove-at-statement.md diff --git a/common-docs/reference/arrays/remove-at-statement.md b/common-docs/reference/arrays/remove-at-statement.md deleted file mode 100644 index 559133a6fbd4..000000000000 --- a/common-docs/reference/arrays/remove-at-statement.md +++ /dev/null @@ -1,33 +0,0 @@ -# remove At (no return value) - -Remove an element from an array at some position. - -```sig -[""]._removeAtStatement(0) -``` - -The size of the array shrinks by one. The element is removed from the array at the position you want. All the other elements after it are moved (shifted) to down to the next lower position. So, an array that has the numbers -`4, 5, 9, 3, 2` will be `4, 5, 3, 2` if `9` is removed from the array at index `2`. It looks like this in blocks: - -```block -let myNumbers = [4, 5, 9, 3, 2] -myNumbers.removeAt(2) -``` - -## Parameters - -* **index**: the position in the array to get the element from. - -## Example - -Remove the largest animal from the list of primates. - -```block -let primates = ["chimpanzee", "baboon", "gorilla", "macaque"] -let largest = primates.indexOf("gorilla") -primates.removeAt(largest) -``` - -## See also - -[remove at](/reference/arrays/remove-at), [insert at](/reference/arrays/insert-at) \ No newline at end of file diff --git a/common-docs/reference/arrays/remove-at.md b/common-docs/reference/arrays/remove-at.md index fba150ebec70..5dcc9e779bb7 100644 --- a/common-docs/reference/arrays/remove-at.md +++ b/common-docs/reference/arrays/remove-at.md @@ -35,5 +35,4 @@ let unzapped = radLevels.removeAt(level) ## See also -[remove at (no return value)](/reference/arrays/remove-at-statement), [insert at](/reference/arrays/insert-at) \ No newline at end of file diff --git a/libs/pxt-common/pxt-core.d.ts b/libs/pxt-common/pxt-core.d.ts index 900d05f9dfab..bb41a8f5fb6d 100644 --- a/libs/pxt-common/pxt-core.d.ts +++ b/libs/pxt-common/pxt-core.d.ts @@ -245,7 +245,7 @@ interface Array { _shiftStatement(): void; /** Remove the element at a certain index. */ - //% help=arrays/remove-at-statement + //% help=arrays/remove-at //% shim=Array_::removeAt weight=14 //% blockId="array_removeat_statement" block="%list| remove value at %index" blockNamespace="arrays" //% blockAliasFor="Array.removeAt" From b0f8acf30f72624dee66760c6445e128b2346607 Mon Sep 17 00:00:00 2001 From: sae220 Date: Tue, 8 Oct 2024 23:14:38 +0900 Subject: [PATCH 4/8] Revert remove-at-statement.md --- .../reference/arrays/remove-at-statement.md | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 common-docs/reference/arrays/remove-at-statement.md diff --git a/common-docs/reference/arrays/remove-at-statement.md b/common-docs/reference/arrays/remove-at-statement.md new file mode 100644 index 000000000000..559133a6fbd4 --- /dev/null +++ b/common-docs/reference/arrays/remove-at-statement.md @@ -0,0 +1,33 @@ +# remove At (no return value) + +Remove an element from an array at some position. + +```sig +[""]._removeAtStatement(0) +``` + +The size of the array shrinks by one. The element is removed from the array at the position you want. All the other elements after it are moved (shifted) to down to the next lower position. So, an array that has the numbers +`4, 5, 9, 3, 2` will be `4, 5, 3, 2` if `9` is removed from the array at index `2`. It looks like this in blocks: + +```block +let myNumbers = [4, 5, 9, 3, 2] +myNumbers.removeAt(2) +``` + +## Parameters + +* **index**: the position in the array to get the element from. + +## Example + +Remove the largest animal from the list of primates. + +```block +let primates = ["chimpanzee", "baboon", "gorilla", "macaque"] +let largest = primates.indexOf("gorilla") +primates.removeAt(largest) +``` + +## See also + +[remove at](/reference/arrays/remove-at), [insert at](/reference/arrays/insert-at) \ No newline at end of file From 45f33a3007c38a1a94ad8fe2aba7cb398d03545b Mon Sep 17 00:00:00 2001 From: Galen Nickel Date: Tue, 15 Oct 2024 17:22:33 -0700 Subject: [PATCH 5/8] add statement 'alias' information to 'pop' page --- common-docs/reference/arrays/pop.md | 33 ++++++++++++++++++++++------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/common-docs/reference/arrays/pop.md b/common-docs/reference/arrays/pop.md index e55cd05f9062..09d9129fb101 100644 --- a/common-docs/reference/arrays/pop.md +++ b/common-docs/reference/arrays/pop.md @@ -3,8 +3,13 @@ Remove and return the last element from an array. ```sig -["hello"].pop(); -["hello"]._popStatement(); +["hello"].pop() +``` + +Remove the last element from an array but don't return it. + +```sig +["hello"]._popStatement() ``` The last element in the array is removed, so the array becomes smaller by one element. @@ -13,28 +18,40 @@ If you have an array with 4 numbers, like 1, 2, 3, and 4, you remove the last nu by _popping_ it off of the end. To pop the number from the array in blocks, do this: ```block -let thoseNumbers = [1, 2, 3, 4]; -let lastNumber = thoseNumbers.pop(); +let thoseNumbers = [1, 2, 3, 4] +let lastNumber = thoseNumbers.pop() ``` ## Returns * The last element in the array. +### ~reminder + +#### **pop** statement + +The ``||arrays:pop||`` **statement** only removes the last element from the array. It doesn't return it. + +```block +["a", "b", "c"]._popStatement() +``` + +### ~ + ## Example Clean out your junk drawer but check if the scissors are in there. Do this by removing them from your list items in the drawer. ```blocks -let found = false; -let junk = ["paper clip", "pencil", "notepad", "glue", "scissors", "screw driver"]; +let found = false +let junk = ["paper clip", "pencil", "notepad", "glue", "scissors", "screw driver"] while (junk.length > 0) { if (junk.pop() == "scissors") { - found = true; + found = true } } ``` ## See also -[push](/reference/arrays/push), [shift](/reference/arrays/shift) \ No newline at end of file +[push](/reference/arrays/push), [shift](/reference/arrays/shift) From 1a3549c423615febb5a9c36e2e03c409987d840f Mon Sep 17 00:00:00 2001 From: Galen Nickel Date: Tue, 15 Oct 2024 17:24:03 -0700 Subject: [PATCH 6/8] add statement 'alias' information to 'remove-at' page --- common-docs/reference/arrays/remove-at.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/common-docs/reference/arrays/remove-at.md b/common-docs/reference/arrays/remove-at.md index 5dcc9e779bb7..d434b2054cf7 100644 --- a/common-docs/reference/arrays/remove-at.md +++ b/common-docs/reference/arrays/remove-at.md @@ -3,8 +3,13 @@ Remove and return an element from an array at some position. ```sig -[""].removeAt(0); -[""]._removeAtStatement(0); +[""].removeAt(0) +``` + +Remove an element from an array at some position but don't return it. + +```sig +[""]._removeAtStatement(0) ``` The size of the array shrinks by one. The element is removed from the array at the position you want. All the other elements after it are moved (shifted) to down to the next lower position. So, an array that has the numbers @@ -23,6 +28,18 @@ let item = myNumbers.removeAt(2) * the element in the array from the position you chose. +### ~reminder + +#### **remove At** statement + +The ``||arrays:remove at||`` **statement** only removes an element from the array. It doesn't return it. + +```block +["a", "b", "c"]._removeAtStatement(0) +``` + +### ~ + ## Example Remove the most dangerous level of radiation from the list. @@ -35,4 +52,4 @@ let unzapped = radLevels.removeAt(level) ## See also -[insert at](/reference/arrays/insert-at) \ No newline at end of file +[insert at](/reference/arrays/insert-at) From a16156d21eb47398cc1074a4d468f456485b6f5e Mon Sep 17 00:00:00 2001 From: Galen Nickel Date: Tue, 15 Oct 2024 17:25:17 -0700 Subject: [PATCH 7/8] add statement 'alias' information to 'shift' page --- common-docs/reference/arrays/shift.md | 31 ++++++++++++++++++++------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/common-docs/reference/arrays/shift.md b/common-docs/reference/arrays/shift.md index d1ff7b3a2a2a..ce73cb758b6e 100644 --- a/common-docs/reference/arrays/shift.md +++ b/common-docs/reference/arrays/shift.md @@ -3,8 +3,13 @@ Remove and return the first element from an array. ```sig -[""].shift(); -[""]._shiftStatement(); +[""].shift() +``` + +Remove the first element from an array but don't return it. + +```sig +[""]._shiftStatement() ``` The first element in the array is removed, so the array becomes smaller by one element. @@ -13,24 +18,35 @@ If you have an array with 4 numbers, like 1, 2, 3, and 4, you remove the first n by _shifting_ it from the front. To shift the number from the array in blocks, do this: ```block -let thoseNumbers = [1, 2, 3, 4]; -let firstNumber = thoseNumbers.shift(); +let thoseNumbers = [1, 2, 3, 4] +let firstNumber = thoseNumbers.shift() ``` ## Returns * the first element in the array. +### ~reminder + +#### **shift** statement + +The ``||arrays:shift||`` **statement** only removes the first element from the array. It doesn't return it. + +```block +["a", "b", "c"]._shiftStatement() +``` + +### ~ ## Example Find out how many odd numbers there are as you remove all the numbers from a list. ```blocks -let odds = 0; -let ints = [45, 78, 98, 3, 5, 6, 12, 643, 0, 34, 4]; +let odds = 0 +let ints = [45, 78, 98, 3, 5, 6, 12, 643, 0, 34, 4] while (ints.length > 0) { if ((ints.shift() % 2) > 0) { - odds++; + odds++ } } ``` @@ -38,4 +54,3 @@ while (ints.length > 0) { ## See also [unshift](/reference/arrays/unshift), [pop](/reference/arrays/pop) - From ece60dde418814e3b30b48ce7743ea648e193678 Mon Sep 17 00:00:00 2001 From: Galen Nickel Date: Tue, 15 Oct 2024 17:26:38 -0700 Subject: [PATCH 8/8] add statement 'alias' information to 'unshift' page --- common-docs/reference/arrays/unshift.md | 32 +++++++++++++++++++------ 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/common-docs/reference/arrays/unshift.md b/common-docs/reference/arrays/unshift.md index b1502948075c..caeadd9d6bbf 100644 --- a/common-docs/reference/arrays/unshift.md +++ b/common-docs/reference/arrays/unshift.md @@ -1,25 +1,43 @@ # unshift -Add an element to the front of an array. +Add an element to the front of an array and return the new length of the array. ```sig -[""].unshift("hello"); -[""]._unshiftStatement("hello"); +[""].unshift("hello") +``` +Add an element to the front of an array but don't return the new length of the array. + +```sig +[""]._unshiftStatement("hello") ``` You might have an array with 3 numbers, like 1, 2, and 3. If you want to add another number to the front, then you _unshift_ it into the array. You do it like this: ```block -let thoseNumbers = [1, 2, 3]; -let head = 0; -head = thoseNumbers.unshift(0); +let thoseNumbers = [1, 2, 3] +let arrayLength = thoseNumbers.unshift(0) ``` ## Parameters * **item**: the element to add to the front of the array. +## Returns + +* the new length of the array. + +### ~reminder + +#### **shift** statement + +The ``||arrays:unshift||`` **statement** only adds an element to the front of the array. It doesn't the array length. + +```block +["a", "b", "c"]._shiftStatement() +``` + +### ~ ## Example Make an array that simulates a train. Place the parts of the train in the right order. @@ -47,4 +65,4 @@ while (parts.length > 0) { ## Sea also -[shift](/reference/arrays/shift), [push](/reference/arrays/push) \ No newline at end of file +[shift](/reference/arrays/shift), [push](/reference/arrays/push)