diff --git a/.github/ISSUE_TEMPLATE/1_page_issue.yml b/.github/ISSUE_TEMPLATE/1_page_issue.yml index 3926106cb..034feec00 100644 --- a/.github/ISSUE_TEMPLATE/1_page_issue.yml +++ b/.github/ISSUE_TEMPLATE/1_page_issue.yml @@ -1,6 +1,6 @@ name: 文档或页面问题 description: 协助改进 dart.cn 的页面内容 -title: "[PAGE ISSUE]: '{请替换为页面的标题}'" +title: '[页面问题] {请替换为页面的标题}' labels: ['E: 页面问题'] body: - type: markdown @@ -11,7 +11,7 @@ body: id: page-url attributes: label: 页面 URL - placeholder: "例如：https://dart.cn/docs" + placeholder: "例如：https://dart.cn/guides" validations: required: true - type: input @@ -42,3 +42,11 @@ body: placeholder: 任何你认为我们需要知道的额外信息。 validations: required: false + - type: checkboxes + id: volunteer + attributes: + label: 我想来解决这个问题。 + description: 如果你想自己尝试修复，请告诉我们。 + options: + - label: 我会尝试在 dart.cn 上解决这个问题。 + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index b35f63b38..eb1ba7eb5 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,19 +1,4 @@ -Thanks for your contribution! Please replace this text with a description of what this PR is changing or adding and why, list any relevant issues, and review the contribution guidelines below. +**请点击「Preview」选择提交 PR 的模板**： -Fixes - ---- - -- [ ] I’ve reviewed the contributor guide and applied the relevant portions to this PR. -- [ ] This PR doesn’t contain automatically generated corrections or text (Grammarly, LLMs, and similar). -- [ ] This PR follows the [Google Developer Documentation Style Guidelines](https://developers.google.com/style) — for example, it doesn’t use _i.e._ or _e.g._, and it avoids _I_ and _we_ (first person). -- [ ] This PR uses [semantic line breaks](https://github.com/dart-lang/site-shared/blob/main/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks) of 80 characters or fewer. - -
- Contribution guidelines:
- - - See our [contributor guide](https://github.com/dart-lang/site-www/blob/main/CONTRIBUTING.md) for general expectations for PRs. - - Larger or significant changes should be discussed in an issue before creating a PR. - - Code changes should generally follow the [Dart style guide](https://dart.dev/effective-dart) and use `dart format`. - - Updates to [code excerpts](https://github.com/dart-lang/site-shared/blob/main/doc/code-excerpts.md) indicated by ` +- [内容修订](?template=1_cn_doc_fix.md) +- [新增翻译](?template=2_localization_submission.md) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index ebea6b17c..32b5d6f07 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -18,7 +18,7 @@ env: # Keep for Dart SDK reporting PUB_ENVIRONMENT: bot.github # LTS - NODE_VERSION: '18' + NODE_VERSION: '20' # Tool location BASE_DIR: ${{ github.workspace }} TOOL_DIR: ${{ github.workspace }}/tool @@ -31,14 +31,18 @@ jobs: fail-fast: false matrix: include: +# - sdk: dev +# experimental: false + - sdk: beta + experimental: false - sdk: stable experimental: false continue-on-error: ${{ matrix.experimental }} steps: - - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 + - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 with: submodules: recursive - - uses: dart-lang/setup-dart@d6a63dab3335f427404425de0fbfed4686d93c4f + - uses: dart-lang/setup-dart@b64355ae6ca0b5d484f0106a033dd1388965d06d with: sdk: ${{ matrix.sdk }} - run: dart pub get @@ -59,15 +63,15 @@ jobs: FIREBASE_TOKEN: ${{ secrets.FIREBASE_TOKEN }} FIREBASE_PROJECT: default steps: - - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 + - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 with: submodules: recursive - run: make build - run: make write-prod-robots - - uses: actions/setup-node@e33196f7422957bea03ed53f6fbb155025ffc7b8 + - uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 with: node-version: ${{ env.NODE_VERSION }} - - uses: dart-lang/setup-dart@d6a63dab3335f427404425de0fbfed4686d93c4f + - uses: dart-lang/setup-dart@b64355ae6ca0b5d484f0106a033dd1388965d06d with: sdk: stable #- run: tool/check-links.sh diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index 3881a55b4..9b334692f 100644 --- a/.github/workflows/codeql-analysis.yml +++ b/.github/workflows/codeql-analysis.yml @@ -29,11 +29,11 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 + uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # Initializes the CodeQL tools for scanning. - name: Initialize CodeQL - uses: github/codeql-action/init@0ba4244466797eb048eb91a6cd43d5c03ca8bd05 + uses: github/codeql-action/init@74483a38d39275f33fcff5f35b679b5ca4a26a99 with: languages: ${{ matrix.language }} # If you wish to specify custom queries, you can do so here or in a config file. @@ -44,7 +44,7 @@ jobs: # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). # If this step fails, then you should remove it and run the build manually (see below) - name: Autobuild - uses: github/codeql-action/autobuild@0ba4244466797eb048eb91a6cd43d5c03ca8bd05 + uses: github/codeql-action/autobuild@74483a38d39275f33fcff5f35b679b5ca4a26a99 # ℹ️ Command-line programs to run using the OS shell. # 📚 https://git.io/JvXDl @@ -58,4 +58,4 @@ jobs: # make release - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@0ba4244466797eb048eb91a6cd43d5c03ca8bd05 + uses: github/codeql-action/analyze@74483a38d39275f33fcff5f35b679b5ca4a26a99 diff --git a/.github/workflows/no-response.yaml b/.github/workflows/no-response.yaml index 22a7e3940..6933d6f22 100644 --- a/.github/workflows/no-response.yaml +++ b/.github/workflows/no-response.yaml @@ -31,4 +31,4 @@ jobs: # Number of days of inactivity before an issue is closed for lack of response. daysUntilClose: 21 # Label requiring a response. - responseRequiredLabel: "waiting for customer response" + responseRequiredLabel: "act.wait-for-customer" diff --git a/.github/workflows/scorecards-analysis.yml b/.github/workflows/scorecards-analysis.yml index 16b5d60ba..b2c41d179 100644 --- a/.github/workflows/scorecards-analysis.yml +++ b/.github/workflows/scorecards-analysis.yml @@ -21,12 +21,12 @@ jobs: steps: - name: "Checkout code" - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 + uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 with: persist-credentials: false - name: "Run analysis" - uses: ossf/scorecard-action@08b4669551908b1024bb425080c797723083c031 + uses: ossf/scorecard-action@0864cf19026789058feabb7e87baa5f140aac736 with: results_file: results.sarif results_format: sarif @@ -41,7 +41,7 @@ jobs: # Upload the results as artifacts (optional). - name: "Upload artifact" - uses: actions/upload-artifact@0b7f8abb1508181956e8e162db84b466c27e18ce + uses: actions/upload-artifact@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 with: name: SARIF file path: results.sarif @@ -49,6 +49,6 @@ jobs: # Upload the results to GitHub's code scanning dashboard. - name: "Upload to code-scanning" - uses: github/codeql-action/upload-sarif@0ba4244466797eb048eb91a6cd43d5c03ca8bd05 + uses: github/codeql-action/upload-sarif@74483a38d39275f33fcff5f35b679b5ca4a26a99 with: sarif_file: results.sarif diff --git a/.gitignore b/.gitignore index b86e7f5c3..33872d381 100644 --- a/.gitignore +++ b/.gitignore @@ -30,3 +30,8 @@ tmp # Misc trash /src/_data/ci.yaml + +# SHA Update +# The script generates the .save file in case you need a rollback. +*.save +tool/new-dart-hashes.txt diff --git a/.gitmodules b/.gitmodules index 1ca07b61a..e870af4f0 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,4 +1,4 @@ [submodule "site-shared"] - path = site-shared - url = https://github.com/dart-lang/site-shared.git - branch = main + path = site-shared + url = https://github.com/dart-lang/site-shared + branch = main diff --git a/Dockerfile b/Dockerfile index 0d4f71514..10099e9a1 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,12 +1,18 @@ -FROM ruby:3.2-slim-bookworm@sha256:2de48b02b2c3383799991fd5573462a7646a92a068b4afbb0e161ad166a3de9a as base +FROM ruby:3.2-slim-bookworm@sha256:adc7f93df5b83c8627b3fadcc974ce452ef9999603f65f637e32b8acec096ae1 as base + +SHELL ["/usr/bin/bash", "-c"] + +# Configure Debian mirrors. +RUN sed -i 's/deb.debian.org/mirrors.ustc.edu.cn/g' /etc/apt/sources.list.d/debian.sources ENV DEBIAN_FRONTEND=noninteractive -ENV TZ=US/Pacific +ENV TZ=Asia/Shanghai RUN apt update && apt install -yq --no-install-recommends \ build-essential \ ca-certificates \ curl \ git \ + gnupg \ lsof \ make \ unzip \ @@ -32,27 +38,29 @@ ENV DART_SDK=/usr/lib/dart ENV PATH=$DART_SDK/bin:$PATH RUN set -eu; \ case "$(dpkg --print-architecture)_${DART_CHANNEL}" in \ + # BEGIN dart-sha amd64_stable) \ - DART_SHA256="cccd5300faa5a9abce12a5f77586e26350028cea82bb4ff8eeb55641b58a2e1d"; \ + DART_SHA256="4342ba274a4e9f8057079cf9de43b1c7bdb002016ad538313e8ebe942b61bba8"; \ SDK_ARCH="x64";; \ arm64_stable) \ - DART_SHA256="2c8eeaf0d3da60c4e14beec45ce3b39aca754f71b9fa3fb0c635ee28d6f44708"; \ + DART_SHA256="0f0e19c276c99fa3efd6428ea4bef1502f742f2a1f9772959637eec775c10ba0"; \ SDK_ARCH="arm64";; \ amd64_beta) \ - DART_SHA256="e3bdf39358dda7f0fd02b25d4d4539536fff53b4ab257da31a5fbbe42edc28c9"; \ + DART_SHA256="b3aa85b15bd13d619ba924524d5c7f082dc256a062ad34fe12ec824c9f05c2b3"; \ SDK_ARCH="x64";; \ arm64_beta) \ - DART_SHA256="7e7c2d1d4c8c8a6a47d916f422ddad2d5497307a147fa860b7b063ffdd162939"; \ + DART_SHA256="b7644435c8acf1e73da3f1ce16889b7222fbab37a75111aff225422a1cc61cab"; \ SDK_ARCH="arm64";; \ amd64_dev) \ - DART_SHA256="53368087f4c191d8b55338d13c32a70bf6cbfb0a99b6b4d86e53cb366bfce446"; \ + DART_SHA256="ae283eec0aa6e044064a79fc524af3dffec0543c48488538fc1a01a1fae7567b"; \ SDK_ARCH="x64";; \ arm64_dev) \ - DART_SHA256="474a251dfa7f6ba41f68d889b774569c4d2da5b4262f0c48fa53424e5b42f200"; \ + DART_SHA256="99153759fe1edbc5c1c6a8c5e5164fad11671eed8a8899bf127a17412b701172"; \ SDK_ARCH="arm64";; \ + # END dart-sha esac; \ SDK="dartsdk-linux-${SDK_ARCH}-release.zip"; \ - BASEURL="https://storage.googleapis.com/dart-archive/channels"; \ + BASEURL="https://storage.flutter-io.cn/dart-archive/channels"; \ URL="$BASEURL/$DART_CHANNEL/release/$DART_VERSION/sdk/$SDK"; \ curl -fsSLO "$URL"; \ echo "$DART_SHA256 *$SDK" | sha256sum --check --status --strict - || (\ @@ -78,21 +86,13 @@ CMD ["./tool/test.sh"] # ============== NODEJS INSTALL ============== FROM dart as node -RUN set -eu; \ - NODE_PPA="node_ppa.sh"; \ - NODE_SHA256=4ef190086f051a5242b8f9e7dff891d94c72bd484672d4a962f7189556977994; \ - curl -fsSL https://deb.nodesource.com/setup_lts.x -o "$NODE_PPA"; \ - echo "$NODE_SHA256 $NODE_PPA" | sha256sum --check --status --strict - || (\ - echo -e "\n\nNODE CHECKSUM FAILED! Run tool/fetch-node-ppa-sum.sh for updated values.\n\n" && \ - rm "$NODE_PPA" && \ - exit 1 \ - ); \ - sh "$NODE_PPA" && rm "$NODE_PPA"; \ - apt-get update -q && apt-get install -yq --no-install-recommends \ - nodejs \ - && rm -rf /var/lib/apt/lists/* -# Ensure latest NPM -RUN npm install -g npm + +RUN mkdir -p /etc/apt/keyrings \ + && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \ + && echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list \ + && apt-get update -yq \ + && apt-get install nodejs -yq \ + && npm install -g npm # Ensure latest npm # ============== DEV/JEKYLL SETUP ============== @@ -106,7 +106,8 @@ RUN BUNDLE_WITHOUT="test production" bundle install --jobs=4 --retry=2 ENV NODE_ENV=development COPY package.json package-lock.json ./ -RUN npm install +RUN npm install -g firebase-tools@12.8.1 +RUN npm ci COPY ./ ./ @@ -137,7 +138,7 @@ CMD ["make", "emulate"] # ============== BUILD PROD JEKYLL SITE ============== -FROM node AS build +FROM node as build WORKDIR /app ENV JEKYLL_ENV=production @@ -147,7 +148,7 @@ RUN BUNDLE_WITHOUT="test development" bundle install --jobs=4 --retry=2 --quiet ENV NODE_ENV=production COPY package.json package-lock.json ./ -RUN npm install +RUN npm ci COPY ./ ./ @@ -164,4 +165,10 @@ RUN tool/translator/build.sh # ============== DEPLOY to FIREBASE ============== FROM build as deploy +# RUN npm install -g firebase-tools@12.8.1 +# ARG FIREBASE_TOKEN +# ENV FIREBASE_TOKEN=$FIREBASE_TOKEN +# ARG FIREBASE_PROJECT=default +# ENV FIREBASE_PROJECT=$FIREBASE_PROJECT +# RUN [[ -z "$FIREBASE_TOKEN" ]] && echo "FIREBASE_TOKEN is required for container deploy!" RUN make deploy-ci diff --git a/Gemfile b/Gemfile index dd3d73731..5256034ad 100644 --- a/Gemfile +++ b/Gemfile @@ -1,6 +1,6 @@ source "https://rubygems.org" -gem 'activesupport', '~> 7.0.6' +gem 'activesupport', '~> 7.1.2' gem 'jekyll', '4.3.2' gem 'jekyll-sass-converter', '~> 3.0.0' gem 'kramdown-parser-gfm' diff --git a/Gemfile.lock b/Gemfile.lock index 1a3cac039..69a17a29a 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,15 +1,25 @@ GEM remote: https://rubygems.org/ specs: - activesupport (7.0.6) + activesupport (7.1.2) + base64 + bigdecimal concurrent-ruby (~> 1.0, >= 1.0.2) + connection_pool (>= 2.2.5) + drb i18n (>= 1.6, < 2) minitest (>= 5.1) + mutex_m tzinfo (~> 2.0) - addressable (2.8.4) + addressable (2.8.5) public_suffix (>= 2.0.2, < 6.0) + base64 (0.2.0) + bigdecimal (3.1.4) colorator (1.1.0) concurrent-ruby (1.2.2) + connection_pool (2.4.1) + drb (2.2.0) + ruby2_keywords em-websocket (0.5.3) eventmachine (>= 0.12.9) http_parser.rb (~> 0) @@ -18,9 +28,9 @@ GEM forwardable-extended (~> 2.5) ffi (1.15.5) forwardable-extended (2.6.0) - google-protobuf (3.23.2) - google-protobuf (3.23.2-aarch64-linux) - google-protobuf (3.23.2-x86_64-linux) + google-protobuf (3.24.3) + google-protobuf (3.24.3-aarch64-linux) + google-protobuf (3.24.3-x86_64-linux) http_parser.rb (0.8.0) i18n (1.14.1) concurrent-ruby (~> 1.0) @@ -59,32 +69,34 @@ GEM rb-fsevent (~> 0.10, >= 0.10.3) rb-inotify (~> 0.9, >= 0.9.10) mercenary (0.4.0) - mini_portile2 (2.8.2) - minitest (5.18.1) - nokogiri (1.15.2) + mini_portile2 (2.8.4) + minitest (5.20.0) + mutex_m (0.2.0) + nokogiri (1.15.4) mini_portile2 (~> 2.8.2) racc (~> 1.4) - nokogiri (1.15.2-aarch64-linux) + nokogiri (1.15.4-aarch64-linux) racc (~> 1.4) - nokogiri (1.15.2-x86_64-linux) + nokogiri (1.15.4-x86_64-linux) racc (~> 1.4) pathutil (0.16.2) forwardable-extended (~> 2.6) - public_suffix (5.0.1) - racc (1.7.0) + public_suffix (5.0.3) + racc (1.7.1) rake (13.0.6) rb-fsevent (0.11.2) rb-inotify (0.10.1) ffi (~> 1.0) - rexml (3.2.5) - rouge (4.1.2) + rexml (3.2.6) + rouge (4.1.3) + ruby2_keywords (0.0.5) safe_yaml (1.0.5) - sass-embedded (1.63.2) + sass-embedded (1.67.0) google-protobuf (~> 3.23) - rake (>= 10.0.0) - sass-embedded (1.63.2-aarch64-linux-gnu) + rake (>= 13.0.0) + sass-embedded (1.67.0-aarch64-linux-gnu) google-protobuf (~> 3.23) - sass-embedded (1.63.2-x86_64-linux-gnu) + sass-embedded (1.67.0-x86_64-linux-gnu) google-protobuf (~> 3.23) terminal-table (3.0.2) unicode-display_width (>= 1.1.1, < 3) @@ -99,7 +111,7 @@ PLATFORMS x86_64-linux DEPENDENCIES - activesupport (~> 7.0.6) + activesupport (~> 7.1.2) jekyll (= 4.3.2) jekyll-sass-converter (~> 3.0.0) jekyll-toc (~> 0.18.0) @@ -108,4 +120,4 @@ DEPENDENCIES webrick BUNDLED WITH - 2.4.13 + 2.4.19 diff --git a/Makefile b/Makefile index dfff69d42..460ed02df 100644 --- a/Makefile +++ b/Makefile @@ -58,14 +58,26 @@ setup: --build-arg DART_CHANNEL=${DART_CHANNEL} # Serve the Jekyll site with livereload and incremental builds +# Tip: livereload is not supported serve: - bundle exec jekyll serve \ - --host ${JEKYLL_SITE_HOST} \ - --port ${JEKYLL_SITE_PORT} \ +# bundle exec jekyll serve \ +# --host ${JEKYLL_SITE_HOST} \ +# --port ${JEKYLL_SITE_PORT} \ +# --config _config.yml,_config_dev.yml \ +# --livereload \ +# --incremental \ +# --trace + bundle exec jekyll clean + bundle exec jekyll build \ --config _config.yml,_config_dev.yml \ - --livereload \ --incremental \ --trace + bash tool/translator/build.sh + bundle exec jekyll serve \ + --host ${JEKYLL_SITE_HOST} \ + --port ${JEKYLL_SITE_PORT} \ + --trace\ + --skip-initial-build # Run all tests inside a built container test: @@ -103,17 +115,26 @@ write-prod-robots: # Deploy locally deploy: - sh tool/translator/deploy-cn.sh + bash tool/translator/deploy-cn.sh ################## UTILS ################## -# Fetch SDK sums for current Dart SDKs by arch, Node PPA +# Fetch SDK sums for current Dart SDKs by arch # This outputs a bash case format to be copied to Dockerfile fetch-sums: - tool/fetch-dart-sdk-sums.sh \ + bash tool/fetch-dart-sdk-sums.sh \ --version ${DART_VERSION} \ --channel ${DART_CHANNEL} - tool/fetch-node-ppa-sum.sh + +# Check Dart sums pulls the set of Dart SDK SHA256 hashes +# and writes them to a temp file. +check-sums: + bash tool/check-dart-sdk.sh + +# Update Dart sums replaces the Dart SDK SHA256 hashes +# in the Dockerfile and deletes the temp file. +update-sums: + bash tool/update-dart-sdk.sh # Test the dev container with pure docker test-builds: @@ -127,4 +148,4 @@ test-builds: # Test stable run with volume TEST_CHANNEL =? stable test-run: - docker run --rm -it -v ${PWD}:/app ${BUILD_TAG}:${TEST_CHANNEL} bash \ No newline at end of file + docker run --rm -it -v ${PWD}:/app ${BUILD_TAG}:${TEST_CHANNEL} bash diff --git a/README.md b/README.md index 44af89240..1994a765a 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ The https://dart.dev site, built with [Jekyll][] and hosted on [Firebase][]. -[We welcome contributions](CONTRIBUTING.md), +[We welcome contributions](CONTRIBUTING.md), and we're [first-timer friendly][first-timers]! ## Getting started @@ -19,7 +19,7 @@ To update this site, fork the repo, make your changes, and generate a pull request. For simple changes (such as to CSS and text), you probably don't need to build this site. Often you can make changes using the GitHub UI. -> **NOTE:** If you clone this repo locally, +> **NOTE:** If you clone this repo locally, > see the instructions below on cloning with its submodule. If your change involves code samples, adds/removes pages, or affects navigation, @@ -34,239 +34,235 @@ If you want or need to build, follow the steps below. > or [file an issue](https://github.com/dart-lang/site-www/issues/new?title=README%20issue) > (or both). - ## Before you build this site -For changes beyond simple text and CSS tweaks, +For changes beyond simple text and CSS tweaks, we recommend building the site. ### 1. Get the prerequisites Install the following tools, if you don't have them already: -- **bash**, the Bourne shell. - These instructions assume you're using `bash`, +- **bash**, the Bourne shell. + These instructions assume you're using `bash`, and setup might not work if you use another shell. -- **GNU Make**. +- **GNU Make**. On Windows the easiest way to install Make is `choco install make` - using command prompt or powershell as an admin. + using command prompt or powershell as an admin. Other options include using a [subsystem][wsl]. -- **Docker**. - We use Docker for local dev, tests, and building the site. +- **Docker**. + We use Docker for local dev, tests, and building the site. Install it from https://docs.docker.com/get-docker/. -- **Firebase CLI**, for hosting the site locally. - One way to get this is to run `npm install -g firebase-tools`. - For full setup details, +- **Firebase CLI**, for hosting the site locally. + One way to get this is to run `npm install -g firebase-tools`. + For full setup details, read the [Firebase CLI documentation](https://firebase.google.com/docs/cli). ### 2. Clone this repo _and_ its submodules -> **Note:** This repo has git _submodules_, which affects how you clone it. +> **Note:** This repo has git _submodules_, which affects how you clone it. > The GitHub documentation has general help on [forking][] and [cloning][] repos. -If you're not a member of the Dart organization, -we recommend you **create a fork** of this repo under your own account, -and then submit a PR from that fork. +If you're not a member of the Dart organization, +we recommend you **create a fork** of this repo under your own account, +and then submit a PR from that fork. -Once you have a fork (or you're a Dart org member), +Once you have a fork (or you're a Dart org member), _choose one_ of the following submodule-cloning techniques: - Clone the repo and its submodule at the same time using the `--recurse-submodules` option: - ```bash + + ```terminal $ git clone --recurse-submodules https://github.com/dart-lang/site-www.git ``` *OR* - -- If you've already cloned the repo without its submodule, + +- If you've already cloned the repo without its submodule, then run this command from the repo root: - ```bash + + ```terminal $ git submodule update --init --recursive ``` -> **Note:** At any time during development +> **Note:** At any time during development > you can use the `git submodule` command to refresh submodules: -> ```bash +> +> ```terminal > $ git pull; git submodule update --init --recursive > ``` - ## Setting up your local environment and serve changes -1. _Optional:_ After cloning the repo and its submodules, +1. _Optional:_ After cloning the repo and its submodules, create a branch for your changes: - ```bash + + ```terminal $ git checkout -b ``` - -2. If the Docker Desktop application isn't already running on your machine, - start it. Look for the Docker status icon: if it has an exclamation + +2. If the Docker Desktop application isn't already running on your machine, + start it. Look for the Docker status icon: if it has an exclamation point (`!`), then update Docker Desktop before proceeding. 3. Run the initial local setup command: - ```bash + + ```terminal $ make setup ``` 4. Serve the site locally (via `docker-compose`): - ```bash + + ```terminal $ make up ``` - The site is generated, and then the development server runs in the + + The site is generated, and then the development server runs in the Docker container, with the generated `_site` directory visible locally as a mirrored volume from inside the container. 5. View your changes in the browser by navigating to `http://localhost:4000`. - > **Note:** Unless you're editing files under `site-shared`, - > you can safely ignore `ERROR: directory is already being watched` messages. + > **Note:** Unless you're editing files under `site-shared`, + > you can safely ignore `ERROR: directory is already being watched` messages. > For details, see [#1363](https://github.com/flutter/website/issues/1363). -6. Make your changes to the local repo. +6. Make your changes to the local repo. - The site will rebuild and the browser will autoreload to reflect the changes. + The site will rebuild and the browser will autoreload to reflect the changes. - > **Tip:** If you aren't seeing the changes you expect (e.g. src/_data), - > `ctrl-C` out of your running dev server and rebuild the site from scratch + > **Tip:** If you aren't seeing the changes you expect (e.g. src/_data), + > Ctrl + C out of your running dev server and rebuild the site from scratch > using the following commands: - > ```bash + > + > ```terminal > $ make down && make clean && make up > ``` - 7. Commit your changes to the branch and submit your PR. > See [Pre-push site checks](#pre-push-site-checks) 8. When you've finished developing, shut down the Docker container: - ```bash + + ```terminal $ make down ``` - -> **Tip:** To find additional commands, read the [Makefile][]. -> For example, if you need to debug the Docker setup, + +> **Tip:** To find additional commands, read the [Makefile][]. +> For example, if you need to debug the Docker setup, > you can run: -> ```bash +> +> ```terminal > $ make run > ``` - ## Pre-push site checks ### Checking documentation and example code -If you've made changes to this site's documentation and/or example code, +If you've made changes to this site's documentation and/or example code, and committed locally, then run the following command before pushing your work: -```bash +```terminal # Enter a running Docker container shell -make run +$ make run # Check/validate example code -tool/test.sh +$ tool/test.sh # Check links for 404 errors -tool/check-links.sh +$ tool/check-links.sh ``` -If these scripts report errors or warnings, -then address those issues and rerun the above commands. +If these scripts report errors or warnings, +then address those issues and rerun the above commands. Otherwise, you can push your changes. - ## Deploying to a staging site You can deploy your local edits to a personal Firebase hosting staging site as follows: -1. If you don't already have a Firebase project, - - - Navigate to the [Firebase Console](https://console.firebase.google.com) +1. If you don't already have a Firebase project, + + - Navigate to the [Firebase Console](https://console.firebase.google.com) and create your own Firebase project (for example, `dart-dev-staging`). - Head back to your local repo shell and verify that you are logged in. - ```bash + + ```terminal $ firebase login ``` - Ensure that your project exists and activate that project: - ```bash + + ```terminal $ firebase projects:list $ firebase use ``` - + 1. Build the site via Docker: - ```bash + + ```terminal $ make build ``` - This will build the site and copy it to your local `_site` directory. - If that directory previously existed, it will be replaced. + This will build the site and copy it to your local `_site` directory. + If that directory previously existed, it will be replaced. 1. Deploy to your activated Firebase project's default hosting site: - ```bash + + ```terminal $ FIREBASE_PROJECT= make deploy ``` - > **TIP:** Add your `FIREBASE_PROJECT` env var to your `.env` file + > **TIP:** Add your `FIREBASE_PROJECT` env var to your `.env` file > and it will overwrite the default every time you deploy without specifying. -1. Navigate to your PR on GitHub and update it with the location of +1. Navigate to your PR on GitHub and update it with the location of the staged version, the names of your reviewers, and so on. ## Creating and/or editing DartPad example code -Most of the code used to create [DartPad][] examples is hosted on GitHub. +Most of the code used to create [DartPad][] examples is hosted on GitHub. However, this repo also contains some `*.dart` files responsible for DartPad example code. -# Refresh DartPad HTML tooltips - -Files that require DartPad HTML to be manually updated -include instructions at the top that specify running: - -```bash -$ tool/create_code_with_tooltips.dart -``` - -Follow the instructions in those files to refresh the appropriate code. - ### DartPad picker -The DartPad example picker must be manually compiled if changes are made. +The DartPad example picker must be manually compiled if changes are made. This will regenerate the associated JavaScript file in `src/assets/dash/js`: -```bash +```terminal $ tool/compile.sh ``` - ## Dockerfile Maintenance ### Dart SDK and Node PPA Checksum values -Since both the Dart SDK and Node PPA `curl` remote files, -it's important to verify checksum values. -Both installs use `latest` and `lts` respectively, -so these files may be periodically updated. -When this happens, +Since the Dart SDK setup fetches remote files, +it's important to verify checksum values. +Both installs use `latest` and `lts` respectively, +so these files may be periodically updated. +When this happens, local checksums may fail and **This will break the Docker/Compose setup/build**. -You will see the relevant output in your shell e.g. `DART CHECKSUM FAILED!...`. +You will see the relevant output in your shell e.g. `DART CHECKSUM FAILED!...`. When this happens, run the following command: -```bash -make fetch-sums +```terminal +$ make fetch-sums ``` -This command will output the updated checksum values for both Node and Dart, -and that output will be formatted similar -or the same as what is currently in the Dockerfile. -Copy this output and replace the relevant install code in the Dockerfile, -then rerun your setup/build again. - +This command will output the updated checksum values for Dart, +and that output will be formatted similar +or the same as what is currently in the Dockerfile. +Copy this output and replace the relevant install code in the Dockerfile, +then rerun your setup/build again. [Build Status SVG]: https://github.com/dart-lang/site-www/workflows/build/badge.svg [OpenSSF Scorecard SVG]: https://api.securityscorecards.dev/projects/github.com/dart-lang/site-www/badge diff --git a/_config.yml b/_config.yml index 6190fb26d..9bd1c719d 100644 --- a/_config.yml +++ b/_config.yml @@ -1,14 +1,16 @@ # Site settings title: Dart -description: Dart is a client-optimized language for developing fast apps on any platform. +description: >- + Dart is a client-optimized language for developing fast apps on any platform. url: https://dart.cn dev-url: https://debug.dart.cn repo: this: https://github.com/cfug/dart.cn - shared: &repo-shared https://github.com/dart-lang/site-shared -branch: master + shared: https://github.com/dart-lang/site-shared +branch: main port: 4000 source: src + strict_front_matter: true liquid: error_mode: strict @@ -16,7 +18,6 @@ liquid: future: true # In support of https://github.com/dart-lang/site-www/issues/1111 sass: sass_dir: _sass - cache: false style: compressed load_paths: - ../node_modules/bootstrap-scss @@ -25,7 +26,7 @@ plugins: toc: min_level: 2 max_level: 3 - no_toc_section_class: no_toc_section # ignore if in no_toc_section element + no_toc_section_class: no_toc_section dart-site: '' @@ -40,20 +41,10 @@ dartpad: https://dartpad.cn dart-api: https://api.dart.cn flutter-api: https://api.flutter-io.cn news: https://news.dartlang.org +announce: https://groups.google.com/a/dartlang.org/g/announce show_banner: true -collections: - articles: - output: true - permalink: /articles/:path - tutorials: - output: true - permalink: /tutorials/:path - guides: - output: true - permalink: /guides/:path - defaults: - scope: path: '' diff --git a/_config_dev.yml b/_config_dev.yml index 4cd7fb644..e805d35e5 100644 --- a/_config_dev.yml +++ b/_config_dev.yml @@ -1,9 +1,6 @@ # Site settings for development mode -# url: https://dartlang-org-dev.firebaseapp.com -# url: https://dartlang-org-staging-0.firebaseapp.com # Dev url inside Docker container -url: http://0.0.0.0:4000 +url: http://127.0.0.1:4000 sass: - cache: true - style: extended \ No newline at end of file + style: extended diff --git a/_config_now.yml b/_config_now.yml deleted file mode 100644 index 7572b1b18..000000000 --- a/_config_now.yml +++ /dev/null @@ -1,6 +0,0 @@ -# Fixed time stamp (useful when comparing generated site versions) -now: 2018-07-01 12:34:56 - -assets: - digest: false - source_maps: true diff --git a/examples/README.md b/examples/README.md index 99506c5b4..4de01987f 100644 --- a/examples/README.md +++ b/examples/README.md @@ -10,7 +10,7 @@ and more. Site-www specific information is given below. Change directory into the example's folder and run Dart commands there. For example: -```console +```terminal $ cd examples/misc $ dart pub get $ dart analyze . @@ -21,7 +21,7 @@ $ dart analyze . Change directory into the example's folder and run Dart commands there. For example: -```console +```terminal $ cd examples/misc $ dart pub get $ dart test # Run VM tests diff --git a/examples/analysis/pubspec.yaml b/examples/analysis/pubspec.yaml index f0e00b04c..5a545cd86 100644 --- a/examples/analysis/pubspec.yaml +++ b/examples/analysis/pubspec.yaml @@ -2,10 +2,10 @@ name: examples description: dart.dev example code. environment: - sdk: ^3.0.0 + sdk: ^3.1.0 dependencies: examples_util: {path: ../util} dev_dependencies: - lints: ^2.1.0 + lints: ^3.0.0 diff --git a/examples/analysis_alt/pubspec.yaml b/examples/analysis_alt/pubspec.yaml index 4407f3cb0..e28f11ce8 100644 --- a/examples/analysis_alt/pubspec.yaml +++ b/examples/analysis_alt/pubspec.yaml @@ -2,7 +2,7 @@ name: examples description: dart.dev example code. environment: - sdk: ^3.0.0 + sdk: ^3.1.0 dev_dependencies: - lints: ^2.1.0 + lints: ^3.0.0 diff --git a/examples/analysis_options.yaml b/examples/analysis_options.yaml index a8e15a216..fae8e9f82 100644 --- a/examples/analysis_options.yaml +++ b/examples/analysis_options.yaml @@ -12,11 +12,8 @@ linter: - always_declare_return_types - cancel_subscriptions - close_sinks - - collection_methods_unrelated_type - combinators_ordering - comment_references - - dangling_library_doc_comments - - implicit_call_tearoffs - invalid_case_patterns - library_annotations - one_member_abstracts @@ -28,12 +25,8 @@ linter: - test_types_in_equals - throw_in_finally - type_annotate_public_apis - - type_literal_in_constant_pattern - unawaited_futures - unnecessary_breaks - unnecessary_library_directive - unnecessary_null_aware_operator_on_extension_on_nullable - - unnecessary_to_list_in_spreads - use_enums - - use_string_in_part_of_directives - - use_super_parameters diff --git a/examples/async_await/pubspec.yaml b/examples/async_await/pubspec.yaml index 0ae0d22e2..898205d9d 100644 --- a/examples/async_await/pubspec.yaml +++ b/examples/async_await/pubspec.yaml @@ -2,11 +2,11 @@ name: async_await description: dart.dev example code. environment: - sdk: ^3.0.0 + sdk: ^3.1.0 dependencies: examples_util: {path: ../util} dev_dependencies: - lints: ^2.1.0 - test: ^1.24.2 + lints: ^3.0.0 + test: ^1.24.6 diff --git a/examples/build_runner_usage/pubspec.yaml b/examples/build_runner_usage/pubspec.yaml index 1d7df6835..b4082079c 100644 --- a/examples/build_runner_usage/pubspec.yaml +++ b/examples/build_runner_usage/pubspec.yaml @@ -2,10 +2,10 @@ name: build_runner_usage description: dart.dev build_runner example code. environment: - sdk: ^3.0.0 + sdk: ^3.1.0 dev_dependencies: args: ^2.4.0 - build_runner: ^2.4.1 - build_test: ^2.1.7 - lints: ^2.1.0 + build_runner: ^2.4.6 + build_test: ^2.2.0 + lints: ^3.0.0 diff --git a/examples/cli/analysis_options.yaml b/examples/cli/analysis_options.yaml new file mode 100644 index 000000000..5e2133eb6 --- /dev/null +++ b/examples/cli/analysis_options.yaml @@ -0,0 +1 @@ +include: ../analysis_options.yaml diff --git a/examples/misc/bin/dcat/dcat.dart b/examples/cli/bin/dcat.dart similarity index 51% rename from examples/misc/bin/dcat/dcat.dart rename to examples/cli/bin/dcat.dart index 4b5b2b1aa..ab45a577c 100644 --- a/examples/misc/bin/dcat/dcat.dart +++ b/examples/cli/bin/dcat.dart @@ -1,16 +1,14 @@ -// Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file -// for details. All rights reserved. Use of this source code is governed by a -// BSD-style license that can be found in the LICENSE file. - -// IMPORTANT NOTE: -// 1. If you change this file, ensure that the associated tooltip data remains -// valid (*_tooltips.html). -// 2. Regenerate the HTML version of this sample, by running -// tool/create_code_with_tooltips.dart -// 3. To generate the DartPad version: (1) delete lines containing only tip -// instructions. (2) Trim //!foo markers from the end of the remaining lines, -// e.g., using this Perl regexp: / ?\/\/!.*//g +/// Simple implementation of the *nix cat utility. +/// +/// Usage: `dart run dcat.dart [-n] patterns files` +/// +/// `dcat` reads `files` sequentially, writing them to standard output. +/// The file operands are processed in command-line order. +/// If `files` is absent, `dcat` reads from the standard input until `EOF`. +/// Unlike the *nix `cat`, `dcat` does not support single dash ('-') arguments. +library; +// #docregion dcat-app import 'dart:convert'; import 'dart:io'; @@ -18,22 +16,11 @@ import 'package:args/args.dart'; const lineNumber = 'line-number'; -/// Simple implementation of the *nix cat utility. //!web-only -/// //!web-only -/// Usage: dart run dcat.dart [-n] patterns files //!web-only -/// //!web-only -/// `dcat` reads `files` sequentially, writing them to standard output. The //!web-only -/// file operands are processed in command-line order. //!web-only -/// If `files` is absent, `dcat` reads from the standard input until `EOF`. //!web-only -/// //!web-only -/// Unlike the *nix `cat`, `dcat` does not support single dash ('-') arguments. //!web-only -//!tip("List arguments") // #docregion arg-processing void main(List arguments) { - exitCode = 0; // presume success + exitCode = 0; // Presume success final parser = ArgParser()..addFlag(lineNumber, negatable: false, abbr: 'n'); - //!tip("parser.parse(arguments)") ArgResults argResults = parser.parse(arguments); final paths = argResults.rest; @@ -41,12 +28,10 @@ void main(List arguments) { } // #enddocregion arg-processing -//!tip("async") Future dcat(List paths, {bool showLineNumbers = false}) async { if (paths.isEmpty) { // No files provided as arguments. Read from stdin and print each line. // #docregion pipe - //!tip("stdin.pipe(stdout)") //!tip("await") await stdin.pipe(stdout); // #enddocregion pipe } else { @@ -54,13 +39,9 @@ Future dcat(List paths, {bool showLineNumbers = false}) async { for (final path in paths) { var lineNumber = 1; final lines = utf8.decoder - //!tip("openRead()") //!tip("File(path)") .bind(File(path).openRead()) - //!tip("transform(const LineSplitter())") .transform(const LineSplitter()); - //!tip("try") try { - //!tip("await for (final line in lines)") await for (final line in lines) { // #docregion showLineNumbers if (showLineNumbers) { @@ -69,7 +50,6 @@ Future dcat(List paths, {bool showLineNumbers = false}) async { stdout.writeln(line); // #enddocregion showLineNumbers } - //!tip("catch") } catch (_) { await _handleError(path); } @@ -78,14 +58,15 @@ Future dcat(List paths, {bool showLineNumbers = false}) async { } } -// #docregion _handleError +// #docregion handle-error Future _handleError(String path) async { - //!tip("await FileSystemEntity.isDirectory(path)") - // #docregion await-FileSystemEntity + // #docregion await-entity if (await FileSystemEntity.isDirectory(path)) { stderr.writeln('error: $path is a directory'); } else { - exitCode = 2; //!tip("exitCode = 2") + exitCode = 2; } - // #enddocregion await-FileSystemEntity + // #enddocregion await-entity } +// #enddocregion handle-error +// #enddocregion dcat-app diff --git a/examples/cli/bin/dcat_stdin.dart b/examples/cli/bin/dcat_stdin.dart new file mode 100644 index 000000000..bf21dc4ff --- /dev/null +++ b/examples/cli/bin/dcat_stdin.dart @@ -0,0 +1,7 @@ +import 'dart:io'; + +void main() { + stdout.writeln('Type something'); + final input = stdin.readLineSync(); + stdout.writeln('You typed: $input'); +} diff --git a/examples/cli/dart_test.yaml b/examples/cli/dart_test.yaml new file mode 100644 index 000000000..107d8a335 --- /dev/null +++ b/examples/cli/dart_test.yaml @@ -0,0 +1 @@ +include: ../dart_test_base.yaml diff --git a/examples/misc/lib/tutorial/cmdline.dart b/examples/cli/lib/cmdline.dart similarity index 100% rename from examples/misc/lib/tutorial/cmdline.dart rename to examples/cli/lib/cmdline.dart diff --git a/examples/cli/pubspec.yaml b/examples/cli/pubspec.yaml new file mode 100644 index 000000000..79be688c7 --- /dev/null +++ b/examples/cli/pubspec.yaml @@ -0,0 +1,12 @@ +name: cli_examples +description: Examples for CLI tutorials on dart.dev + +environment: + sdk: ^3.1.0 + +dependencies: + args: ^2.4.2 + +dev_dependencies: + lints: ^3.0.0 + test: ^1.24.8 diff --git a/examples/cli/test/dcat_test.dart b/examples/cli/test/dcat_test.dart new file mode 100644 index 000000000..202081fb0 --- /dev/null +++ b/examples/cli/test/dcat_test.dart @@ -0,0 +1,42 @@ +import 'dart:convert'; +import 'dart:io'; + +import 'package:test/test.dart'; + +void main() { + const pathToQuotes = 'test_data/quote.txt'; + + test('dcat', () async { + final procResult = await Process.run('dart', [ + 'run', + '--enable-asserts', + 'bin/dcat.dart', + '-n', + pathToQuotes, + ]); + expect( + procResult.stdout, + allOf( + startsWith('1'), // Line number + contains('Dr. Seuss'), + endsWith('Nietzsche\n'), + ), + ); + }); + + test('dcat1', () async { + const greeting = '¡Hola Dash!'; + final process = await Process.start('dart', [ + 'run', + '--enable-asserts', + 'bin/dcat_stdin.dart', + ]); + process.stdin.writeln(greeting); + final output = await process.stdout.transform(const Utf8Decoder()).join(''); + final errors = await process.stderr.transform(const Utf8Decoder()).join(''); + + expect(await process.exitCode, 0); + expect(output, contains('You typed: $greeting')); + expect(errors, isEmpty); + }); +} diff --git a/examples/cli/test_data/quote.txt b/examples/cli/test_data/quote.txt new file mode 100644 index 000000000..561f56eb6 --- /dev/null +++ b/examples/cli/test_data/quote.txt @@ -0,0 +1,5 @@ +Be yourself. Everyone else is taken. -Oscar Wilde +Don't cry because it's over, smile because it happened. -Dr. Seuss +You only live once, but if you do it right, once is enough. -Mae West +# This is a comment line. +That which does not kill us makes us stronger. -Nietzsche diff --git a/examples/concurrency/pubspec.yaml b/examples/concurrency/pubspec.yaml index 68f750003..6dac852f2 100644 --- a/examples/concurrency/pubspec.yaml +++ b/examples/concurrency/pubspec.yaml @@ -4,8 +4,8 @@ version: 0.0.1 publish_to: none environment: - sdk: ^3.0.0 + sdk: ^3.1.0 dev_dependencies: - lints: ^2.1.0 - test: ^1.24.2 + lints: ^3.0.0 + test: ^1.24.6 diff --git a/examples/create_libraries/pubspec.yaml b/examples/create_libraries/pubspec.yaml index 70aab4b51..0bb10262a 100644 --- a/examples/create_libraries/pubspec.yaml +++ b/examples/create_libraries/pubspec.yaml @@ -3,8 +3,8 @@ description: dart.dev example code. version: 1.0.0 environment: - sdk: ^3.0.0 + sdk: ^3.1.0 dev_dependencies: - lints: ^2.1.0 - test: ^1.24.2 + lints: ^3.0.0 + test: ^1.24.6 diff --git a/examples/extension_methods/pubspec.yaml b/examples/extension_methods/pubspec.yaml index 5688bf183..a79180456 100644 --- a/examples/extension_methods/pubspec.yaml +++ b/examples/extension_methods/pubspec.yaml @@ -3,8 +3,8 @@ description: dart.dev example code. version: 1.0.0 environment: - sdk: ^3.0.0 + sdk: ^3.1.0 dev_dependencies: - lints: ^2.1.0 - test: ^1.24.2 + lints: ^3.0.0 + test: ^1.24.6 diff --git a/examples/fetch_data/pubspec.yaml b/examples/fetch_data/pubspec.yaml index c85f7a9dd..1dd4a92d2 100644 --- a/examples/fetch_data/pubspec.yaml +++ b/examples/fetch_data/pubspec.yaml @@ -3,10 +3,10 @@ description: Fetch data example version: 0.0.1 environment: - sdk: ^3.0.0 + sdk: ^3.1.0 dependencies: - http: ^0.13.5 + http: ^1.1.0 dev_dependencies: - lints: ^2.1.0 + lints: ^3.0.0 diff --git a/examples/futures/pubspec.yaml b/examples/futures/pubspec.yaml index e729a40f5..bf6319ad1 100644 --- a/examples/futures/pubspec.yaml +++ b/examples/futures/pubspec.yaml @@ -4,11 +4,11 @@ version: 0.0.1 publish_to: none environment: - sdk: ^3.0.0 + sdk: ^3.1.0 dependencies: examples_util: {path: ../util} dev_dependencies: - lints: ^2.1.0 - test: ^1.24.2 + lints: ^3.0.0 + test: ^1.24.6 diff --git a/examples/html/pubspec.yaml b/examples/html/pubspec.yaml index 8cad6e997..e2d252c1e 100644 --- a/examples/html/pubspec.yaml +++ b/examples/html/pubspec.yaml @@ -3,12 +3,9 @@ description: dart.dev example code. version: 0.0.1 environment: - sdk: ^3.0.0 - -dependencies: - html: any + sdk: ^3.1.0 dev_dependencies: - test: ^1.24.2 - lints: ^2.1.0 + lints: ^3.0.0 + test: ^1.24.6 examples_util: {path: ../util} diff --git a/examples/iterables/pubspec.yaml b/examples/iterables/pubspec.yaml index 5793637ef..579884a3a 100644 --- a/examples/iterables/pubspec.yaml +++ b/examples/iterables/pubspec.yaml @@ -2,9 +2,9 @@ name: iterables_examples description: dart.dev example code. environment: - sdk: ^3.0.0 + sdk: ^3.1.0 dev_dependencies: examples_util: {path: ../util} - lints: ^2.1.0 - test: ^1.24.2 + lints: ^3.0.0 + test: ^1.24.6 diff --git a/examples/language/lib/control_flow/branches.dart b/examples/language/lib/control_flow/branches.dart index d85eed9a0..5915f4d14 100644 --- a/examples/language/lib/control_flow/branches.dart +++ b/examples/language/lib/control_flow/branches.dart @@ -1,4 +1,4 @@ -// ignore_for_file: unused_local_variable +// ignore_for_file: unused_local_variable, dead_code, unreachable_switch_case class Point { final int x; @@ -142,9 +142,14 @@ dynamic miscDeclAnalyzedButNotTested() { } { + final pair = (1, 2); // #docregion guard switch (pair) { + case (int a, int b): + if (a > b) print('First element greater'); + // If false, prints nothing and exits the switch. case (int a, int b) when a > b: + // If false, prints nothing but proceeds to next case. print('First element greater'); case (int a, int b): print('First element not greater'); diff --git a/examples/language/lib/patterns/switch.dart b/examples/language/lib/patterns/switch.dart index d920d5b89..5ec3ca3b3 100644 --- a/examples/language/lib/patterns/switch.dart +++ b/examples/language/lib/patterns/switch.dart @@ -1,3 +1,5 @@ +// ignore_for_file: pattern_never_matches_value_type + class Rect { int width; int height; @@ -48,11 +50,13 @@ void main() { case 1: print('one'); - // Matches if the value of obj is between the constant values of 'first' and 'last'. + // Matches if the value of obj is between the + // constant values of 'first' and 'last'. case >= first && <= last: print('in range'); - // Matches if obj is a record with two fields, then assigns the fields to 'a' and 'b'. + // Matches if obj is a record with two fields, + // then assigns the fields to 'a' and 'b'. case (var a, var b): print('a = $a, b = $b'); diff --git a/examples/language/pubspec.yaml b/examples/language/pubspec.yaml index 7c735c4ed..2efd0bbfb 100644 --- a/examples/language/pubspec.yaml +++ b/examples/language/pubspec.yaml @@ -2,11 +2,11 @@ name: examples description: dart.dev example code. environment: - sdk: ^3.0.0 + sdk: ^3.1.0 dependencies: examples_util: { path: ../util } dev_dependencies: - lints: ^2.1.0 - test: ^1.24.2 + lints: ^3.0.0 + test: ^1.24.6 diff --git a/examples/misc/bin/dcat/dcat1.dart b/examples/misc/bin/dcat/dcat1.dart deleted file mode 100644 index 7e6d63fe3..000000000 --- a/examples/misc/bin/dcat/dcat1.dart +++ /dev/null @@ -1,12 +0,0 @@ -// Copyright (c) 2019, the Dart project authors. Please see the AUTHORS file -// for details. All rights reserved. Use of this source code is governed by a -// BSD-style license that can be found in the LICENSE file. - -// #docregion -import 'dart:io'; - -void main() { - stdout.writeln('Type something'); - final input = stdin.readLineSync(); - stdout.writeln('You typed: $input'); -} diff --git a/examples/misc/bin/dcat/dcat_tooltips.html b/examples/misc/bin/dcat/dcat_tooltips.html deleted file mode 100644 index fd7bf6e2e..000000000 --- a/examples/misc/bin/dcat/dcat_tooltips.html +++ /dev/null @@ -1,53 +0,0 @@ - - diff --git a/examples/misc/lib/effective_dart/design_good.dart b/examples/misc/lib/effective_dart/design_good.dart index a557a9af1..3a9b87d29 100644 --- a/examples/misc/lib/effective_dart/design_good.dart +++ b/examples/misc/lib/effective_dart/design_good.dart @@ -523,27 +523,6 @@ class Graph1 { //---------------------------------------------------------------------------- -class Control {} - -// #docregion mixin -mixin ClickableMixin implements Control { - bool _isDown = false; - - void click(); - - void mouseDown() { - _isDown = true; - } - - void mouseUp() { - if (_isDown) click(); - _isDown = false; - } -} -// #enddocregion mixin - -//---------------------------------------------------------------------------- - // #docregion one-member-abstract-class typedef Predicate = bool Function(E element); // #enddocregion one-member-abstract-class diff --git a/examples/misc/lib/language_tour/classes/point.dart b/examples/misc/lib/language_tour/classes/point.dart index 2cc39b36d..bf2ce7e12 100644 --- a/examples/misc/lib/language_tour/classes/point.dart +++ b/examples/misc/lib/language_tour/classes/point.dart @@ -11,13 +11,15 @@ class Point { final double x; final double y; + // #docregion class-with-distanceTo, named-constructor + Point(this.x, this.y); // #enddocregion class-with-distanceTo, named-constructor // Sets the x and y instance variables // before the constructor body runs. - // #docregion class-with-distanceTo, named-constructor - Point(this.x, this.y); // #enddocregion class-with-distanceTo, constructor-initializer + // #docregion named-constructor + // Named constructor Point.origin() : x = xOrigin, diff --git a/examples/misc/lib/language_tour/classes/point_alt.dart b/examples/misc/lib/language_tour/classes/point_alt.dart index dc6eb595c..d9cb09ea5 100644 --- a/examples/misc/lib/language_tour/classes/point_alt.dart +++ b/examples/misc/lib/language_tour/classes/point_alt.dart @@ -4,18 +4,14 @@ /// - A constructor initializing fields in the body "the long way" /// - A named constructor with initializers, and a print statement in the body. /// -// #docregion constructor-long-way +// #docregion idiomatic-constructor class Point { double x = 0; double y = 0; - Point(double x, double y) { - // See initializing formal parameters for a better way - // to initialize instance variables. - this.x = x; - this.y = y; - } - // #enddocregion constructor-long-way + // Generative constructor with initializing formal parameters: + Point(this.x, this.y); + // #enddocregion idiomatic-constructor // #docregion initializer-list // Initializer list sets instance variables before @@ -35,5 +31,5 @@ class Point { } // #enddocregion initializer-list-with-assert -// #docregion constructor-long-way +// #docregion idiomatic-constructor } diff --git a/examples/misc/lib/language_tour/classes/super_initializer_parameters.dart b/examples/misc/lib/language_tour/classes/super_initializer_parameters.dart index b8ef2f5f2..42c3c311e 100644 --- a/examples/misc/lib/language_tour/classes/super_initializer_parameters.dart +++ b/examples/misc/lib/language_tour/classes/super_initializer_parameters.dart @@ -24,7 +24,6 @@ class Vector3d extends Vector2d { // #docregion positional final double z; - // #enddocregion named // Forward the x and y parameters to the default super constructor like: // Vector3d(final double x, final double y, this.z) : super(x, y); Vector3d(super.x, super.y, this.z); diff --git a/examples/misc/pubspec.yaml b/examples/misc/pubspec.yaml index 0dd5bc42d..c7bc8ca9b 100644 --- a/examples/misc/pubspec.yaml +++ b/examples/misc/pubspec.yaml @@ -2,13 +2,13 @@ name: examples description: dart.dev example code. environment: - sdk: ^3.0.0 + sdk: ^3.1.0 dependencies: - args: ^2.3.0 - characters: ^1.2.1 + args: ^2.4.2 + characters: ^1.3.0 examples_util: { path: ../util } dev_dependencies: - lints: ^2.1.0 - test: ^1.24.2 + lints: ^3.0.0 + test: ^1.24.6 diff --git a/examples/misc/test/dcat_test.dart b/examples/misc/test/dcat_test.dart deleted file mode 100644 index fedc7e231..000000000 --- a/examples/misc/test/dcat_test.dart +++ /dev/null @@ -1,33 +0,0 @@ -import 'dart:convert'; -import 'dart:io'; - -import 'package:test/test.dart'; - -void main() { - const pathToQuotes = 'test_data/quote.txt'; - - test('dcat', () async { - final procResult = await Process.run( - 'dart', ['--enable-asserts', 'bin/dcat/dcat.dart', '-n', pathToQuotes]); - expect( - procResult.stdout, - allOf( - startsWith('1'), // Line number - contains('Dr. Seuss'), - endsWith('Nietzsche\n'), - )); - }); - - test('dcat1', () async { - const greeting = '¡Hola, Mundo!'; - final process = await Process.start( - 'dart', ['--enable-asserts', 'bin/dcat/dcat1.dart']); - process.stdin.writeln(greeting); - final output = await process.stdout.transform(Utf8Decoder()).join(''); - final errors = await process.stderr.transform(Utf8Decoder()).join(''); - - expect(await process.exitCode, 0); - expect(output, contains('You typed: $greeting')); - expect(errors, isEmpty); - }); -} diff --git a/examples/non_promotion/pubspec.yaml b/examples/non_promotion/pubspec.yaml index fd0737da2..2587cb5b7 100644 --- a/examples/non_promotion/pubspec.yaml +++ b/examples/non_promotion/pubspec.yaml @@ -3,7 +3,7 @@ description: dart.dev non-promotion examples. version: 0.0.1 environment: - sdk: ^3.0.0 + sdk: ^3.1.0 dev_dependencies: - lints: ^2.1.0 + lints: ^3.0.0 diff --git a/examples/null_safety_codelab/pubspec.yaml b/examples/null_safety_codelab/pubspec.yaml index 670d0872a..0d8825b08 100644 --- a/examples/null_safety_codelab/pubspec.yaml +++ b/examples/null_safety_codelab/pubspec.yaml @@ -2,9 +2,9 @@ name: null_safety_codelab_examples description: dart.dev example code for null safety codelab environment: - sdk: ^3.0.0 + sdk: ^3.1.0 dev_dependencies: examples_util: {path: ../util} - lints: ^2.1.0 - test: ^1.24.2 + lints: ^3.0.0 + test: ^1.24.6 diff --git a/examples/type_system/lib/incorrect_animal.dart b/examples/type_system/lib/incorrect_animal.dart new file mode 100644 index 000000000..1d3fd128b --- /dev/null +++ b/examples/type_system/lib/incorrect_animal.dart @@ -0,0 +1,29 @@ +// ignore_for_file: unused_local_variable, unused_element +import 'animal.dart'; + +// #docregion chase-mouse +class Mouse extends Animal {/* ... */} + +class Cat extends Animal { + @override + // ignore: invalid_override + void chase(Mouse a) {/* ... */} +} +// #enddocregion chase-mouse + +void notTypeSafeChase() { + // #docregion would-not-be-type-safe + Animal a = Cat(); + a.chase(Alligator()); // Not type safe or feline safe. + // #enddocregion would-not-be-type-safe +} + +void invalidDynamicList() { + // #docregion invalid-dynamic-list + void main() { + // ignore: invalid_assignment + List foo = [Dog()]; // Error + List bar = [Dog(), Cat()]; // OK + } + // #enddocregion invalid-dynamic-list +} diff --git a/examples/type_system/pubspec.yaml b/examples/type_system/pubspec.yaml index 7fe3129e2..31eba0fc7 100644 --- a/examples/type_system/pubspec.yaml +++ b/examples/type_system/pubspec.yaml @@ -2,11 +2,11 @@ name: type_system_examples description: dart.dev type system examples. environment: - sdk: ^3.0.0 + sdk: ^3.1.0 dependencies: examples_util: {path: ../util} dev_dependencies: - lints: ^2.1.0 - test: ^1.24.2 + lints: ^3.0.0 + test: ^1.24.6 diff --git a/examples/util/pubspec.yaml b/examples/util/pubspec.yaml index 341825e57..6d9a48f08 100644 --- a/examples/util/pubspec.yaml +++ b/examples/util/pubspec.yaml @@ -3,10 +3,10 @@ description: dart.dev example utilities. version: 0.0.2 environment: - sdk: ^3.0.0 + sdk: ^3.1.0 dependencies: - test: ^1.24.2 + test: ^1.24.6 dev_dependencies: - lints: ^2.1.0 + lints: ^3.0.0 diff --git a/examples/vector_victor/pubspec.yaml b/examples/vector_victor/pubspec.yaml index fabd60d4a..4fc023c2f 100644 --- a/examples/vector_victor/pubspec.yaml +++ b/examples/vector_victor/pubspec.yaml @@ -4,14 +4,14 @@ version: 1.0.0 # homepage: https://www.example.com environment: - sdk: ^3.0.0 + sdk: ^3.1.0 # dependencies: # path: ^1.8.0 dev_dependencies: - lints: ^2.1.0 - test: ^1.24.2 + lints: ^3.0.0 + test: ^1.24.6 dependencies: vector_math: ^2.1.4 diff --git a/firebase.json b/firebase.json index c258d1d31..a221ab2cc 100644 --- a/firebase.json +++ b/firebase.json @@ -30,6 +30,7 @@ { "source": "/\\)", "destination": "/", "type": 301 }, { "source": "/angular{,/**}", "destination": "https://github.com/angulardart", "type": 301 }, { "source": "/api", "destination": "https://api.dart.dev", "type": 301 }, + { "source": "/articles", "destination": "https://medium.com/dartlang", "type": 301 }, { "source": "/articles/api-naming-guide{,/**}", "destination": "/effective-dart/design", "type": 301 }, { "source": "/articles/archive/dart-2", "destination": "/guides/language/evolution#dart-20", "type": 301 }, { "source": "/articles/archive/event-loop", "destination": "https://medium.com/dartlang/dart-asynchronous-programming-isolates-and-event-loops-bffc3e296a6a", "type": 301 }, @@ -55,12 +56,11 @@ { "source": "/articles/language/await-async", "destination": "/codelabs/async-await", "type": 301 }, { "source": "/articles/language/mixins", "destination": "/language/mixins", "type": 301 }, { "source": "/articles/language/optional-types", "destination": "/resources/faq#types", "type": 301 }, - { "source": "/articles/libraries", "destination": "/articles", "type": 301 }, + { "source": "/articles/libraries", "destination": "/guides/libraries/library-tour", "type": 301 }, { "source": "/articles/libraries/converters-and-codecs", "destination": "/articles/archive/converters-and-codecs", "type": 301 }, { "source": "/articles/libraries/dart-io", "destination": "/guides/libraries/library-tour#dartio", "type": 301 }, { "source": "/articles/libraries/zones", "destination": "/articles/archive/zones", "type": 301 }, - { "source": "/articles/m*{,/**}", "destination": "/articles", "type": 301 }, - { "source": "/articles/m1-language-changes{,/**}", "destination": "/guides/language/spec", "type": 301 }, + { "source": "/articles/m*{,/**}", "destination": "/guides/language/evolution", "type": 301 }, { "source": "/articles/mixins", "destination": "/language/mixins", "type": 301 }, { "source": "/articles/mocking-with-dart", "destination": "https://pub.dev/packages/mockito", "type": 301 }, { "source": "/articles/native-extensions-for-standalone-dart-vm", "destination": "/server/c-interop-native-extensions", "type": 301 }, @@ -79,6 +79,8 @@ { "source": "/books", "destination": "/resources/books", "type": 301 }, { "source": "/bug", "destination": "https://dartbug.com", "type": 301 }, { "source": "/bug/:rest*", "destination": "https://dartbug.com/:rest*", "type": 301 }, + { "source": "/cl", "destination": "https://dart-review.googlesource.com/q/status:open+-is:wip", "type": 301 }, + { "source": "/cl/:rest*", "destination": "https://dart-review.googlesource.com/c/sdk/+/:rest*", "type": 301 }, { "source": "/cloud{,/**}", "destination": "/server/google-cloud", "type": 301 }, { "source": "/codelabs/server{,/**}", "destination": "/tutorials/server/httpserver", "type": 301 }, { "source": "/code-of-conduct", "destination": "/community/code-of-conduct", "type": 301 }, @@ -156,10 +158,20 @@ { "source": "/go/false-secrets", "destination": "/tools/pub/pubspec#false_secrets", "type": 301 }, { "source": "/go/ffi", "destination": "/guides/libraries/c-interop", "type": 301 }, { "source": "/go/flutter-upper-bound-deprecation", "destination": "https://github.com/flutter/flutter/issues/68143", "type": 301 }, + { "source": "/go/non-promo-conflicting-getter", "destination": "/tools/non-promotion-reasons", "type": 301 }, + { "source": "/go/non-promo-conflicting-non-promotable-field", "destination": "/tools/non-promotion-reasons", "type": 301 }, + { "source": "/go/non-promo-conflicting-noSuchMethod-forwarder", "destination": "/tools/non-promotion-reasons", "type": 301 }, + { "source": "/go/non-promo-external-field", "destination": "/tools/non-promotion-reasons", "type": 301 }, + { "source": "/go/non-promo-field-promotion-unavailable", "destination": "/tools/non-promotion-reasons", "type": 301 }, + { "source": "/go/non-promo-non-field", "destination": "/tools/non-promotion-reasons", "type": 301 }, + { "source": "/go/non-promo-non-final-field", "destination": "/tools/non-promotion-reasons", "type": 301 }, { "source": "/go/non-promo-property", "destination": "/tools/non-promotion-reasons#property-or-this", "type": 301 }, + { "source": "/go/non-promo-public-field", "destination": "/tools/non-promotion-reasons", "type": 301 }, { "source": "/go/non-promo-this", "destination": "/tools/non-promotion-reasons#property-or-this", "type": 301 }, { "source": "/go/non-promo-write", "destination": "/tools/non-promotion-reasons#write", "type": 301 }, + { "source": "/go/null-safety-migration", "destination": "/null-safety/migration-guide", "type": 301 }, + { "source": "/go/package-discontinue", "destination": "/tools/pub/publishing#discontinue", "type": 301 }, { "source": "/go/package-retraction", "destination": "/tools/pub/publishing#retract", "type": 301 }, { "source": "/go/pub-cache", "destination": "/tools/pub/cmd/pub-cache", "type": 301 }, { "source": "/go/pubignore", "destination": "/tools/pub/publishing#what-files-are-published", "type": 301 }, @@ -173,6 +185,7 @@ { "source": "/googleapis", "destination": "https://github.com/dart-lang/googleapis", "type": 301 }, { "source": "/guides/get-started", "destination": "/overview", "type": 301 }, { "source": "/guides/language/analysis-options", "destination": "/tools/analysis", "type": 301 }, + { "source": "/guides/language/cheatsheet", "destination": "/language", "type": 301 }, { "source": "/guides/language/common-prob", "destination": "/guides/language/sound-problems", "type": 301 }, { "source": "/guides/language/concurrency", "destination": "/language/concurrency", "type": 301 }, { "source": "/guides/language/effective-dart", "destination": "/effective-dart", "type": 301 }, diff --git a/pubspec.yaml b/pubspec.yaml index 51b4a9aa7..28890d4d0 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -4,15 +4,13 @@ publish_to: none homepage: https://dart.dev environment: - sdk: ^3.0.1 + sdk: ^3.1.0 dev_dependencies: - build_runner: ^2.4.4 + build_runner: ^2.4.6 code_excerpt_updater: path: site-shared/packages/code_excerpt_updater code_excerpter: path: site-shared/packages/code_excerpter linkcheck: ^3.0.0 - lints: ^2.1.0 - logging: ^1.2.0 - path: ^1.8.3 + lints: ^3.0.0 diff --git a/site-shared b/site-shared index 992976e42..1eb779898 160000 --- a/site-shared +++ b/site-shared @@ -1 +1 @@ -Subproject commit 992976e4265a60ac6262e41c5a9c168a6db15b05 +Subproject commit 1eb779898ebf50063b36f565f4d95b5ed8f62d54 diff --git a/src/404.html b/src/404.html index 1b5af05bd..3f4201d11 100644 --- a/src/404.html +++ b/src/404.html @@ -2,7 +2,6 @@ layout: error title: "404: Page not found" description: "dart.dev's 404 page." -permalink: /404 sitemap: false ---
@@ -14,7 +13,7 @@

Page not found

- +
diff --git a/src/_articles/archive/images/both-queues.png b/src/_articles/archive/images/both-queues.png deleted file mode 100644 index e5bc24e84..000000000 Binary files a/src/_articles/archive/images/both-queues.png and /dev/null differ diff --git a/src/_articles/archive/images/scheduling-tasks.png b/src/_articles/archive/images/scheduling-tasks.png deleted file mode 100644 index e1d2665d9..000000000 Binary files a/src/_articles/archive/images/scheduling-tasks.png and /dev/null differ diff --git a/src/_articles/archive/images/test-annotated.png b/src/_articles/archive/images/test-annotated.png deleted file mode 100644 index b5a93deba..000000000 Binary files a/src/_articles/archive/images/test-annotated.png and /dev/null differ diff --git a/src/_articles/archive/images/test-queue-output.png b/src/_articles/archive/images/test-queue-output.png deleted file mode 100644 index f10a7dcbc..000000000 Binary files a/src/_articles/archive/images/test-queue-output.png and /dev/null differ diff --git a/src/_articles/index.md b/src/_articles/index.md deleted file mode 100644 index 1ca3d5712..000000000 --- a/src/_articles/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Articles -description: Read early articles about the Dart libraries. -toc: false ---- - -Read these articles for insight into the Dart libraries. -To find newer articles, see the -[Dart publication on medium.com.](https://medium.com/dartlang) - -
- {% assign articles = site.articles | where: 'categories', 'libraries' | sort: 'date' | reverse %} -
    - {% for article in articles %} -
  • {% include article_summary.html %}
    • - {% endfor %} -
-
- -Also see: - -* [Effective Dart](/effective-dart) -* [Tutorials](/tutorials) diff --git a/src/_data/linter_rules.json b/src/_data/linter_rules.json index 661c604b0..a4f6e1a35 100644 --- a/src/_data/linter_rules.json +++ b/src/_data/linter_rules.json @@ -114,6 +114,17 @@ "details": "**AVOID** using a parameter name that is the same as an existing type.\n\n**BAD:**\n```dart\nm(f(int));\n```\n\n**GOOD:**\n```dart\nm(f(int v));\n```\n\n", "sinceDartSdk": "2.0.0" }, + { + "name": "avoid_unstable_final_fields", + "description": "Avoid overriding a final field to return different values if called multiple times.", + "group": "errors", + "state": "experimental", + "incompatible": [], + "sets": [], + "fixStatus": "noFix", + "details": "**AVOID** overriding or implementing a final field as a getter which could\nreturn different values if it is invoked multiple times on the same receiver.\nThis could occur because the getter is an implicitly induced getter of a\nnon-final field, or it could be an explicitly declared getter with a body\nthat isn't known to return the same value each time it is called.\n\nThe underlying motivation for this rule is that if it is followed then a final\nfield is an immutable property of an object. This is important for correctness\nbecause it is then safe to assume that the value does not change during the\nexecution of an algorithm. In contrast, it may be necessary to re-check any\nother getter repeatedly if it is not known to have this property. Similarly,\nit is safe to cache the immutable property in a local variable and promote it,\nbut for any other property it is necessary to check repeatedly that the\nunderlying property hasn't changed since it was promoted.\n\n**BAD:**\n```dart\nclass A {\n final int i;\n A(this.i);\n}\n\nvar j = 0;\n\nclass B1 extends A {\n int get i => ++j + super.i; // LINT.\n B1(super.i);\n}\n\nclass B2 implements A {\n int i; // LINT.\n B2(this.i);\n}\n```\n\n**GOOD:**\n```dart\nclass C {\n final int i;\n C(this.i);\n}\n\nclass D1 implements C {\n late final int i = someExpression; // OK.\n}\n\nclass D2 extends C {\n int get i => super.i + 1; // OK.\n D2(super.i);\n}\n\nclass D3 implements C {\n final int i; // OK.\n D3(this.i);\n}\n```\n\n", + "sinceDartSdk": "3.3.0-wip" + }, { "name": "avoid_web_libraries_in_flutter", "description": "Avoid using web-only libraries outside Flutter web plugin packages.", @@ -135,7 +146,7 @@ "incompatible": [], "sets": [], "fixStatus": "noFix", - "details": "**DO** invoke `cancel` on instances of `dart.async.StreamSubscription`.\n\nCancelling instances of StreamSubscription prevents memory leaks and unexpected\nbehavior.\n\n**BAD:**\n```dart\nclass A {\n StreamSubscription _subscriptionA; // LINT\n void init(Stream stream) {\n _subscriptionA = stream.listen((_) {});\n }\n}\n```\n\n**BAD:**\n```dart\nvoid someFunction() {\n StreamSubscription _subscriptionF; // LINT\n}\n```\n\n**GOOD:**\n```dart\nclass B {\n StreamSubscription _subscriptionB; // OK\n void init(Stream stream) {\n _subscriptionB = stream.listen((_) {});\n }\n\n void dispose(filename) {\n _subscriptionB.cancel();\n }\n}\n```\n\n**GOOD:**\n```dart\nvoid someFunctionOK() {\n StreamSubscription _subscriptionB; // OK\n _subscriptionB.cancel();\n}\n```\n\n", + "details": "**DO** invoke `cancel` on instances of `dart.async.StreamSubscription`.\n\nCancelling instances of StreamSubscription prevents memory leaks and unexpected\nbehavior.\n\n**BAD:**\n```dart\nclass A {\n StreamSubscription _subscriptionA; // LINT\n void init(Stream stream) {\n _subscriptionA = stream.listen((_) {});\n }\n}\n```\n\n**BAD:**\n```dart\nvoid someFunction() {\n StreamSubscription _subscriptionF; // LINT\n}\n```\n\n**GOOD:**\n```dart\nclass B {\n StreamSubscription _subscriptionB; // OK\n void init(Stream stream) {\n _subscriptionB = stream.listen((_) {});\n }\n\n void dispose(filename) {\n _subscriptionB.cancel();\n }\n}\n```\n\n**GOOD:**\n```dart\nvoid someFunctionOK() {\n StreamSubscription _subscriptionB; // OK\n _subscriptionB.cancel();\n}\n```\n\n**Known limitations**\n\nThis rule does not track all patterns of StreamSubscription instantiations and\ncancellations. See [linter#317](https://github.com/dart-lang/linter/issues/317)\nfor more information.\n\n", "sinceDartSdk": "2.0.0" }, { @@ -146,7 +157,7 @@ "incompatible": [], "sets": [], "fixStatus": "noFix", - "details": "**DO** invoke `close` on instances of `dart.core.Sink`.\n\nClosing instances of Sink prevents memory leaks and unexpected behavior.\n\n**BAD:**\n```dart\nclass A {\n IOSink _sinkA;\n void init(filename) {\n _sinkA = File(filename).openWrite(); // LINT\n }\n}\n```\n\n**BAD:**\n```dart\nvoid someFunction() {\n IOSink _sinkF; // LINT\n}\n```\n\n**GOOD:**\n```dart\nclass B {\n IOSink _sinkB;\n void init(filename) {\n _sinkB = File(filename).openWrite(); // OK\n }\n\n void dispose(filename) {\n _sinkB.close();\n }\n}\n```\n\n**GOOD:**\n```dart\nvoid someFunctionOK() {\n IOSink _sinkFOK; // OK\n _sinkFOK.close();\n}\n```\n\n", + "details": "**DO** invoke `close` on instances of `dart.core.Sink`.\n\nClosing instances of Sink prevents memory leaks and unexpected behavior.\n\n**BAD:**\n```dart\nclass A {\n IOSink _sinkA;\n void init(filename) {\n _sinkA = File(filename).openWrite(); // LINT\n }\n}\n```\n\n**BAD:**\n```dart\nvoid someFunction() {\n IOSink _sinkF; // LINT\n}\n```\n\n**GOOD:**\n```dart\nclass B {\n IOSink _sinkB;\n void init(filename) {\n _sinkB = File(filename).openWrite(); // OK\n }\n\n void dispose(filename) {\n _sinkB.close();\n }\n}\n```\n\n**GOOD:**\n```dart\nvoid someFunctionOK() {\n IOSink _sinkFOK; // OK\n _sinkFOK.close();\n}\n```\n\n**Known limitations**\n\nThis rule does not track all patterns of Sink instantiations and\nclosures. See [linter#1381](https://github.com/dart-lang/linter/issues/1381)\nfor more information.\n\n", "sinceDartSdk": "2.0.0" }, { @@ -155,7 +166,11 @@ "group": "errors", "state": "stable", "incompatible": [], - "sets": [], + "sets": [ + "core", + "recommended", + "flutter" + ], "fixStatus": "noFix", "details": "**DON'T** invoke certain collection method with an argument with an unrelated\ntype.\n\nDoing this will invoke `==` on the collection's elements and most likely will\nreturn `false`.\n\nAn argument passed to a collection method should relate to the collection type\nas follows:\n\n* an argument to `Iterable.contains` should be related to `E`\n* an argument to `List.remove` should be related to `E`\n* an argument to `Map.containsKey` should be related to `K`\n* an argument to `Map.containsValue` should be related to `V`\n* an argument to `Map.remove` should be related to `K`\n* an argument to `Map.[]` should be related to `K`\n* an argument to `Queue.remove` should be related to `E`\n* an argument to `Set.lookup` should be related to `E`\n* an argument to `Set.remove` should be related to `E`\n\n**BAD:**\n```dart\nvoid someFunction() {\n var list = [];\n if (list.contains('1')) print('someFunction'); // LINT\n}\n```\n\n**BAD:**\n```dart\nvoid someFunction() {\n var set = {};\n set.remove('1'); // LINT\n}\n```\n\n**GOOD:**\n```dart\nvoid someFunction() {\n var list = [];\n if (list.contains(1)) print('someFunction'); // OK\n}\n```\n\n**GOOD:**\n```dart\nvoid someFunction() {\n var set = {};\n set.remove(1); // OK\n}\n```\n\n", "sinceDartSdk": "2.19.0" @@ -168,7 +183,7 @@ "incompatible": [], "sets": [], "fixStatus": "noFix", - "details": "**DO** reference only in scope identifiers in doc comments.\n\nIf you surround things like variable, method, or type names in square brackets,\nthen [`dart doc`](https://dart.dev/tools/dart-doc) will look\nup the name and link to its docs. For this all to work, ensure that all\nidentifiers in docs wrapped in brackets are in scope.\n\nFor example, assuming `outOfScopeId` is out of scope:\n\n**BAD:**\n```dart\n/// Return true if [value] is larger than [outOfScopeId].\nbool isOutOfRange(int value) { ... }\n```\n\n**GOOD:**\n```dart\n/// Return the larger of [a] or [b].\nint max_int(int a, int b) { ... }\n```\n\nNote that the square bracket comment format is designed to allow\ncomments to refer to declarations using a fairly natural format\nbut does not allow *arbitrary expressions*. In particular, code\nreferences within square brackets can consist of either\n\n- a single identifier where the identifier is any identifier in scope for the comment (see the spec for what is in scope in doc comments),\n- two identifiers separated by a period where the first identifier is the name of a class that is in scope and the second is the name of a member declared in the class,\n- a single identifier followed by a pair of parentheses where the identifier is the name of a class that is in scope (used to refer to the unnamed constructor for the class), or\n- two identifiers separated by a period and followed by a pair of parentheses where the first identifier is the name of a class that is in scope and the second is the name of a named constructor (not strictly necessary, but allowed for consistency).\n\n", + "details": "**DO** reference only in scope identifiers in doc comments.\n\nIf you surround things like variable, method, or type names in square brackets,\nthen [`dart doc`](https://dart.dev/tools/dart-doc) will look up the name and\nlink to its docs. For this all to work, ensure that all identifiers in docs\nwrapped in brackets are in scope.\n\nFor example, assuming `outOfScopeId` is out of scope:\n\n**BAD:**\n```dart\n/// Return true if [value] is larger than [outOfScopeId].\nbool isOutOfRange(int value) { ... }\n```\n\n**GOOD:**\n```dart\n/// Return the larger of [a] or [b].\nint max_int(int a, int b) { ... }\n```\n\nNote that the square bracket comment format is designed to allow comments to\nrefer to declarations using a fairly natural format but does not allow\n*arbitrary expressions*. In particular, code references within square brackets\ncan consist of either\n\n- a single identifier where the identifier is any identifier in scope for the\n comment (see the spec for what is in scope in doc comments),\n- two identifiers separated by a period where the first identifier is the name\n of a class that is in scope and the second is the name of a member declared in\n the class,\n- a single identifier followed by a pair of parentheses where the identifier is\n the name of a class that is in scope (used to refer to the unnamed constructor\n for the class), or\n- two identifiers separated by a period and followed by a pair of parentheses\n where the first identifier is the name of a class that is in scope and the\n second is the name of a named constructor (not strictly necessary, but allowed\n for consistency).\n\n**Known limitations**\n\nThe `comment_references` linter rule aligns with the Dart analyzer's notion of\ncomment references, which is separate from Dartdoc's notion of comment\nreferences. The linter rule may report comment references which cannot be\nresolved by the analyzer, but which Dartdoc can. See\n[dartdoc#1142](https://github.com/dart-lang/linter/issues/1142) for more\ninformation.\n\n", "sinceDartSdk": "2.0.0" }, { @@ -255,7 +270,7 @@ "incompatible": [], "sets": [], "fixStatus": "hasFix", - "details": "Using an `interface`, `base`, `final`, or `sealed` modifier on a class,\nor a `base` modifier on a mixin,\nauthors can control whether classes and mixins allow being implemented,\nextended, and/or mixed in from outside of the library where they're defined.\nIn some cases, it's possible for an author to inadvertently relax these controls\nand implicitly \"reopen\" a class. (A similar reopening cannot occur with a mixin.)\n\nThis lint guards against unintentionally reopening a class by requiring such\ncases to be made explicit with the \n[`@reopen`](https://pub.dev/documentation/meta/latest/meta/reopen-constant.html)\nannotation in `package:meta`.\n\n**BAD:**\n```dart\ninterface class I {}\n\nclass C extends I {} // LINT\n```\n\n**GOOD:**\n```dart\ninterface class I {}\n\nfinal class C extends I {}\n```\n\n```dart\ninterface class I {}\n\nfinal class C extends I {}\n```\n\n```dart\nimport 'package:meta/meta.dart';\n\ninterface class I {}\n\n@reopen\nclass C extends I {}\n```\n", + "details": "Using an `interface`, `base`, `final`, or `sealed` modifier on a class,\nor a `base` modifier on a mixin,\nauthors can control whether classes and mixins allow being implemented,\nextended, and/or mixed in from outside of the library where they're defined.\nIn some cases, it's possible for an author to inadvertently relax these controls\nand implicitly \"reopen\" a class. (A similar reopening cannot occur with a mixin.)\n\nThis lint guards against unintentionally reopening a class by requiring such\ncases to be made explicit with the\n[`@reopen`](https://pub.dev/documentation/meta/latest/meta/reopen-constant.html)\nannotation in `package:meta`.\n\n**BAD:**\n```dart\ninterface class I {}\n\nclass C extends I {} // LINT\n```\n\n**GOOD:**\n```dart\ninterface class I {}\n\nfinal class C extends I {}\n```\n\n```dart\nimport 'package:meta/meta.dart';\n\ninterface class I {}\n\n@reopen\nclass C extends I {}\n```\n", "sinceDartSdk": "3.0.0" }, { @@ -286,11 +301,7 @@ "group": "errors", "state": "deprecated", "incompatible": [], - "sets": [ - "core", - "recommended", - "flutter" - ], + "sets": [], "fixStatus": "noFix", "details": "**DON'T** invoke `contains` on `Iterable` with an instance of different type\nthan the parameter type.\n\nDoing this will invoke `==` on its elements and most likely will return `false`.\n\n**BAD:**\n```dart\nvoid someFunction() {\n var list = [];\n if (list.contains('1')) print('someFunction'); // LINT\n}\n```\n\n**BAD:**\n```dart\nvoid someFunction3() {\n List list = [];\n if (list.contains('1')) print('someFunction3'); // LINT\n}\n```\n\n**BAD:**\n```dart\nvoid someFunction8() {\n List list = [];\n DerivedClass3 instance;\n if (list.contains(instance)) print('someFunction8'); // LINT\n}\n```\n\n**BAD:**\n```dart\nabstract class SomeIterable implements Iterable {}\n\nabstract class MyClass implements SomeIterable {\n bool badMethod(String thing) => this.contains(thing); // LINT\n}\n```\n\n**GOOD:**\n```dart\nvoid someFunction10() {\n var list = [];\n if (list.contains(1)) print('someFunction10'); // OK\n}\n```\n\n**GOOD:**\n```dart\nvoid someFunction1() {\n var list = [];\n if (list.contains(1)) print('someFunction1'); // OK\n}\n```\n\n**GOOD:**\n```dart\nvoid someFunction4() {\n List list = [];\n if (list.contains(1)) print('someFunction4'); // OK\n}\n```\n\n**GOOD:**\n```dart\nvoid someFunction5() {\n List list = [];\n DerivedClass1 instance;\n if (list.contains(instance)) print('someFunction5'); // OK\n}\n\nabstract class ClassBase {}\n\nclass DerivedClass1 extends ClassBase {}\n```\n\n**GOOD:**\n```dart\nvoid someFunction6() {\n List list = [];\n DerivedClass2 instance;\n if (list.contains(instance)) print('someFunction6'); // OK\n}\n\nabstract class ClassBase {}\n\nabstract class Mixin {}\n\nclass DerivedClass2 extends ClassBase with Mixin {}\n```\n\n**GOOD:**\n```dart\nvoid someFunction7() {\n List list = [];\n DerivedClass3 instance;\n if (list.contains(instance)) print('someFunction7'); // OK\n}\n\nabstract class ClassBase {}\n\nabstract class Mixin {}\n\nclass DerivedClass3 extends ClassBase implements Mixin {}\n```\n\n**DEPRECATED:** This rule is deprecated in favor of\n`collection_methods_unrelated_type`.\nThe rule will be removed in a future Dart release.\n\n", "sinceDartSdk": "2.0.0" @@ -301,11 +312,7 @@ "group": "errors", "state": "deprecated", "incompatible": [], - "sets": [ - "core", - "recommended", - "flutter" - ], + "sets": [], "fixStatus": "noFix", "details": "**DON'T** invoke `remove` on `List` with an instance of different type than\nthe parameter type.\n\nDoing this will invoke `==` on its elements and most likely will\nreturn `false`.\n\n**BAD:**\n```dart\nvoid someFunction() {\n var list = [];\n if (list.remove('1')) print('someFunction'); // LINT\n}\n```\n\n**BAD:**\n```dart\nvoid someFunction3() {\n List list = [];\n if (list.remove('1')) print('someFunction3'); // LINT\n}\n```\n\n**BAD:**\n```dart\nvoid someFunction8() {\n List list = [];\n DerivedClass3 instance;\n if (list.remove(instance)) print('someFunction8'); // LINT\n}\n```\n\n**BAD:**\n```dart\nabstract class SomeList implements List {}\n\nabstract class MyClass implements SomeList {\n bool badMethod(String thing) => this.remove(thing); // LINT\n}\n```\n\n**GOOD:**\n```dart\nvoid someFunction10() {\n var list = [];\n if (list.remove(1)) print('someFunction10'); // OK\n}\n```\n\n**GOOD:**\n```dart\nvoid someFunction1() {\n var list = [];\n if (list.remove(1)) print('someFunction1'); // OK\n}\n```\n\n**GOOD:**\n```dart\nvoid someFunction4() {\n List list = [];\n if (list.remove(1)) print('someFunction4'); // OK\n}\n```\n\n**GOOD:**\n```dart\nvoid someFunction5() {\n List list = [];\n DerivedClass1 instance;\n if (list.remove(instance)) print('someFunction5'); // OK\n}\n\nabstract class ClassBase {}\n\nclass DerivedClass1 extends ClassBase {}\n```\n\n**GOOD:**\n```dart\nvoid someFunction6() {\n List list = [];\n DerivedClass2 instance;\n if (list.remove(instance)) print('someFunction6'); // OK\n}\n\nabstract class ClassBase {}\n\nabstract class Mixin {}\n\nclass DerivedClass2 extends ClassBase with Mixin {}\n```\n\n**GOOD:**\n```dart\nvoid someFunction7() {\n List list = [];\n DerivedClass3 instance;\n if (list.remove(instance)) print('someFunction7'); // OK\n}\n\nabstract class ClassBase {}\n\nabstract class Mixin {}\n\nclass DerivedClass3 extends ClassBase implements Mixin {}\n```\n\n**DEPRECATED:** This rule is deprecated in favor of\n`collection_methods_unrelated_type`.\nThe rule will be removed in a future Dart release.\n\n", "sinceDartSdk": "2.0.0" @@ -369,7 +376,7 @@ "sets": [], "fixStatus": "needsEvaluation", "details": "**DON'T** assign a variable to itself. Usually this is a mistake.\n\n**BAD:**\n```dart\nclass C {\n int x;\n\n C(int x) {\n x = x;\n }\n}\n```\n\n**GOOD:**\n```dart\nclass C {\n int x;\n\n C(int x) : x = x;\n}\n```\n\n**GOOD:**\n```dart\nclass C {\n int x;\n\n C(int x) {\n this.x = x;\n }\n}\n```\n\n**BAD:**\n```dart\nclass C {\n int _x = 5;\n\n int get x => _x;\n\n set x(int x) {\n _x = x;\n _customUpdateLogic();\n }\n\n void _customUpdateLogic() {\n print('updated');\n }\n\n void example() {\n x = x;\n }\n}\n```\n\n**GOOD:**\n```dart\nclass C {\n int _x = 5;\n\n int get x => _x;\n\n set x(int x) {\n _x = x;\n _customUpdateLogic();\n }\n\n void _customUpdateLogic() {\n print('updated');\n }\n\n void example() {\n _customUpdateLogic();\n }\n}\n```\n\n**BAD:**\n```dart\nclass C {\n int x = 5;\n\n void update(C other) {\n this.x = this.x;\n }\n}\n```\n\n**GOOD:**\n```dart\nclass C {\n int x = 5;\n\n void update(C other) {\n this.x = other.x;\n }\n}\n```\n\n", - "sinceDartSdk": "3.1.0-wip" + "sinceDartSdk": "3.1.0" }, { "name": "no_wildcard_variable_uses", @@ -380,7 +387,7 @@ "sets": [], "fixStatus": "needsEvaluation", "details": "**DON'T** use wildcard parameters or variables.\n\nWildcard parameters and local variables\n(e.g. underscore-only names like `_`, `__`, `___`, etc.) will\nbecome non-binding in a future version of the Dart language.\nAny existing code that uses wildcard parameters or variables will\nbreak. In anticipation of this change, and to make adoption easier,\nthis lint disallows wildcard and variable parameter uses.\n\n\n**BAD:**\n```dart\nvar _ = 1;\nprint(_); // LINT\n```\n\n```dart\nvoid f(int __) {\n print(__); // LINT multiple underscores too\n}\n```\n\n**GOOD:**\n```dart\nfor (var _ in [1, 2, 3]) count++;\n```\n\n```dart\nvar [a, _, b, _] = [1, 2, 3, 4];\n```\n", - "sinceDartSdk": "3.1.0-wip" + "sinceDartSdk": "3.1.0" }, { "name": "prefer_relative_imports", @@ -401,10 +408,7 @@ "group": "errors", "state": "stable", "incompatible": [], - "sets": [ - "recommended", - "flutter" - ], + "sets": [], "fixStatus": "hasFix", "details": "**DON'T** use the type Null where void would work.\n\n**BAD:**\n```dart\nNull f() {}\nFuture f() {}\nStream f() {}\nf(Null x) {}\n```\n\n**GOOD:**\n```dart\nvoid f() {}\nFuture f() {}\nStream f() {}\nf(void x) {}\n```\n\nSome exceptions include formulating special function types:\n\n```dart\nNull Function(Null, Null);\n```\n\nand for making empty literals which are safe to pass into read-only locations\nfor any type of map or list:\n\n```dart\n[];\n{};\n```\n", "sinceDartSdk": "2.1.0" @@ -472,7 +476,7 @@ "name": "use_build_context_synchronously", "description": "Do not use BuildContexts across async gaps.", "group": "errors", - "state": "experimental", + "state": "stable", "incompatible": [], "sets": [ "flutter" @@ -544,7 +548,11 @@ "group": "pub", "state": "stable", "incompatible": [], - "sets": [], + "sets": [ + "core", + "recommended", + "flutter" + ], "fixStatus": "noFix", "details": "**DO** Use secure urls in `pubspec.yaml`.\n\nUse `https` instead of `http` or `git:`.\n\n**BAD:**\n```yaml\nrepository: http://github.com/dart-lang/example\n```\n\n```yaml\ngit:\n url: git://github.com/dart-lang/example/example.git\n```\n\n**GOOD:**\n```yaml\nrepository: https://github.com/dart-lang/example\n```\n\n", "sinceDartSdk": "2.16.0" @@ -632,6 +640,17 @@ "details": "**DO** annotate overridden methods and fields.\n\nThis practice improves code readability and helps protect against\nunintentionally overriding superclass members.\n\n**BAD:**\n```dart\nclass Cat {\n int get lives => 9;\n}\n\nclass Lucky extends Cat {\n final int lives = 14;\n}\n```\n\n**GOOD:**\n```dart\nabstract class Dog {\n String get breed;\n void bark() {}\n}\n\nclass Husky extends Dog {\n @override\n final String breed = 'Husky';\n @override\n void bark() {}\n}\n```\n\n", "sinceDartSdk": "2.0.0" }, + { + "name": "annotate_redeclares", + "description": "Annotate redeclared members.", + "group": "style", + "state": "experimental", + "incompatible": [], + "sets": [], + "fixStatus": "hasFix", + "details": "**DO** annotate redeclared members.\n\nThis practice improves code readability and helps protect against\nunintentionally redeclaring members or being surprised when a member ceases to\nredeclare (due for example to a rename refactoring).\n\n**BAD:**\n```dart\nclass C {\n void f() { }\n}\n\nextension type E(C c) implements C {\n void f() {\n ...\n }\n}\n```\n\n**GOOD:**\n```dart\nimport 'package:meta/meta.dart';\n\nclass C {\n void f() { }\n}\n\nextension type E(C c) implements C {\n @redeclare\n void f() {\n ...\n }\n}\n```\n", + "sinceDartSdk": "3.2.0" + }, { "name": "avoid_annotating_with_dynamic", "description": "Avoid annotating with dynamic when not required.", @@ -1139,7 +1158,11 @@ "group": "style", "state": "stable", "incompatible": [], - "sets": [], + "sets": [ + "core", + "recommended", + "flutter" + ], "fixStatus": "hasFix", "details": "Attach library doc comments (with `///`) to library directives, rather than\nleaving them dangling near the top of a library.\n\n**BAD:**\n```dart\n/// This is a great library.\nimport 'package:math';\n```\n\n```dart\n/// This is a great library.\n\nclass C {}\n```\n\n**GOOD:**\n```dart\n/// This is a great library.\nlibrary;\n\nimport 'package:math';\n\nclass C {}\n```\n\n**NOTE:** An unnamed library, like `library;` above, is only supported in Dart\n2.19 and later. Code which might run in earlier versions of Dart will need to\nprovide a name in the `library` directive.\n", "sinceDartSdk": "2.19.0" @@ -1288,7 +1311,11 @@ "group": "style", "state": "stable", "incompatible": [], - "sets": [], + "sets": [ + "core", + "recommended", + "flutter" + ], "fixStatus": "hasFix", "details": "**DO**\nExplicitly tear off `.call` methods from objects when assigning to a Function\ntype. There is less magic with an explicit tear off. Future language versions\nmay remove the implicit call tear off.\n\n**BAD:**\n```dart\nclass Callable {\n void call() {}\n}\nvoid callIt(void Function() f) {\n f();\n}\n\ncallIt(Callable());\n```\n\n**GOOD:**\n```dart\nclass Callable {\n void call() {}\n}\nvoid callIt(void Function() f) {\n f();\n}\n\ncallIt(Callable().call);\n```\n\n", "sinceDartSdk": "2.19.0" @@ -1388,7 +1415,7 @@ "sets": [], "fixStatus": "needsFix", "details": "**DO** use super parameter names that match their corresponding super\nconstructor's parameter names.\n\n**BAD:**\n\n```dart\nclass Rectangle {\n final int width;\n final int height;\n \n Rectangle(this.width, this.height);\n}\n\nclass ColoredRectangle extends Rectangle {\n final Color color;\n \n ColoredRectangle(\n this.color,\n super.height, // Bad, actually corresponds to the `width` parameter.\n super.width, // Bad, actually corresponds to the `height` parameter.\n ); \n}\n```\n\n**GOOD:**\n\n```dart\nclass Rectangle {\n final int width;\n final int height;\n \n Rectangle(this.width, this.height);\n}\n\nclass ColoredRectangle extends Rectangle {\n final Color color;\n \n ColoredRectangle(\n this.color,\n super.width,\n super.height, \n ); \n}\n```\n", - "sinceDartSdk": "3.1.0-wip" + "sinceDartSdk": "3.0.0" }, { "name": "missing_whitespace_between_adjacent_strings", @@ -1449,7 +1476,7 @@ "sets": [], "fixStatus": "hasFix", "details": "From [Effective Dart](https://dart.dev/effective-dart/usage#dont-use-true-or-false-in-equality-operations):\n\n**DON'T** use `true` or `false` in equality operations.\n\nThis lint applies only if the expression is of a non-nullable `bool` type.\n\n**BAD:**\n```dart\nif (someBool == true) {\n}\nwhile (someBool == false) {\n}\n```\n\n**GOOD:**\n```dart\nif (someBool) {\n}\nwhile (!someBool) {\n}\n```\n", - "sinceDartSdk": "3.1.0-wip" + "sinceDartSdk": "3.0.0" }, { "name": "no_runtimeType_toString", @@ -1459,7 +1486,7 @@ "incompatible": [], "sets": [], "fixStatus": "noFix", - "details": "Calling `toString` on a runtime type is a non-trivial operation that can\nnegatively impact performance. It's better to avoid it.\n\n**BAD:**\n```dart\nclass A {\n String toString() => '$runtimeType()';\n}\n```\n\n**GOOD:**\n```dart\nclass A {\n String toString() => 'A()';\n}\n```\n\nThis lint has some exceptions where performance is not a problem or where real\ntype information is more important than performance:\n\n* in assertion\n* in throw expressions\n* in catch clauses\n* in mixin declaration\n* in abstract class\n\n", + "details": "Calling `toString` on a runtime type is a non-trivial operation that can\nnegatively impact performance. It's better to avoid it.\n\n**BAD:**\n```dart\nclass A {\n String toString() => '$runtimeType()';\n}\n```\n\n**GOOD:**\n```dart\nclass A {\n String toString() => 'A()';\n}\n```\n\nThis lint has some exceptions where performance is not a problem or where real\ntype information is more important than performance:\n\n* in an assertion\n* in a throw expression\n* in a catch clause\n* in a mixin declaration\n* in an abstract class declaration\n\n", "sinceDartSdk": "2.8.1" }, { @@ -1661,7 +1688,7 @@ "flutter" ], "fixStatus": "hasFix", - "details": "**DO** use collection literals when possible.\n\n**BAD:**\n```dart\nvar addresses = Map();\nvar uniqueNames = Set();\nvar ids = LinkedHashSet();\nvar coordinates = LinkedHashMap();\n```\n\n**GOOD:**\n```dart\nvar addresses = {};\nvar uniqueNames = {};\nvar ids = {};\nvar coordinates = {};\n```\n\n**EXCEPTIONS:**\n\nThere are cases with `LinkedHashSet` or `LinkedHashMap` where a literal constructor\nwill trigger a type error so those will be excluded from the lint.\n\n```dart\nvoid main() {\n LinkedHashSet linkedHashSet = LinkedHashSet.from([1, 2, 3]); // OK\n LinkedHashMap linkedHashMap = LinkedHashMap(); // OK\n \n printSet(LinkedHashSet()); // LINT\n printHashSet(LinkedHashSet()); // OK\n\n printMap(LinkedHashMap()); // LINT\n printHashMap(LinkedHashMap()); // OK\n}\n\nvoid printSet(Set ids) => print('$ids!');\nvoid printHashSet(LinkedHashSet ids) => printSet(ids);\nvoid printMap(Map map) => print('$map!');\nvoid printHashMap(LinkedHashMap map) => printMap(map);\n```\n", + "details": "**DO** use collection literals when possible.\n\n**BAD:**\n```dart\nvar addresses = Map();\nvar uniqueNames = Set();\nvar ids = LinkedHashSet();\nvar coordinates = LinkedHashMap();\n```\n\n**GOOD:**\n```dart\nvar addresses = {};\nvar uniqueNames = {};\nvar ids = {};\nvar coordinates = {};\n```\n\n**EXCEPTIONS:**\n\nWhen a `LinkedHashSet` or `LinkedHashMap` is expected, a collection literal is\nnot preferred (or allowed).\n\n```dart\nvoid main() {\n LinkedHashSet linkedHashSet = LinkedHashSet.from([1, 2, 3]); // OK\n LinkedHashMap linkedHashMap = LinkedHashMap(); // OK\n \n printSet(LinkedHashSet()); // LINT\n printHashSet(LinkedHashSet()); // OK\n\n printMap(LinkedHashMap()); // LINT\n printHashMap(LinkedHashMap()); // OK\n}\n\nvoid printSet(Set ids) => print('$ids!');\nvoid printHashSet(LinkedHashSet ids) => printSet(ids);\nvoid printMap(Map map) => print('$map!');\nvoid printHashMap(LinkedHashMap map) => printMap(map);\n```\n", "sinceDartSdk": "2.0.0" }, { @@ -1774,10 +1801,7 @@ "group": "style", "state": "removed", "incompatible": [], - "sets": [ - "recommended", - "flutter" - ], + "sets": [], "fixStatus": "noFix", "details": "**DO** use `=` to separate a named parameter from its default value.\n\n**BAD:**\n```dart\nm({a: 1})\n```\n\n**GOOD:**\n```dart\nm({a = 1})\n```\n", "sinceDartSdk": "2.0.0" @@ -2186,7 +2210,7 @@ "incompatible": [], "sets": [], "fixStatus": "needsFix", - "details": "Use `SizedBox.shrink(...)` and `SizedBox.expand(...)` constructors appropriately.\n\nThe `SizedBox.shrink(...)` and `SizedBox.expand(...)` constructors should be used\ninstead of the more general `SizedBox(...)` constructor when the named constructors\ncapture the intent of the code more succinctly.\n\n**Examples**\n\n**BAD:**\n```dart\nWidget buildLogo() {\n return SizedBox(\n height: 0,\n width: 0,\n child: const MyLogo(),\n );\n}\n```\n\n```dart\nWidget buildLogo() {\n return SizedBox(\n height: double.infinity,\n width: double.infinity,\n child: const MyLogo(),\n );\n}\n```\n\n**GOOD:**\n```dart\nWidget buildLogo() {\n return SizedBox.shrink(\n child: const MyLogo(),\n );\n}\n```\n\n```dart\nWidget buildLogo() {\n return SizedBox.expand(\n child: const MyLogo(),\n );\n}\n```\n", + "details": "Use `SizedBox.shrink(...)` and `SizedBox.expand(...)` constructors\nappropriately.\n\nEither the `SizedBox.shrink(...)` or `SizedBox.expand(...)` constructor should\nbe used instead of the more general `SizedBox(...)` constructor when one of the\nnamed constructors capture the intent of the code more succinctly.\n\n**Examples**\n\n**BAD:**\n```dart\nWidget buildLogo() {\n return SizedBox(\n height: 0,\n width: 0,\n child: const MyLogo(),\n );\n}\n```\n\n```dart\nWidget buildLogo() {\n return SizedBox(\n height: double.infinity,\n width: double.infinity,\n child: const MyLogo(),\n );\n}\n```\n\n**GOOD:**\n```dart\nWidget buildLogo() {\n return SizedBox.shrink(\n child: const MyLogo(),\n );\n}\n```\n\n```dart\nWidget buildLogo() {\n return SizedBox.expand(\n child: const MyLogo(),\n );\n}\n```\n", "sinceDartSdk": "2.16.0" }, { @@ -2291,7 +2315,11 @@ "group": "style", "state": "stable", "incompatible": [], - "sets": [], + "sets": [ + "core", + "recommended", + "flutter" + ], "fixStatus": "hasFix", "details": "If you meant to test if the object has type `Foo`, instead write `Foo _`.\n\n**BAD:**\n```dart\nvoid f(Object? x) {\n if (x case num) {\n print('int or double');\n }\n}\n```\n\n**GOOD:**\n```dart\nvoid f(Object? x) {\n if (x case num _) {\n print('int or double');\n }\n}\n```\n\nIf you do mean to test that the matched value (which you expect to have the\ntype `Type`) is equal to the type literal `Foo`, then this lint can be\nsilenced using `const (Foo)`.\n\n**BAD:**\n```dart\nvoid f(Object? x) {\n if (x case int) {\n print('int');\n }\n}\n```\n\n**GOOD:**\n```dart\nvoid f(Object? x) {\n if (x case const (int)) {\n print('int');\n }\n}\n```\n", "sinceDartSdk": "3.0.0" @@ -2589,7 +2617,7 @@ "flutter" ], "fixStatus": "hasFix", - "details": "From [Effective Dart](https://dart.dev/effective-dart/usage#dont-use-this-when-not-needed-to-avoid-shadowing):\n\n**DON'T** use `this` when not needed to avoid shadowing.\n\n**BAD:**\n```dart\nclass Box {\n var value;\n void update(new_value) {\n this.value = new_value;\n }\n}\n```\n\n**GOOD:**\n```dart\nclass Box {\n var value;\n void update(new_value) {\n value = new_value;\n }\n}\n```\n\n**GOOD:**\n```dart\nclass Box {\n var value;\n void update(value) {\n this.value = value;\n }\n}\n```\n\n", + "details": "From [Effective Dart](https://dart.dev/effective-dart/usage#dont-use-this-when-not-needed-to-avoid-shadowing):\n\n**DON'T** use `this` when not needed to avoid shadowing.\n\n**BAD:**\n```dart\nclass Box {\n int value;\n void update(int newValue) {\n this.value = newValue;\n }\n}\n```\n\n**GOOD:**\n```dart\nclass Box {\n int value;\n void update(int newValue) {\n value = newValue;\n }\n}\n```\n\n**GOOD:**\n```dart\nclass Box {\n int value;\n void update(int value) {\n this.value = value;\n }\n}\n```\n\n", "sinceDartSdk": "2.0.0" }, { @@ -2598,7 +2626,10 @@ "group": "style", "state": "stable", "incompatible": [], - "sets": [], + "sets": [ + "recommended", + "flutter" + ], "fixStatus": "hasFix", "details": "Unnecessary `toList()` in spreads.\n\n**BAD:**\n```dart\nchildren: [\n ...['foo', 'bar', 'baz'].map((String s) => Text(s)).toList(),\n]\n```\n\n**GOOD:**\n```dart\nchildren: [\n ...['foo', 'bar', 'baz'].map((String s) => Text(s)),\n]\n```\n\n", "sinceDartSdk": "2.18.0" @@ -2610,8 +2641,8 @@ "state": "stable", "incompatible": [], "sets": [], - "fixStatus": "noFix", - "details": "Top-level members and static members in an executable library should be used\ndirectly inside this library. An executable library is a library that contains\na `main` top-level function or that contains a top-level function annotated with\n`@pragma('vm:entry-point')`). Executable libraries are not usually imported\nand it's better to avoid defining unused members.\n\nThis rule assumes that an executable library isn't imported by other files\nexcept to execute its `main` function.\n\n**BAD:**\n\n```dart\nmain() {}\nvoid f() {}\n```\n\n**GOOD:**\n\n```dart\nmain() {\n f();\n}\nvoid f() {}\n```\n\n", + "fixStatus": "hasFix", + "details": "Any member declared in an executable library should be used directly inside that\nlibrary. An executable library is a library that contains a `main` top-level\nfunction or that contains a top-level function annotated with\n`@pragma('vm:entry-point')`). Executable libraries are not usually imported\nand it's better to avoid defining unused members.\n\nThis rule assumes that an executable library isn't imported by other libraries\nexcept to execute its `main` function.\n\n**BAD:**\n\n```dart\nmain() {}\nvoid f() {}\n```\n\n**GOOD:**\n\n```dart\nmain() {\n f();\n}\nvoid f() {}\n```\n\n", "sinceDartSdk": "2.19.0" }, { @@ -2644,7 +2675,7 @@ "incompatible": [], "sets": [], "fixStatus": "hasFix", - "details": "Classes that look like enumerations should be declared as `enum`s.\n\n**DO** use enums where appropriate.\n\nCandidates for enums are classes that:\n * are concrete,\n * are private or have only private generative constructors,\n * have two or more static const fields with the same type as the class,\n * have generative constructors that are only invoked at the top-level of the\n initialization expression of these static fields,\n * do not define `hashCode`, `==`, `values` or `index`,\n * do not extend any class other than Object, and\n * have no subclasses declared in the defining library.\n\n**BAD:**\n```dart\nclass LogPriority {\n static const error = LogPriority._(1, 'Error');\n static const warning = LogPriority._(2, 'Warning');\n static const log = LogPriority._unknown('Log');\n\n final String prefix;\n final int priority;\n const LogPriority._(this.priority, this.prefix);\n const LogPriority._unknown(String prefix) : this._(-1, prefix);\n}\n```\n\n**GOOD:**\n```dart\nenum LogPriority {\n error(1, 'Error'),\n warning(2, 'Warning'),\n log.unknown('Log');\n\n final String prefix;\n final int priority;\n const LogPriority(this.priority, this.prefix);\n const LogPriority.unknown(String prefix) : this(-1, prefix);\n}\n```\n", + "details": "Classes that look like enumerations should be declared as `enum`s.\n\n**DO** use enums where appropriate.\n\nCandidates for enums are classes that:\n\n * are concrete,\n * are private or have only private generative constructors,\n * have two or more static const fields with the same type as the class,\n * have generative constructors that are only invoked at the top-level of the\n initialization expression of these static fields,\n * do not define `hashCode`, `==`, `values` or `index`,\n * do not extend any class other than `Object`, and\n * have no subclasses declared in the defining library.\n\nTo learn more about creating and using these enums, check out\n[Declaring enhanced enums](https://dart.dev/language/enums#declaring-enhanced-enums).\n\n**BAD:**\n```dart\nclass LogPriority {\n static const error = LogPriority._(1, 'Error');\n static const warning = LogPriority._(2, 'Warning');\n static const log = LogPriority._unknown('Log');\n\n final String prefix;\n final int priority;\n const LogPriority._(this.priority, this.prefix);\n const LogPriority._unknown(String prefix) : this._(-1, prefix);\n}\n```\n\n**GOOD:**\n```dart\nenum LogPriority {\n error(1, 'Error'),\n warning(2, 'Warning'),\n log.unknown('Log');\n\n final String prefix;\n final int priority;\n const LogPriority(this.priority, this.prefix);\n const LogPriority.unknown(String prefix) : this(-1, prefix);\n}\n```\n", "sinceDartSdk": "2.17.0" }, { @@ -2771,7 +2802,11 @@ "group": "style", "state": "stable", "incompatible": [], - "sets": [], + "sets": [ + "core", + "recommended", + "flutter" + ], "fixStatus": "hasFix", "details": "From [Effective Dart](https://dart.dev/effective-dart/usage#do-use-strings-in-part-of-directives):\n\n**DO** use strings in `part of` directives.\n\n**BAD:**\n\n```dart\npart of my_library;\n```\n\n**GOOD:**\n\n```dart\npart of '../../my_library.dart';\n```\n\n", "sinceDartSdk": "2.19.0" @@ -2782,7 +2817,10 @@ "group": "style", "state": "experimental", "incompatible": [], - "sets": [], + "sets": [ + "recommended", + "flutter" + ], "fixStatus": "hasFix", "details": "\"Forwarding constructor\"s, that do nothing except forward parameters to their \nsuperclass constructors should take advantage of super-initializer parameters \nrather than repeating the names of parameters when passing them to the \nsuperclass constructors. This makes the code more concise and easier to read\nand maintain.\n\n**DO** use super-initializer parameters where possible.\n\n**BAD:**\n```dart\nclass A {\n A({int? x, int? y});\n}\nclass B extends A {\n B({int? x, int? y}) : super(x: x, y: y);\n}\n```\n\n**GOOD:**\n```dart\nclass A {\n A({int? x, int? y});\n}\nclass B extends A {\n B({super.x, super.y});\n}\n```\n", "sinceDartSdk": "2.17.0" @@ -2824,4 +2862,4 @@ "details": "**DON'T** assign to void.\n\n**BAD:**\n```dart\nclass A {\n T value;\n void test(T arg) { }\n}\n\nvoid main() {\n A a = A();\n a.value = 1; // LINT\n a.test(1); // LINT\n}\n```\n", "sinceDartSdk": "2.0.0" } -] \ No newline at end of file +] diff --git a/src/_data/pkg-vers.json b/src/_data/pkg-vers.json index f4b9fbf84..952efc926 100644 --- a/src/_data/pkg-vers.json +++ b/src/_data/pkg-vers.json @@ -3,6 +3,6 @@ "doc-path": "install", "channel": "stable", "prev-vers": "2.19.6", - "vers": "3.0.7" + "vers": "3.1.5" } } diff --git a/src/_data/side-nav.yml b/src/_data/side-nav.yml index e34be50ba..48c6b62bf 100644 --- a/src/_data/side-nav.yml +++ b/src/_data/side-nav.yml @@ -334,6 +334,8 @@ children: - title: 常见问题 permalink: /resources/faq + - title: 破坏性改动 + permalink: /resources/breaking-changes - title: 版本演变 permalink: /guides/language/evolution - title: 语言规范 diff --git a/src/_guides/language/cheatsheet.md b/src/_guides/language/cheatsheet.md deleted file mode 100644 index 2fac147da..000000000 --- a/src/_guides/language/cheatsheet.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -title: Dart language cheatsheet -title: Dart 语言速查表 -description: A one-page summary of some of Dart's most useful, interesting features. -description: 介绍 Dart 里最有用和有意思的特性。 ---- - -This cheatsheet is based on an internal document -created by Googler [Mehmet Fidanboylu](https://medium.com/@mehmetf_71205) -to help Google engineers remember the syntax for -some of Dart's commonly used features. -For an interactive guide to these features and more, see the -[Dart cheatsheet codelab](/codelabs/dart-cheatsheet). - -## Using literals - -### `‘Substitution ${val}’` - -Puts the value of `val` into a string literal. -Equivalent: `‘Substitution’ + val` - -### `[ ]` - -Creates an object of type `List`. - -### `const [1, 2, 3]` - -Creates a compile-time constant list. - -### `= { }` - -Initializes a map. -Equivalent: `new Map<>();` - -## Declaring fields - -| `var` | Generic `var` with type inference | -| `final` | Same as `var` but cannot be reassigned | -| `const` | Compile-time constant | -{:.table} - - -## Checking types - -| `as` | Typecast | -| `is` | instanceof | -| `is!` | !instanceof | -{:.table} - - -## Chaining method calls - -### `a..b = true..c = 5;` - -Cascade used for chaining access to methods and other members. -Equivalent: `a.b = true; a.c = 5;` - - -## Dealing with null - -### `b ??= val;` - -If `b` is null, assign the value of `val` to `b`; -otherwise, `b` stays the same. - -### `a = value ?? 0;` - -If value is null, set `a` to 0. -Otherwise, set `a` to value. - -### `a?.b` - -Conditional access. -Equivalent: `a == null ? null : a.b` - - -## Implementing functions - -### `fn({bool bold = false, bool hidden = false})` - -Named params with default values. - -### `int incr(int a) => a + 1;` - -Single return statement can be abbreviated. - -## Handling exceptions - -```dart -try {...} -on MyException {...} -catch (e) {...} -finally {...} -``` - -Use `on` to catch a type. -Use `catch` to catch an instance. - -## Implementing constructors - -### Normal constructor - -```dart -Point(this.x, this.y); -``` - -### Factory constructor - -```dart -factory Point(int x, int y) => ...; -``` - -Use `factory` when implementing a constructor that -doesn’t always create a new instance. - - -### Named constructor - -```dart -Point.fromJson(Map json) { - x = json['x']; - y = json['y']; - } -``` - -### Delegating constructor - -```dart -Point.alongXAxis(num x) : this(x, 0); -``` - -### Const constructor - -```dart -const ImmutablePoint(this.x, this.y); -``` - -Produces an object that will never change. All fields have to be final. - -### Initializer list - -```dart -Point.fromJson(Map jsonMap) - : x = jsonMap['x'], y = jsonMap['y']; -``` - -Initializer lists are handy when setting up final fields. diff --git a/src/_includes/article_summary.html b/src/_includes/article_summary.html deleted file mode 100644 index 97739a207..000000000 --- a/src/_includes/article_summary.html +++ /dev/null @@ -1,3 +0,0 @@ -

{{article.title}}

-{{ article.original-date | default: article.date | date: '%B %Y' }} {% if article.original-date %}(updated: {{ article.date | date: '%B %Y' }}){% endif %} -

{{article.description}}

diff --git a/src/_includes/author.html b/src/_includes/author.html deleted file mode 100644 index 6d8411aa0..000000000 --- a/src/_includes/author.html +++ /dev/null @@ -1,39 +0,0 @@ -
- {% if page.rel.me or page.author.twitter %} -
-

Follow {{page.author.fname}}

- -
- {% endif %} - -
-

Bio

- {{bio}} -
- - {% assign empty_list = true %} - {% for article in site.pages %} - {% if article.rel and article.rel.author == page.author.key %} - {% assign article_url = article.url | remove:'index.html' %} - {% if empty_list %} - {% assign empty_list = false %} -
-

On this site

-
    - {% endif %} -
  • {{article.title}}
    • - {% endif %} - {% endfor %} - {% if empty_list == false %} -
-
- {% endif %} - -
diff --git a/src/_includes/banner.html b/src/_includes/banner.html index d6806a95b..69250805f 100644 --- a/src/_includes/banner.html +++ b/src/_includes/banner.html @@ -1,10 +1,7 @@ diff --git a/src/_includes/breadcrumbs.html b/src/_includes/breadcrumbs.html new file mode 100644 index 000000000..b55a20b46 --- /dev/null +++ b/src/_includes/breadcrumbs.html @@ -0,0 +1,33 @@ +{% comment %} +Embeds breadcrumb RDFa, follows ARIA guidelines. References: +- https://developers.google.com/search/docs/data-types/breadcrumb +- https://schema.org/BreadcrumbList +- https://www.w3.org/TR/wai-aria-practices/examples/breadcrumb/index.html +- https://search.google.com/structured-data/testing-tool +{% endcomment %} + +{% assign url = page.url | regex_replace: '/index$|/index.html$|/$' -%} + +{% if url.size > 0 -%} + +{%- endif -%} diff --git a/src/_includes/get-sdk.md b/src/_includes/get-sdk.md index 188b68a27..4f0c2bc00 100644 --- a/src/_includes/get-sdk.md +++ b/src/_includes/get-sdk.md @@ -1,4 +1,4 @@ -Once you’re ready to move beyond DartPad and develop real apps, +Once you're ready to move beyond DartPad and develop real apps, you need an SDK. You can either download the Dart SDK directly (as described below) diff --git a/src/_includes/head.html b/src/_includes/head.html index ac8594950..5f2b79dc1 100644 --- a/src/_includes/head.html +++ b/src/_includes/head.html @@ -13,8 +13,11 @@ - - {% assign desc = page.description | default: page.excerpt | default: site.description | strip_html | strip_newlines | truncate: 160 -%} + {% assign desc = page.description | strip_html | strip_newlines | truncate: 160 -%} + {% unless desc and desc != '' -%} + {% assign error = page.url | append: ' must have a description specified!' -%} + {{ error | throw_error }} + {% endunless %} {% if page.short-title %}{{page.short-title}}{% else %}{{page.title}}{% endif %} | {{site.title}} @@ -89,9 +92,11 @@ - {% for css in page.css -%} - + {% if page.css -%} + {% for cssFile in page.css -%} + {% endfor -%} + {% endif -%} - {% for js in page.js -%} - + {% if page.js -%} + {% for jsFile in page.js -%} + {% endfor -%} + {% endif -%} {% include analytics.html %} diff --git a/src/_includes/linter-page-content.md b/src/_includes/linter-page-content.md index 5ea8547f3..d26e0128e 100644 --- a/src/_includes/linter-page-content.md +++ b/src/_includes/linter-page-content.md @@ -2,7 +2,7 @@ {{lint.description}} -{% if lint.sinceDartSdk == "Unreleased" %} +{% if lint.sinceDartSdk == "Unreleased" or lint.sinceDartSdk contains "-wip" %} _This rule is currently **experimental** and not yet available in a stable SDK._ {% elsif lint.state == "removed" %} diff --git a/src/_includes/linter-rules-section.md b/src/_includes/linter-rules-section.md index b3ab80b3d..75f54c6ab 100644 --- a/src/_includes/linter-rules-section.md +++ b/src/_includes/linter-rules-section.md @@ -1,6 +1,6 @@ {% for lint in site.data.linter_rules %} -{% if lint.group == include.type %} +{% if lint.group == include.type and lint.state != "internal" %} {% assign badges = "" %} diff --git a/src/_includes/navigation-main.html b/src/_includes/navigation-main.html index 3d436a77b..c24287f75 100644 --- a/src/_includes/navigation-main.html +++ b/src/_includes/navigation-main.html @@ -36,7 +36,7 @@ + id="search-main" autocomplete="off" placeholder="Search" aria-label="Search"> diff --git a/src/_includes/navigation-side.html b/src/_includes/navigation-side.html index 83672c447..4477c7fa5 100644 --- a/src/_includes/navigation-side.html +++ b/src/_includes/navigation-side.html @@ -1,7 +1,7 @@
+ id="search-side" autocomplete="off" placeholder="Search" aria-label="Search">
@@ -28,6 +28,6 @@ - {% include shared/sidenav-level-1.html nav=site.data.side-nav %} + {% include sidenav-level-1.html nav=site.data.side-nav %}
diff --git a/src/_includes/navigation-toc.html b/src/_includes/navigation-toc.html index 6002eb2dc..f5fa4d614 100644 --- a/src/_includes/navigation-toc.html +++ b/src/_includes/navigation-toc.html @@ -12,6 +12,7 @@ {% endif %} {% if include.extendToc -%} {% assign toc = toc | underscore_breaker: true %} + {% assign toc = toc | replace: 'id="toc" ', '' %} {% assign toc = toc | replace: '
    ', '
      ' %} {% assign toc = toc | replace: '
        ', '
          ' %} {% assign toc = toc | replace: 'class="toc-entry', 'class="toc-entry nav-item' %} diff --git a/src/_includes/page-footer.html b/src/_includes/page-footer.html index 53041668a..c5aaebe2f 100644 --- a/src/_includes/page-footer.html +++ b/src/_includes/page-footer.html @@ -9,6 +9,11 @@ + + + + +
          diff --git a/src/_includes/page-github-links.html b/src/_includes/page-github-links.html new file mode 100644 index 000000000..fbbf2462f --- /dev/null +++ b/src/_includes/page-github-links.html @@ -0,0 +1,21 @@ +{% comment %} +This include file requires the material icons fonts. +Style the button pair using the `#page-github-links` selector. +{% endcomment -%} + +{% assign repo = page.repo | default: site.repo.this -%} +{% capture path -%} {{repo}}/tree/{{site.branch}}/{{site.source}}/{{page.path}} {%- endcapture -%} +{% assign title = page.title | default: page.url -%} +{% assign url = site.url | append: page.url -%} + +{% capture issueTitle -%} title=[页面问题] '{{title}}' {%- endcapture -%} + +
          + + description + + + bug_report + +
          diff --git a/src/_includes/shared b/src/_includes/shared deleted file mode 120000 index 5ef5fe29d..000000000 --- a/src/_includes/shared +++ /dev/null @@ -1 +0,0 @@ -../_shared/_includes \ No newline at end of file diff --git a/src/_includes/sidenav-level-1.html b/src/_includes/sidenav-level-1.html new file mode 100644 index 000000000..3f9f0ade7 --- /dev/null +++ b/src/_includes/sidenav-level-1.html @@ -0,0 +1,37 @@ +{% comment %} Canonicalize page URL path {% endcomment -%} +{% assign page_url_path = page.url | regex_replace: '/index$|/index\.html$|\.html$|/$' -%} + +{% assign active_entries = include.nav | active_nav_entry_index_array: page_url_path -%} +{% assign show_entries_wo_pages = false -%} + +
            + {%- for entry1 in include.nav -%} + + {% assign class1 = '' -%} + {% assign id1 = 'sidenav-' | append: forloop.index -%} + {% assign isActive1 = false -%} + {% if forloop.index == active_entries[0] -%} + {% assign isActive1 = true -%} + {% assign class1 = 'active' -%} + {% endif -%} + + {% if isActive1 or entry1.expanded -%} + {% assign expanded = 'true' -%} + {% assign show = 'show' -%} + {% else -%} + {% assign class1 = 'collapsed' -%} + {% assign expanded = 'false' -%} + {% assign show = '' -%} + {% endif -%} + +
          • + {{entry1.title}} + + +
            • + {%- endfor -%} +
          diff --git a/src/_includes/sidenav-level-2.html b/src/_includes/sidenav-level-2.html new file mode 100644 index 000000000..b34181eb8 --- /dev/null +++ b/src/_includes/sidenav-level-2.html @@ -0,0 +1,61 @@ +{% for entry2 in entry1.children -%} + +{% assign class2 = 'nav-link' -%} +{% assign isActive2 = false -%} +{% if isActive1 and forloop.index == active_entries[1] -%} + {% assign isActive2 = true -%} + {% assign class2 = class2 | append: ' active' -%} +{% endif -%} + +{% if entry2 == 'divider' -%} + +
          + +{%- elsif entry2.children == nil and entry2.permalink or show_entries_wo_pages -%} + +
        • + {{entry2.title}} + {%- if entry2.permalink == nil %} (TBC) + {%- elsif entry2.permalink contains '://' -%} + + open_in_new + + {%- endif -%} + +
          • + +{%- elsif entry2.children -%} + + {% assign class2 = class2 | append: ' collapsable' -%} + + {% if isActive2 or entry2.expanded -%} + {% assign expanded = 'true' -%} + {% assign show = 'show' -%} + {% else -%} + {% assign class2 = class2 | append: ' collapsed' -%} + {% assign expanded = 'false' -%} + {% assign show = '' -%} + {% endif -%} + + {% assign id2 = id1 | append: '-' | append: forloop.index -%} + {% assign href = entry2.permalink -%} + {% unless href -%} + {% assign href = '#' | append: id2 -%} + {% endunless -%} + +
        • + {{entry2.title}} + + +
          • +{% endif -%} +{% endfor %} diff --git a/src/_includes/sidenav-level-3.html b/src/_includes/sidenav-level-3.html new file mode 100644 index 000000000..aae138c09 --- /dev/null +++ b/src/_includes/sidenav-level-3.html @@ -0,0 +1,61 @@ +{% for entry3 in entry2.children -%} + +{% assign class3 = 'nav-link' -%} +{% assign isActive3 = false -%} +{% if isActive2 and forloop.index == active_entries[2] -%} + {% assign isActive3 = true -%} + {% assign class3 = class3 | append: ' active' -%} +{% endif -%} + +{% if entry3 == 'divider' -%} + +
          + +{%- elsif entry3.children == nil and entry3.permalink or show_entries_wo_pages -%} + +
        • + {{entry3.title}} + {%- if entry3.permalink == nil %} (TBC) + {%- elsif entry3.permalink contains '://' -%} + + open_in_new + + {%- endif -%} + +
          • + +{%- elsif entry3.children -%} + + {% assign class3 = class3 | append: ' collapsable' -%} + + {% if isActive3 or entry3.expanded -%} + {% assign expanded = 'true' -%} + {% assign show = 'show' -%} + {% else -%} + {% assign class3 = class3 | append: ' collapsed' -%} + {% assign expanded = 'false' -%} + {% assign show = '' -%} + {% endif -%} + + {% assign id3 = id2 | append: '-' | append: forloop.index -%} + {% assign href = entry3.permalink -%} + {% unless href -%} + {% assign href = '#' | append: id3 -%} + {% endunless -%} + +
        • + {{entry3.title}} + + +
          • +{% endif -%} +{% endfor -%} diff --git a/src/_includes/sidenav-level-4.html b/src/_includes/sidenav-level-4.html new file mode 100644 index 000000000..2c8abcef0 --- /dev/null +++ b/src/_includes/sidenav-level-4.html @@ -0,0 +1,25 @@ +{% for entry4 in entry3.children -%} + {% if entry4.permalink or show_entries_wo_pages -%} + + {% assign class4 = 'nav-link' -%} + {% assign isActive4 = false -%} + {% if isActive3 and forloop.index == active_entries[3] -%} + {% assign isActive4 = true -%} + {% assign class4 = class4 | append: ' active' -%} + {% endif -%} + +
        • + {{entry4.title}} + {%- if entry4.permalink == nil %} (TBC) + {%- elsif entry4.permalink contains '://' -%} + + open_in_new + + {%- endif -%} + +
          • + {% endif -%} +{% endfor -%} diff --git a/src/_layouts/default.html b/src/_layouts/default.html index 5deca1f64..3625aa9a8 100644 --- a/src/_layouts/default.html +++ b/src/_layouts/default.html @@ -1,7 +1,7 @@ {% include head.html %} - + {% include cookie-notice.html %} {% include gtags.html %} {% include page-header.html %} @@ -12,14 +12,14 @@
          {% include navigation-sub.html %}
          - {% include shared/page-github-links.html %} + {% include page-github-links.html %} {% if page.underscore_breaker_titles -%}

          {{page.title | underscore_breaker}}

          {% else %}

          {{page.title }}

          {% endif -%} {% if page.show_breadcrumbs -%} - {% include shared/breadcrumbs.html %} + {% include breadcrumbs.html %} {% endif -%}
          {% include navigation-toc.html id='site-toc--inline' collapsible=true %} diff --git a/src/_plugins/jekyll-pages-directory.rb b/src/_plugins/jekyll-pages-directory.rb deleted file mode 100644 index fab9c8481..000000000 --- a/src/_plugins/jekyll-pages-directory.rb +++ /dev/null @@ -1,51 +0,0 @@ -module Jekyll - class PagesDirGenerator < Generator - def generate(site) - pages_dir = site.config['pages'] || './_pages' - all_raw_paths = Dir["#{pages_dir}/**/*"] - all_raw_paths.each do |f| - - if File.file?(File.join(site.source, '/', f)) - filename = f.match(/[^\/]*$/)[0] - clean_filepath = f.gsub(/^#{pages_dir}\//, '') - clean_dir = extract_directory(clean_filepath) - - site.pages << PagesDirPage.new(site, - site.source, - clean_dir, - filename, - pages_dir) - - end - end - end - - def extract_directory(filepath) - dir_match = filepath.match(/(.*\/)[^\/]*$/) - if dir_match - return dir_match[1] - else - return '' - end - end - end - - class PagesDirPage < Page - - def initialize(site, base, dir, name, pagesdir) - @site = site - @base = base - @dir = dir - @name = name - - process(name) - read_yaml(File.join(base, pagesdir, dir), name) - - data.default_proc = proc do |hash, key| - site.frontmatter_defaults.find(File.join(dir, name), type, key) - end - - Jekyll::Hooks.trigger :pages, :post_init, self - end - end -end \ No newline at end of file diff --git a/src/_plugins/linter_page_generator.rb b/src/_plugins/linter_page_generator.rb index b1619c7f5..faa744b29 100644 --- a/src/_plugins/linter_page_generator.rb +++ b/src/_plugins/linter_page_generator.rb @@ -4,7 +4,9 @@ def generate(site) linter_rules = site.data['linter_rules'] linter_rules.each { |lint| - site.pages << LinterPage.new(site, lint) + unless lint['state'] == 'internal' + site.pages << LinterPage.new(site, lint) + end } end end @@ -21,6 +23,7 @@ def initialize(site, lint) @data = { 'title' => basename, + 'description' => "#{basename} linter rule documentation.", 'layout' => 'linter-rule-standalone', 'lint' => lint, 'underscore_breaker_titles' => true, diff --git a/src/_plugins/throw_error.rb b/src/_plugins/throw_error.rb new file mode 100644 index 000000000..edf7d5730 --- /dev/null +++ b/src/_plugins/throw_error.rb @@ -0,0 +1,7 @@ +module ThrowErrorFilter + def throw_error(message) + raise message + end +end + +Liquid::Template.register_filter(ThrowErrorFilter) diff --git a/src/_sass/_overwrites.scss b/src/_sass/_overwrites.scss index c24b656e4..84c808680 100644 --- a/src/_sass/_overwrites.scss +++ b/src/_sass/_overwrites.scss @@ -1,3 +1,5 @@ +@use 'sass:color'; + @use 'core/variables' as *; @use 'core/bootstrap'; @@ -17,7 +19,7 @@ a { &:hover, &:focus, &:active { code { - color: lighten($default-link, 25%); + color: color.scale($default-link, $lightness: -15%, $saturation: 15%); } } } @@ -39,7 +41,7 @@ a { @media print { /* Don't display navigation aids when printing */ #page-header, #sidenav, #subnav, #page-footer, .banner, - #toc, #site-toc--inline, #site-toc--side, #page-github-links { + #site-toc--inline, #site-toc--side, #page-github-links { display: none !important; } diff --git a/src/_sass/components/_banner.scss b/src/_sass/components/_banner.scss index d9d28a5e5..5f69a5e11 100644 --- a/src/_sass/components/_banner.scss +++ b/src/_sass/components/_banner.scss @@ -8,9 +8,8 @@ z-index: 1000; &__text { - font-family: $site-font-family-base; + font-family: $site-font-family-alt; font-size: 16px; - font-weight: 300; color: white; diff --git a/src/_sass/components/_code.scss b/src/_sass/components/_code.scss index 5b466ac86..76e3a1dde 100644 --- a/src/_sass/components/_code.scss +++ b/src/_sass/components/_code.scss @@ -28,7 +28,7 @@ pre { } .highlight { - background: #ffe600; + background: $flutter-color-yellow; padding: 2px; } } diff --git a/src/_sass/components/_sidebar.scss b/src/_sass/components/_sidebar.scss index 5aecb7224..f47ff5033 100644 --- a/src/_sass/components/_sidebar.scss +++ b/src/_sass/components/_sidebar.scss @@ -204,7 +204,7 @@ } &.active { - color: $site-color-sidebar-active; + color: $brand-primary; font-weight: 400; } } diff --git a/src/_sass/components/_toc.scss b/src/_sass/components/_toc.scss index dce329322..5bd80e255 100644 --- a/src/_sass/components/_toc.scss +++ b/src/_sass/components/_toc.scss @@ -190,7 +190,7 @@ padding: 1px 0; &.active { - color: $site-color-sidebar-active !important; + color: $brand-primary !important; // removing the '>' before the menu item // override shared/_toc.scss diff --git a/src/_sass/core/_base.scss b/src/_sass/core/_base.scss index 05ad4780e..a67fc42bc 100644 --- a/src/_sass/core/_base.scss +++ b/src/_sass/core/_base.scss @@ -64,11 +64,15 @@ a, button { } &:hover, &:focus, &:active { - color: lighten($brand-primary, 25%); + color: $flutter-color-blue-700; outline: none; text-decoration: none; } + &:active { + color: $flutter-color-blue-800; + } + &.external { &:after { @include md-icon-content("launch"); diff --git a/src/_sass/core/_bootstrap.scss b/src/_sass/core/_bootstrap.scss index 52bdac558..1163bf7dc 100644 --- a/src/_sass/core/_bootstrap.scss +++ b/src/_sass/core/_bootstrap.scss @@ -96,9 +96,6 @@ $dropdown-divider-bg: #bbbbbb, $dropdown-link-active-color: transparent, $dropdown-link-active-bg: transparent, - - $popover-font-size: $font-size-base, - $popover-border-color: rgba(0, 0, 0, 0), ); @use '../../../node_modules/bootstrap-scss/bootstrap'; diff --git a/src/_sass/core/_mixins.scss b/src/_sass/core/_mixins.scss index 5ea34fd45..9f19e8f64 100644 --- a/src/_sass/core/_mixins.scss +++ b/src/_sass/core/_mixins.scss @@ -51,7 +51,9 @@ @mixin dart-style-for($kind, $bg-color, $fg-color, $msg) { .#{$kind} { - background-color: $bg-color !important; + @if $bg-color != 'inherit' { + background-color: $bg-color !important; + } position: relative; &:after { @@ -65,4 +67,10 @@ color: $fg-color; } } + + @if $bg-color != 'inherit' { + .#{$kind} pre { + background-color: $bg-color; + } + } } diff --git a/src/_sass/core/_variables.scss b/src/_sass/core/_variables.scss index d5d858409..59a080b86 100644 --- a/src/_sass/core/_variables.scss +++ b/src/_sass/core/_variables.scss @@ -1,17 +1,23 @@ // Colors -$flutter-color-teal: #60caf6; -$flutter-color-blue-500: #1389FD; -$flutter-color-dark-blue: #075b9a; -$flutter-color-fuchsia: #FF2B5B; +$flutter-color-blue: #043875; +$flutter-color-teal: #158477; +$flutter-color-dark-blue: #042B59; +$flutter-color-blue-500: #0468D7; +$flutter-color-blue-600: #0553B1; +$flutter-color-blue-700: $flutter-color-blue; +$flutter-color-blue-800: $flutter-color-dark-blue; +$flutter-color-fuchsia: #E64637; $flutter-color-light-blue: #E7F8FF; +$flutter-color-yellow: #FFF275; +$flutter-color-grey-500: #E8EAED; $site-color-dark-background: #1C2834; $site-color-black: #000; $site-color-white: #FFF; $site-color-codeblock-bg: #F8F9FA; -$site-color-light-grey: #D8D8D8; +$site-color-light-grey: #DADCE0; $site-color-nav-links: #6E7274; -$site-color-body: #4A4A4A; +$site-color-body: #212121; $site-color-body-light: $site-color-body; $site-color-footer: $site-color-dark-background; $site-color-primary: $flutter-color-blue-500; @@ -60,7 +66,6 @@ $site-color-card-text: #f8f9fa; $site-color-card-link: #40C4FF; $site-font-size-header: 16px; $site-color-primary: $brand-primary; -$site-color-sidebar-active: #1389FD; // Sidenav, toc, and footer $font-size-small: 14px; @@ -68,7 +73,7 @@ $font-size-small: 14px; // Spacing $live-content-width: 1280px; $content-padding: 32px; -$top-content-padding: 55px; +$top-content-padding: 40px; // Fonts $site-font-family-roboto: "Google Sans", "Noto Sans SC", Roboto, "Helvetica Neue", "Helvetica", Arial, "PingFang SC", "Hiragino Sans GB", "Heiti SC", "Microsoft YaHei", "WenQuanYi Micro Hei", sans-serif; diff --git a/src/_sass/site.scss b/src/_sass/site.scss index 9d7471a3a..07eb178c3 100644 --- a/src/_sass/site.scss +++ b/src/_sass/site.scss @@ -308,7 +308,11 @@ main .content { opacity: 0; &:hover { - color: lighten($brand-primary, 25%); + color: $brand-primary; + } + + &:active { + color: $flutter-color-blue-700; } } @@ -530,34 +534,6 @@ li.card { } } -// Popovers - -h3.popover-header { - font-weight: $font-weight-light-bold; - margin-top: 0; -} - -@mixin popover-open { - &.popover-open { - font-weight: 500; - border-color: $default-link; - } -} - -[data-toggle="popover"] { - background: none; - border-bottom: 2px dotted $gray; - padding: 0; - cursor: pointer; - @include popover-open; -} - -@media (hover: hover) { - [data-toggle="popover"]:hover { - border-color: $default-link !important; - } -} - .table { width: 100%; @extend .table-striped; @@ -607,6 +583,11 @@ h3.popover-header { background-color: $alert-info-bg; } + &.alert-secondary { + width: auto; + background-color: $flutter-color-grey-500; + } + &.alert-warning { width: auto; background-color: $alert-warning-bg; @@ -686,7 +667,7 @@ ul.nav-list { } &:active { - color: lighten($brand-primary, 25%); + color: $flutter-color-blue-700; } } diff --git a/src/_tutorials/README.md b/src/_tutorials/README.md deleted file mode 100644 index 24b2bb364..000000000 --- a/src/_tutorials/README.md +++ /dev/null @@ -1,35 +0,0 @@ -The tutorial examples, including source for DartPad examples, -live in the "dart-tutorials-samples" repo on GitHub. - -DartPad grabs source for these examples from "gist" files. -The gist files are generated from the source in the sample repo, -using the gist-generator. - -For info on how to generate the gist files, see: -https://github.com/dart-lang/dart-tutorials-samples/blob/master/README.md - -To generate the gist files, you need to use a gist token/password. -Get the token from the creator of the original gist file. - -Location of relevant resources: - -GitHub repo for tutorials examples: -https://github.com/dart-lang/dart-tutorials-samples - -Gist files: -https://gist.github.com/ - -Gist generator: -https://github.com/kasperpeulen/gist-generator - -DartPad: -{{site.dartpad}} - -Definitions for the DartPad constants used on dartlang: -src/site/_config.yml - -Embedding Guide for DartPad: -https://github.com/dart-lang/dart-pad/wiki/Embedding-Guide - -Defined constants for embedding DartPad: -/src/site/_config.yml diff --git a/src/_tutorials/server/_dcat-example.html b/src/_tutorials/server/_dcat-example.html deleted file mode 100644 index f4e570d6e..000000000 --- a/src/_tutorials/server/_dcat-example.html +++ /dev/null @@ -1,55 +0,0 @@ -{%- comment %} -WARNING: Do NOT EDIT this file directly. It is autogenerated by - tool/create_code_with_tooltips.dart -from sources in the example folder. -{% endcomment -%} -
          -import 'dart:convert';
-import 'dart:io';
-
-import 'package:args/args.dart';
-
-const lineNumber = 'line-number';
-
-void main(List<String> arguments) {
-  exitCode = 0; // presume success
-  final parser = ArgParser()..addFlag(lineNumber, negatable: false, abbr: 'n');
-
-  ArgResults argResults = parser.parse(arguments);
-  final paths = argResults.rest;
-
-  dcat(paths, showLineNumbers: argResults[lineNumber] as bool);
-}
-
-Future<void> dcat(List<String> paths, {bool showLineNumbers = false}) async {
-  if (paths.isEmpty) {
-    // No files provided as arguments. Read from stdin and print each line.
-    await stdin.pipe(stdout);
-  } else {
-    for (final path in paths) {
-      var lineNumber = 1;
-      final lines = utf8.decoder
-          .bind(File(path).openRead())
-          .transform(const LineSplitter());
-      try {
-        await for (final line in lines) {
-          if (showLineNumbers) {
-            stdout.write('${lineNumber++} ');
-          }
-          stdout.writeln(line);
-        }
-      } catch (_) {
-        await _handleError(path);
-      }
-    }
-  }
-}
-
-Future<void> _handleError(String path) async {
-  if (await FileSystemEntity.isDirectory(path)) {
-    stderr.writeln('error: $path is a directory');
-  } else {
-    exitCode = 2;
-  }
-}
-
          diff --git a/src/_articles/archive/converters-and-codecs.md b/src/articles/archive/converters-and-codecs.md similarity index 91% rename from src/_articles/archive/converters-and-codecs.md rename to src/articles/archive/converters-and-codecs.md index 130e7fe60..90dc56970 100644 --- a/src/_articles/archive/converters-and-codecs.md +++ b/src/articles/archive/converters-and-codecs.md @@ -18,13 +18,13 @@ core library that provides a set of converters and useful tools to build new converters. Examples of converters provided by the library include those for commonly used encodings such as JSON and UTF-8. -In this document, we show how Dart’s +In this document, we show how Dart's converters work and how you can create your own efficient converters that fit into the Dart world. ## Big picture -Dart’s conversion architecture is +Dart's conversion architecture is based on _converters_, which translate from one representation to another. When conversions are reversible, two converters are grouped together into a _codec_ (coder-decoder). The term codec is frequently used for audio and @@ -44,7 +44,7 @@ they had been used separately. A codec is a combination of two converters where one encodes and the other one decodes: -{% prettify dart tag=pre+code %} +```dart abstract class Codec { const Codec(); @@ -57,7 +57,7 @@ abstract class Codec { Codec fuse(Codec other) { .. } Codec get inverted => ...; } -{% endprettify %} +``` As can be seen, codecs provide convenience methods such as `encode()` and `decode()` that are expressed in terms of the encoder and decoder. The `fuse()` @@ -67,7 +67,7 @@ The base implementation of [Codec]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-convert/Codec-class.html) for these two members provides a solid default implementation -and implementers usually don’t need to worry about them. +and implementers usually don't need to worry about them. The `encode()` and `decode()` methods, too, may be left untouched, but they can be extended for additional @@ -76,19 +76,19 @@ arguments. For example, the adds named arguments to `encode()` and `decode()` to make these methods more useful: -{% prettify dart tag=pre+code %} +```dart dynamic decode(String source, {reviver(var key, var value)}) { … } String encode(Object value, {toEncodable(var object)}) { … } -{% endprettify %} +``` The codec can be instantiated with arguments that are used as default values, unless they are overridden by the named arguments during the `encode()`/`decode()` call. -{% prettify dart tag=pre+code %} +```dart const JsonCodec({reviver(var key, var value), toEncodable(var object)}) ... -{% endprettify %} +``` As a general rule: if a codec can be configured, it should add named arguments to the `encode()`/`decode()` methods and allow their defaults to be @@ -100,9 +100,9 @@ When possible, codec constructors should be `const` constructors. Converters, and in particular their `convert()` methods, are where the real conversions happen: -{% prettify dart tag=pre+code %} +```dart T convert(S input); // where T is the target and S the source type. -{% endprettify %} +``` A minimal converter implementation only needs to extend the [Converter]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-convert/Converter-class.html) class and @@ -112,7 +112,7 @@ the `convert()` method. Such a minimal converter works in synchronous settings, but does not work when used with chunks (either synchronously or asynchronously). In -particular, such a simple converter doesn’t work as a transformer (one of the +particular, such a simple converter doesn't work as a transformer (one of the nicer features of Converters). A fully implemented converter implements the [StreamTransformer]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-async/StreamTransformer-class.html) interface and can thus be given to the `Stream.transform()` method. @@ -120,21 +120,21 @@ interface and can thus be given to the `Stream.transform()` method. Probably the most common use case is the decoding of UTF-8 with [utf8.decoder]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-convert/Utf8Codec-class.html): -{% prettify dart tag=pre+code %} +```dart File.openRead().transform(utf8.decoder). -{% endprettify %} +``` ## Chunked conversion The concept of chunked conversions can be confusing, but at its core, it is relatively simple. When a chunked conversion (including a stream -transformation) is started, the converter’s +transformation) is started, the converter's [startChunkedConversion]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-convert/Converter/startChunkedConversion.html) method is invoked with an output- sink as argument. The method then returns an input sink into which the caller puts data. -![Chunked conversion](/articles/archive/images/chunked-conversion.png) +![Chunked conversion](/assets/img/converters-and-codecs/chunked-conversion.png) **Note**: An asterisk (`*`) in the diagram represents optional multiple calls. @@ -181,11 +181,11 @@ has the same signature as HtmlEscape: String→String. In this case each individual output chunk represents one line. -{% prettify dart tag=pre+code %} +```dart import 'dart:convert'; import 'dart:async'; -main() async { +void main() async { // HtmlEscape synchronously converts Strings to Strings. print(const HtmlEscape().convert("foo")); // "foo". // When used in a chunked way it converts from Strings @@ -202,7 +202,7 @@ main() async { print("${await (stream2.transform(const LineSplitter()) .toList())}"); } -{% endprettify %} +``` In general, the type of the chunked conversion is determined by the most useful case when used as a StreamTransformer. @@ -229,19 +229,21 @@ ChunkedConversionSink that support more efficient ways of passing data. For instance, the [ByteConversionSink]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-convert/ByteConversionSink-class.html), -has the additional method +has the additional method: -`addSlice(List chunk, int start, int end, bool isLast)` +```dart +void addSlice(List chunk, int start, int end, bool isLast); +``` Semantically, it accepts a list (which may not be held onto), the sub-range that the converter operates on, and a boolean `isLast`, which can be set instead of calling `close()`. -{% prettify dart tag=pre+code %} +```dart import 'dart:convert'; -main() { +void main() { var outSink = new ChunkedConversionSink.withCallback((chunks) { print(chunks.single); // 𝅘𝅥𝅯 }); @@ -254,7 +256,7 @@ main() { list[1] = 0xA1; inSink.addSlice(list, 0, 2, true); } -{% endprettify %} +``` As a user of the chunked conversion sink (which is used both as input and output of converters), this simply provides more choice. The fact that the list is not @@ -278,10 +280,10 @@ not break the extended sinks._ This section shows all the steps needed to create a simple encryption converter and how a custom ChunkedConversionSink can improve performance. -Let’s start with the simple synchronous converter, +Let's start with the simple synchronous converter, whose encryption routine simply rotates bytes by the given key: -{% prettify dart tag=pre+code %} +```dart import 'dart:convert'; /// A simple extension of Rot13 to bytes and a key. @@ -298,11 +300,11 @@ class RotConverter extends Converter, List> { return result; } } -{% endprettify %} +``` The corresponding Codec class is also simple: -{% prettify dart tag=pre+code %} +```dart class Rot extends Codec, List> { final _key; const Rot(this._key); @@ -320,18 +322,18 @@ class Rot extends Codec, List> { RotConverter get encoder => new RotConverter(_key); RotConverter get decoder => new RotConverter(-_key); } -{% endprettify %} +``` We can (and should) avoid some of the `new` allocations, but for simplicity we allocate a new instance of RotConverter every time one is needed. This is how we use the Rot codec: -{% prettify dart tag=pre+code %} +```dart const Rot ROT128 = const Rot(128); const Rot ROT1 = const Rot(1); -main() { +void main() { print(const RotConverter(128).convert([0, 128, 255, 1])); // [128, 0, 127, 129] print(const RotConverter(128).convert([128, 0, 127, 129])); // [0, 128, 255, 1] print(const RotConverter(-128).convert([128, 0, 127, 129]));// [0, 128, 255, 1] @@ -339,13 +341,13 @@ main() { print(ROT1.decode(ROT1.encode([0, 128, 255, 1]))); // [0, 128, 255, 1] print(ROT128.decode(ROT128.encode([0, 128, 255, 1]))); // [0, 128, 255, 1] } -{% endprettify %} +``` We are on the right track. The codec works, but it is still missing the chunked encoding part. Because each byte is encoded separately we can fall back to the synchronous conversion method: -{% prettify dart tag=pre+code %} +```dart class RotConverter { ... RotSink startChunkedConversion(sink) { @@ -366,15 +368,15 @@ class RotSink extends ChunkedConversionSink> { _outSink.close(); } } - -{% endprettify %} +``` Now, we can use the converter with chunked conversions or even for stream transformations: -{% prettify dart tag=pre+code %} -// Requires importing dart:io. -main(args) { +```dart +import 'dart:io'; + +void main(List args) { String inFile = args[0]; String outFile = args[1]; int key = int.parse(args[2]); @@ -383,13 +385,13 @@ main(args) { .transform(new RotConverter(key)) .pipe(new File(outFile).openWrite()); } -{% endprettify %} +``` ### Specialized ChunkedConversionSinks For many purposes, the current version of Rot is sufficient. That is, the benefit of improvements would be outweighed by the cost of more complex code -and test requirements. Let’s assume, however, +and test requirements. Let's assume, however, that the performance of the converter is critical (it's on the hot path and up on the profile). We furthermore assume that @@ -399,14 +401,14 @@ the cost of allocating a new list for every chunk is killing performance We start by making the allocation cost cheaper: by using a [typed byte-list]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-typed_data/Uint8List-class.html) we can reduce the size of the allocated list by a factor of 8 (on 64-bit -machines). This one line change doesn’t remove the allocation, but makes it much +machines). This one line change doesn't remove the allocation, but makes it much cheaper. We can also avoid the allocation altogether if we overwrite the input. In the following version of RotSink, we add a new method `addModifiable()` that does exactly that: -{% prettify dart tag=pre+code %} +```dart class RotSink extends ChunkedConversionSink> { final _key; final ChunkedConversionSink> _outSink; @@ -427,7 +429,7 @@ class RotSink extends ChunkedConversionSink> { _outSink.close(); } } -{% endprettify %} +``` For simplicity we propose a new method that consumes a complete list. A more advanced method (for example `addModifiableSlice()`) would take range arguments @@ -436,9 +438,8 @@ advanced method (for example `addModifiableSlice()`) would take range arguments This new method is not yet used by transformers, but we can already use it when invoking `startChunkedConversion()` explicitly. -{% prettify dart tag=pre+code %} - -main() { +```dart +void main() { var outSink = new ChunkedConversionSink.withCallback((chunks) { print(chunks); // [[31, 32, 33], [24, 25, 26]] }); @@ -447,12 +448,12 @@ main() { inSink.addModifiable([250, 251, 252]); inSink.close(); } -{% endprettify %} +``` In this small example, performance isn't visibly different, but internally the chunked conversion avoids allocating new lists for the individual chunks. -For two small chunks, it doesn’t make a difference, but +For two small chunks, it doesn't make a difference, but if we implement this for the stream transformer, encrypting a bigger file can be noticeably faster. @@ -465,7 +466,7 @@ such a converter would be the potential source of hard-to-track bugs. Instead, we write a converter that does the unmodifiable-to-modifiable conversion explicitly, and then fuse the two converters. -{% prettify dart tag=pre+code %} +```dart class ToModifiableConverter extends Converter, List> { List convert(List data) => data; ToModifiableSink startChunkedConversion(RotSink sink) { @@ -481,13 +482,13 @@ class ToModifiableSink void add(List data) { sink.addModifiable(data); } void close() { sink.close(); } } -{% endprettify %} +``` ToModifiableSink just signals the next sink that the incoming chunk is modifiable. We can use this to make our pipeline more efficient: -{% prettify dart tag=pre+code %} -main(args) { +```dart +void main(List args) { String inFile = args[0]; String outFile = args[1]; int key = int.parse(args[2]); @@ -497,7 +498,7 @@ main(args) { new ToModifiableConverter().fuse(new RotConverter(key))) .pipe(new File(outFile).openWrite()); } -{% endprettify %} +``` On my machine, this small modification brought the encryption time of an 11MB file from 450ms down to 260ms. We achieved this speed up without losing @@ -509,12 +510,12 @@ converters and not just with our Rot cipher. We should therefore make an interface that generalizes the concept. For simplicity, we named it `CipherSink`, although it has, of course, uses outside the encryption world. -{% prettify dart tag=pre+code %} +```dart abstract class CipherSink extends ChunkedConversionSink, List> { void addModifiable(List data) { add(data); } } -{% endprettify %} +``` We can then make our RotSink private and expose the CipherSink instead. Other developers can now reuse our work (CipherSink and ToModifiableConverter) @@ -522,12 +523,12 @@ and benefit from it. But we are not done yet. -Although we won’t make the cipher faster anymore, +Although we won't make the cipher faster anymore, we can improve the output side of our Rot converter. Take, for instance, the fusion of two encryptions: -{% prettify dart tag=pre+code %} -main(args) { +```dart +void main(List args) { String inFile = args[0]; String outFile = args[1]; int key = int.parse(args[2]); @@ -540,18 +541,18 @@ main(args) { .transform(transformer) .pipe(new File(outFile).openWrite()); } -{% endprettify %} +``` Since the first RotConverter invokes `outSink.add()`, the second RotConverter assumes that input cannot be modified and allocates a copy. We can work around this by sandwiching a ToModifiableConverter in between the two ciphers: -{% prettify dart tag=pre+code %} +```dart var transformer = new ToModifiableConverter() .fuse(new RotConverter(key)) .fuse(new ToModifiableConverter()) .fuse(new RotConverter(key)); -{% endprettify %} +``` This works, but is hackish. We want the RotConverters to work without intermediate converters. The first cipher should look at the outSink and @@ -560,18 +561,18 @@ whenever we want to add a new chunk, or at the beginning when we start a chunked conversion. We prefer the latter approach: -{% prettify dart tag=pre+code %} +```dart /// Works more efficiently if given a CipherSink as argument. CipherSink startChunkedConversion( ChunkedConversionSink> sink) { if (sink is! CipherSink) sink = new _CipherSinkAdapter(sink); return new _RotSink(_key, sink); } -{% endprettify %} +``` _CipherSinkAdapter is simply: -{% prettify dart tag=pre+code %} +```dart class _CipherSinkAdapter implements CipherSink { ChunkedConversionSink, List> sink; _CipherSinkAdapter(this.sink); @@ -580,12 +581,12 @@ class _CipherSinkAdapter implements CipherSink { void addModifiable(data) { sink.add(data); } void close() { sink.close(); } } -{% endprettify %} +``` We now only need to change the _RotSink to take advantage of the fact that it always receives a CipherSink as an argument to its constructor: -{% prettify dart tag=pre+code %} +```dart class _RotSink extends CipherSink { final _key; final CipherSink _outSink; // <= always a CipherSink. @@ -606,9 +607,9 @@ class _RotSink extends CipherSink { _outSink.close(); } } -{% endprettify %} +``` -With these changes our super secure, double cipher won’t allocate any new lists +With these changes our super secure, double cipher won't allocate any new lists and our work is done. Thanks to Lasse Reichstein Holst Nielsen, Anders Johnsen, and Matias Meno who diff --git a/src/_articles/archive/index.md b/src/articles/archive/index.md similarity index 93% rename from src/_articles/archive/index.md rename to src/articles/archive/index.md index fe70b4baa..2f6c41f32 100644 --- a/src/_articles/archive/index.md +++ b/src/articles/archive/index.md @@ -10,7 +10,6 @@ and [zones][] articles haven't been updated in a long time, but have background information that isn't available anywhere else. To find newer articles, see the [Dart publication on medium.com.](https://medium.com/dartlang) -Also see the [Articles page](/articles). [converters and codecs]: /articles/archive/converters-and-codecs [numeric computation]: /articles/archive/numeric-computation diff --git a/src/_articles/archive/numeric-computation.md b/src/articles/archive/numeric-computation.md similarity index 85% rename from src/_articles/archive/numeric-computation.md rename to src/articles/archive/numeric-computation.md index 2e2d0af4c..914716c91 100644 --- a/src/_articles/archive/numeric-computation.md +++ b/src/articles/archive/numeric-computation.md @@ -3,7 +3,6 @@ title: Numeric computation description: How you store and use numbers can have a big impact on your app's performance. This article focuses on the Dart VM. original-date: 2013-05-22 date: 2018-07-26 -category: dart-vm obsolete: true --- @@ -30,7 +29,7 @@ Just following a few simple rules can give you 50-100% speed improvements. Follow the guidelines in this article to get the most performance from the Dart VM in numerical applications. -You’ll learn about the four different number representations, +You'll learn about the four different number representations, how integer and floating-point numerical computation occurs, and how to pick the best container for your data. @@ -48,10 +47,12 @@ The former is an arbitrary-precision signed integer, and the latter is the IEEE-754 double-precision floating-point number. Examples: - int speed = 3232943523452345329384234242323523; - int hitPoints = 21; - double position = 32.43432; - double hp = hitPoints.toDouble(); +```dart +int speed = 3232943523452345329384234242323523; +int hitPoints = 21; +double position = 32.43432; +double hp = hitPoints.toDouble(); +``` ### Integers @@ -92,14 +93,16 @@ as numbers grow and shrink in range. Here is an example of how a single integer value in the VM graduates from smi to mint to bigint: - main() { - int hitPoints = 21; // starts as a smi - print(hitPoints); // 21 - hitPoints += potionOfSuperHealth.points; // becomes a mint - print(hitPoints); // 2133232342342423 - hitPoints += spellOfNearlyInvinciblity.points; // becomes a bigint - print(hitPoints); // 99999999999999999999999999999999999999999 - } +```dart +void main() { + int hitPoints = 21; // starts as a smi + print(hitPoints); // 21 + hitPoints += potionOfSuperHealth.points; // becomes a mint + print(hitPoints); // 2133232342342423 + hitPoints += spellOfNearlyInvinciblity.points; // becomes a bigint + print(hitPoints); // 99999999999999999999999999999999999999999 +} +``` ### Floating-point numbers @@ -139,15 +142,17 @@ _object lists_ and _typed lists_. A List stores a list of objects. Examples include: - var a = [ 1.0, 2.0, 3.0 ]; - var b = new List(3); // Create a new list with a fixed length of 3. - b[0] = 5; - b[1] = 99; - b[2] = 34; +```dart +var a = [ 1.0, 2.0, 3.0 ]; +var b = new List(3); // Create a new list with a fixed length of 3. +b[0] = 5; +b[1] = 99; +b[2] = 34; +``` The list `b` is an object list, meaning it can store any object—for example, a String object or null. -This means that each entry in a List is as wide as the CPU’s pointer type. +This means that each entry in a List is as wide as the CPU's pointer type. #### Typed lists @@ -162,19 +167,21 @@ When working with numbers that are smaller than the pointer width, these lists can have considerable memory savings. Some examples: - var a = new Float64List(3); - a[0] = 1.0; - a[1] = 2.0; - a[2] = 3.0; - var b = new Int8List(3); - b[0] = 5; - b[1] = 99; - b[2] = 34; +```dart +var a = new Float64List(3); +a[0] = 1.0; +a[1] = 2.0; +a[2] = 3.0; +var b = new Int8List(3); +b[0] = 5; +b[1] = 99; +b[2] = 34; +``` In both the object list and typed list examples, the lists named `a` are holding the same values. Same for the lists named `b`. -What’s different is how the values are stored in memory +What's different is how the values are stored in memory and how they are accessed. More on this later. @@ -200,7 +207,7 @@ The first representation, smi, is the same size as a pointer on your platform, minus 1 bit. On a 32-bit machine, a smi holds a 31-bit signed integer. On a 64-bit machine, a smi holds a 63-bit signed integer. -A smi doesn’t require a memory allocation to be created +A smi doesn't require a memory allocation to be created and is stored directly in a field. The VM can do this by storing twice the numeric value, guaranteeing the low bit being 0. @@ -223,37 +230,41 @@ addition—do not require the smi to be untagged. Consider an object called `entity`, defined as follows: - class Entity { - Entity() { - scale = 2; - x = 3; - y = 0x40000000; - } - int scale; - int x; - int y; - } - - Entity entity = new Entity(); +```dart +class Entity { + Entity() { + scale = 2; + x = 3; + y = 0x40000000; + } + int scale; + int x; + int y; +} + +Entity entity = new Entity(); +``` After the above code executes, in memory on a 32-bit machine the `entity` object looks like this: -![x and scale are smis and thus stored directly; y is 2^30, so it requires a pointer to memory](images/1.png) +![x and scale are smis and thus stored directly; y is 2^30, so it requires a pointer to memory](/assets/img/articles/numeric-computation/1.png) Now consider this Dart code: - entity.x = entity.x * entity.scale; +```dart +entity.x = entity.x * entity.scale; +``` -It’s converted into the VM instructions shown in the following figure. +It's converted into the VM instructions shown in the following figure. Each VM instruction can return a value shown as v1, v2, and so on. -![3 values are needed (for x, scale, and the result)](images/2.png) +![3 values are needed (for x, scale, and the result)](/assets/img/articles/numeric-computation/2.png) After that code executes, in memory the `entity` object looks like this: -![Same memory illustration as before, except the value of x is now 24](images/3.png) +![Same memory illustration as before, except the value of x is now 24](/assets/img/articles/numeric-computation/3.png) Now consider the second representation, mint, which holds a 64-bit signed integer. @@ -265,13 +276,15 @@ before loading the actual value. The following Dart code is converted into the VM instructions shown below. - entity.y = entity.y + entity.x; +```dart +entity.y = entity.y + entity.x; +``` -![6 values are needed (for y, x, unboxed y, unboxed x, the result, and the boxed result](images/4.png) +![6 values are needed (for y, x, unboxed y, unboxed x, the result, and the boxed result](/assets/img/articles/numeric-computation/4.png) After that code executes, in memory the `entity` object looks like this: -![y's previous memory is now garbage, and a new memory location holds y's new value](images/5.png) +![y's previous memory is now garbage, and a new memory location holds y's new value](/assets/img/articles/numeric-computation/5.png) **Performance tip:** If you can, stay in smi range. @@ -289,14 +302,18 @@ you must be careful that the values remain in smi range. The VM performs an optimization when it sees a left shift masked with a constant smi value: - result = (int1 << int2) & CONSTANT; // CONSTANT within smi range +```dart +result = (int1 << int2) & CONSTANT; // CONSTANT within smi range +``` For example: - a = (b << c) & 0x3FFFFFFF; +```dart +a = (b << c) & 0x3FFFFFFF; +``` The VM knows that the result can be stored in a smi, -and it generates code that doesn’t check whether +and it generates code that doesn't check whether a mint is needed to store the result. The constant 0x3FFFFFFF is the maximum positive smi on 32-bit architectures. 0x3FFFFFFFFFFFFFFF is the equivalent constant on 64-bit architectures. @@ -329,9 +346,11 @@ These operations can add overhead when working with typed lists. Consider the following code, assuming that all integer variables stay within the smi range: - for (int i = 0; i < list.length; i++) { - list[i] = list[i] + b; - } +```dart +for (int i = 0; i < list.length; i++) { + list[i] = list[i] + b; +} +``` If `list` is an object list, no smi tagging or untagging occurs. @@ -362,7 +381,7 @@ and better CPU cache performance: * Typed lists can be much more dense. For example, if you know you need only 8 bits of precision you can use an Int8List, - using much less memory and making better use of your CPU’s cache. + using much less memory and making better use of your CPU's cache. In general and specifically because of the above caveats, it is always a good idea to benchmark @@ -391,7 +410,7 @@ Thus, bigints are significantly more expensive than smis or mints. **Performance tip:** Avoid bigint whenever possible. -The VM doesn’t optimize operations on bigint instances. +The VM doesn't optimize operations on bigint instances. ### Doubles @@ -451,7 +470,7 @@ The following operations can trigger a number to be boxed: Boxing requires a memory allocation and a store. Unboxing requires a load. -![Illustration of boxing and unboxing 3.14159](images/6.png) +![Illustration of boxing and unboxing 3.14159](/assets/img/articles/numeric-computation/6.png) ### Lists @@ -471,7 +490,7 @@ When type checking is not enforced, object lists can hold objects of any type. Object lists can contain the null object. -![Illustration of a list's memory, which contains a smi (4) and two points to doubles (1.0 and 2.0)](images/7.png) +![Illustration of a list's memory, which contains a smi (4) and two points to doubles (1.0 and 2.0)](/assets/img/articles/numeric-computation/7.png) Loading a number from an object list works like this: @@ -481,7 +500,7 @@ Loading a number from an object list works like this: 2. The address of the number or the tagged smi is loaded from the list backing store. -![Illustration of loading a number from an object list](images/8.png) +![Illustration of loading a number from an object list](/assets/img/articles/numeric-computation/8.png) Storing a number into an object list works like this: @@ -493,7 +512,7 @@ Storing a number into an object list works like this: 3. The address of the number or the tagged smi value is stored in the list backing store. -![Illustration of storing a number into an object list](images/9.png) +![Illustration of storing a number into an object list](/assets/img/articles/numeric-computation/9.png) #### Typed lists @@ -502,9 +521,9 @@ Each entry in the array always holds the value directly. Typed lists can be much denser, providing better memory and CPU cache usage. Typed lists are also faster to process at garbage collection time -because they don’t have to be scanned for object pointers. +because they don't have to be scanned for object pointers. -![Illustration of a typed list's memory, containing the numbers 4, 1.0, and 2.0 (and no pointers)](images/10.png) +![Illustration of a typed list's memory, containing the numbers 4, 1.0, and 2.0 (and no pointers)](/assets/img/articles/numeric-computation/10.png) Loading a double-precision number from a typed data list works like this: @@ -513,7 +532,7 @@ Loading a double-precision number from a typed data list works like this: this includes a dependent load.) 2. The value is loaded from the list backing store. -![Illustration of loading a number from a typed list](images/11.png) +![Illustration of loading a number from a typed list](/assets/img/articles/numeric-computation/11.png) Storing a double-precision number into a typed data list works like this: @@ -522,7 +541,7 @@ Storing a double-precision number into a typed data list works like this: this includes a dependent load.) 2. The double number is stored into the list backing store. -![Illustration of storing a number into a typed list](images/12.png) +![Illustration of storing a number into a typed list](/assets/img/articles/numeric-computation/12.png) Loading an integer number from a typed list can be more expensive than the double case in the following two cases: diff --git a/src/_articles/archive/zones.md b/src/articles/archive/zones.md similarity index 97% rename from src/_articles/archive/zones.md rename to src/articles/archive/zones.md index 2a0f1298f..2fe4f8cf5 100644 --- a/src/_articles/archive/zones.md +++ b/src/articles/archive/zones.md @@ -1,6 +1,8 @@ --- title: Zones -description: "Manage your asynchronous code: handle uncaught errors, override behavior (such as printing and scheduling tasks), and more." +description: >- + Manage your asynchronous code: handle uncaught errors, + override behavior (such as printing and scheduling tasks), and more. date: 2014-03-03 obsolete: true --- @@ -67,8 +69,8 @@ Zones make the following tasks possible: or saving a stack trace. You might have encountered something similar to zones in other languages. -_Domains_ in Node.js were an inspiration for Dart’s zones. -Java’s _thread-local storage_ +_Domains_ in Node.js were an inspiration for Dart's zones. +Java's _thread-local storage_ also has some similarities. Closest of all is Brian Ford's JavaScript port of Dart zones, [zone.js](https://github.com/btford/zone.js/), which he describes in @@ -116,7 +118,7 @@ qux(x) => ...qux-body... The following figure shows the code's execution order, as well as which zone the code executes in. -![illustration of program execution](images/trace.png) +![illustration of program execution](/assets/img/articles/zones/trace.png) Each call to `runZoned()` creates a new zone and executes code in that zone. @@ -129,7 +131,7 @@ runs in even though it's attached to a future that itself runs in zone #2. -Child zones don’t completely replace their parent zone. +Child zones don't completely replace their parent zone. Instead new zones are nested inside their surrounding zone. For example, zone #2 contains @@ -357,7 +359,7 @@ runZoned(() { }, zoneValues: { #key: 499 }); {% endprettify %} -To read zone-local values, use the zone’s index operator and the value's key: +To read zone-local values, use the zone's index operator and the value's key: [key]. Any object can be used as a key, as long as it has compatible `operator ==` and `hashCode` implementations. @@ -378,7 +380,7 @@ runZoned(() { {% endprettify %} A zone inherits zone-local values from its parent zone, -so adding nested zones doesn’t accidentally drop existing values. +so adding nested zones doesn't accidentally drop existing values. Nested zones can, however, shadow parent values. {{site.alert.important}} @@ -417,7 +419,7 @@ main() { {% endprettify %} This program works, -but let’s assume that you now want to know +but let's assume that you now want to know which file each line comes from, and that you can't just add a filename argument to `splitLinesStream()`. With zone-local values you can add the filename to the returned string diff --git a/src/_articles/libraries/creating-streams.md b/src/articles/libraries/creating-streams.md similarity index 99% rename from src/_articles/libraries/creating-streams.md rename to src/articles/libraries/creating-streams.md index 3d0eff5ec..98409302c 100644 --- a/src/_articles/libraries/creating-streams.md +++ b/src/articles/libraries/creating-streams.md @@ -5,7 +5,6 @@ description: A stream is a sequence of results; learn how to create your own. description: Stream 是一个结果序列，本篇带你学会如何创建自己的 Stream。 original-date: 2013-04-08 date: 2021-05-16 -category: libraries --- -

          What's the point?

          * Command-line applications need to do input and output. - * The dart:io library provides I/O functionality. + * The `dart:io` library provides I/O functionality. * The args package helps define and parse command-line arguments. * A `Future` object represents a value that will be available at some time in the future. * Streams provide a series of asynchronous data events. @@ -35,8 +30,8 @@ prevpage: {{site.alert.note}} This tutorial uses the `async` and `await` language features, which rely on - the [Future]({{_api}}/dart-async/Future-class.html) and - [Stream]({{_api}}/dart-async/Stream-class.html) + the [`Future`]({{_api}}/dart-async/Future-class.html) and + [`Stream`]({{_api}}/dart-async/Stream-class.html) classes for asynchronous support. To learn more about these features, see the [asynchronous programming codelab](/codelabs/async-await) and the @@ -56,9 +51,9 @@ The `dart` commands are included with the [Dart SDK](/tools/sdk). {{site.alert.important}} The location of the SDK installation directory - (we'll call it _<sdk-install-dir>_) depends on your platform + (we'll call it ``) depends on your platform and how you installed the SDK. - You can find `dart` in _<sdk-install-dir>_/bin. + You can find `dart` in `/bin`. By putting this directory in your PATH you can refer to the `dart` command by name. {{site.alert.end}} @@ -88,12 +83,63 @@ Use `dart --verbose` to see all options. ## Overview of the dcat app code This tutorial covers the details of a small sample app called `dcat`, which -displays the contents of any files listed on the command line. This app uses -various classes, functions, and properties available to command-line apps. For a -brief description of key app features, click the highlighted code below. +displays the contents of any files listed on the command line. +This app uses various classes, functions, and properties +available to command-line apps. +Continue on in the tutorial to learn about each part of the app +and the various APIs used. + + +```dart +import 'dart:convert'; +import 'dart:io'; + +import 'package:args/args.dart'; + +const lineNumber = 'line-number'; -{% include_relative _dcat-example.html %} +void main(List arguments) { + exitCode = 0; // Presume success + final parser = ArgParser()..addFlag(lineNumber, negatable: false, abbr: 'n'); + ArgResults argResults = parser.parse(arguments); + final paths = argResults.rest; + + dcat(paths, showLineNumbers: argResults[lineNumber] as bool); +} + +Future dcat(List paths, {bool showLineNumbers = false}) async { + if (paths.isEmpty) { + // No files provided as arguments. Read from stdin and print each line. + await stdin.pipe(stdout); + } else { + for (final path in paths) { + var lineNumber = 1; + final lines = utf8.decoder + .bind(File(path).openRead()) + .transform(const LineSplitter()); + try { + await for (final line in lines) { + if (showLineNumbers) { + stdout.write('${lineNumber++} '); + } + stdout.writeln(line); + } + } catch (_) { + await _handleError(path); + } + } + } +} + +Future _handleError(String path) async { + if (await FileSystemEntity.isDirectory(path)) { + stderr.writeln('error: $path is a directory'); + } else { + exitCode = 2; + } +} +``` ### Getting dependencies @@ -117,9 +163,10 @@ with the [`dart create`](/tools/dart-create) command. $ cd dcat ``` -3. Inside the `dcat` directory, use [dart pub add](/tools/pub/cmd/pub-add) - to add the `args` package as a dependency. This adds `args` to - the list of your dependencies found in the `pubspec.yaml` file. +3. Inside the `dcat` directory, use [`dart pub add`](/tools/pub/cmd/pub-add) + to add the `args` package as a dependency. + This adds `args` to the list of your dependencies + found in the `pubspec.yaml` file. ```terminal $ dart pub add args @@ -128,9 +175,9 @@ with the [`dart create`](/tools/dart-create) command. 4. Open the `bin/dcat.dart` file and copy the preceding code into it. {{site.alert.note}} - To learn more about using packages and organizing your code, see the - [package documentation](/guides/packages) and - [layout conventions](/tools/pub/package-layout). + To learn more about using packages and organizing your code, check out + [How to use packages](/guides/packages) and + [Package layout conventions](/tools/pub/package-layout). {{site.alert.end}} ### Running dcat @@ -147,20 +194,21 @@ $ dart run bin/dcat.dart -n pubspec.yaml 4 # repository: https://github.com/my_org/my_repo 5 6 environment: -7 sdk: '>=2.19.0 <3.0.0' +7 sdk: ^3.2.0 8 -9 # dependencies: -10 # path: ^1.8.0 -11 -12 dev_dependencies: -13 lints: ^2.0.0 -14 test: ^1.21.0 -15 dependencies: -16 args: ^2.3.2 +9 # Add regular dependencies here. +10 dependencies: +11 args: ^2.4.2 +12 # path: ^1.8.0 +13 +14 dev_dependencies: +15 lints: ^2.1.0 +16 test: ^1.24.0 ``` -This command displays each line of the specified file. Because the `-n` argument -is present, a line number is displayed before each line. +This command displays each line of the specified file. +Because you specified the `-n` option, +a line number is displayed before each line. ## Parsing command-line arguments @@ -171,7 +219,7 @@ Import the package's [args library]({{argsAPI}}/args-library.html) as follows: - + ```dart import 'package:args/args.dart'; ``` @@ -184,16 +232,15 @@ The `args` library contains these classes, among others: | [ArgResults]({{argsAPI}}/ArgResults-class.html) | The result of parsing command-line arguments using `ArgParser`. | {: .table } -Here is the `dcat` code that uses these classes to parse and store command-line -arguments: +The following code in the `dcat` app uses these classes to +parse and store the specified command-line arguments: - + {% prettify dart tag=pre+code %} void main([!List arguments!]) { - exitCode = 0; // presume success + exitCode = 0; // Presume success final [!parser = ArgParser()..addFlag(lineNumber, negatable: false, abbr: 'n');!] - [!ArgResults argResults = parser.parse(arguments);!] final paths = [!argResults.rest!]; @@ -201,14 +248,15 @@ void main([!List arguments!]) { } {% endprettify %} -The runtime passes command-line arguments to the app's `main()` function as a -list of strings. The `ArgParser` is configured to parse the `-n` flag. The -result of parsing command-line arguments is stored in `argResults`. +The Dart runtime passes command-line arguments to +the app's `main` function as a list of strings. +The `ArgParser` is configured to parse the `-n` option. +Then, the result of parsing command-line arguments is stored in `argResults`. The following diagram shows how the `dcat` command line used above is parsed into an `ArgResults` object. -![Run dcat from the command-line](images/dcat-dart-run.svg){:width="350"} +![Run dcat from the command-line](/assets/img/tutorials/server/dcat-dart-run.svg){:width="350"} You can access flags and options by name, treating an `ArgResults` like a `Map`. @@ -222,7 +270,7 @@ the `ArgParser` and `ArgResults` classes. Like other languages, Dart has standard output, standard error, and standard input streams. -The standard I/O streams are defined at the top level of the dart:io library: +The standard I/O streams are defined at the top level of the `dart:io` library: | Stream | Description | |---|---| @@ -231,23 +279,24 @@ The standard I/O streams are defined at the top level of the dart:io library: | [stdin]({{ioAPI}}/stdin.html) | The standard input | {: .table } -Import the dart:io library as follows: +Import the `dart:io` library as follows: - + ```dart import 'dart:io'; ``` {{site.alert.note}} - Web apps (apps that depend on dart:html) can't use the dart:io library. + Web apps (apps that depend on `dart:html`) can't use the `dart:io` library. {{site.alert.end}} ### stdout -Here's the code from the `dcat` program that writes the line number to -the `stdout` (if the `-n` flag is set) followed by the line from the file. +The following code from the `dcat` app +writes the line numbers to `stdout` (if the `-n` option is specified) +followed by the contents of the line from the file. - + {% prettify dart tag=pre+code %} if (showLineNumbers) { [!stdout.write('${lineNumber++} ');!] @@ -256,10 +305,10 @@ if (showLineNumbers) { {% endprettify %} The `write()` and `writeln()` methods take an object of any type, -convert it to a string, and print it. The `writeln()` method -also prints a newline character. -`dcat` uses the `write()` method to print the line number so the -line number and text appear on the same line. +convert it to a string, and print it. +The `writeln()` method also prints a newline character. +The `dcat` app uses the `write()` method to print the line number so +the line number and text appear on the same line. You can also use the `writeAll()` method to print a list of objects, or use `addStream()` to asynchronously print all the elements from a stream. @@ -267,7 +316,7 @@ or use `addStream()` to asynchronously print all the elements from a stream. `stdout` provides more functionality than the `print()` function. For example, you can display the contents of a stream with `stdout`. However, you must use `print()` instead of `stdout` -for programs that run on the web. +for apps that run on the web. ### stderr @@ -275,14 +324,17 @@ Use `stderr` to write error messages to the console. The standard error stream has the same methods as `stdout`, and you use it in the same way. Although both `stdout` and `stderr` print to the console, -their output is separate -and can be redirected or piped at the command line +their output is separate and +can be redirected or piped in the command line or programmatically to different destinations. This code from `dcat` prints an error message if the user tries to list a directory. - +The following code from the `dcat` app prints an error message if +the user tries to output the lines of a directory instead of a file. + + {% prettify dart tag=pre+code %} if (await FileSystemEntity.isDirectory(path)) { [!stderr.writeln('error: $path is a directory');!] @@ -300,7 +352,7 @@ and get input piped in from the standard output of another program. Here's a small program that reads a single line from `stdin`: - + ```dart import 'dart:io'; @@ -315,22 +367,20 @@ The `readLineSync()` method reads text from the standard input stream, blocking until the user types in text and presses return. This little program prints out the typed text. -In the `dcat` program, +In the `dcat` app, if the user does not provide a filename on the command line, -the program instead reads from stdin -using the `pipe()` method. +the program instead reads from stdin using the `pipe()` method. Because `pipe()` is asynchronous -(returning a future, even though this code doesn't use that return value), +(returning a `Future`, even though this code doesn't use that return value), the code that calls it uses `await`. - + {% prettify dart tag=pre+code %} - await stdin.[!pipe!](stdout); {% endprettify %} In this case, the user types in lines of text, -and the program copies them to stdout. +and the app copies them to stdout. The user signals the end of input by pressing Control+D (or Control+Z on Windows). @@ -342,23 +392,24 @@ The quick brown fox jumps over the lazy dog. ## Getting info about a file -The [FileSystemEntity]({{ioAPI}}/FileSystemEntity-class.html) -class in the dart:io library provides properties and static methods +The [`FileSystemEntity`]({{ioAPI}}/FileSystemEntity-class.html) +class in the `dart:io` library provides properties and static methods that help you inspect and manipulate the file system. -For example, if you have a path, -you can determine whether the path is a file, a directory, a link, or not found -by using the `type()` method from the `FileSystemEntity` class. +For example, if you have a path, you can +determine whether the path is a file, a directory, a link, or not found by +using the `type()` method from the `FileSystemEntity` class. Because the `type()` method accesses the file system, it performs the check asynchronously. -The following code from the `dcat` example uses `FileSystemEntity` +The following code from the `dcat` app uses `FileSystemEntity` to determine if the path provided on the command line is a directory. -The future returns a boolean that indicates if the path is a directory or not. -Because the check is asynchronous, the code calls `isDirectory()` -using `await`. +The returned `Future` completes with a boolean that +indicates if the path is a directory or not. +Because the check is asynchronous, the +code calls `isDirectory()` using `await`. - + {% prettify dart tag=pre+code %} if ([!await FileSystemEntity.isDirectory(path)!]) { stderr.writeln('error: $path is a directory'); @@ -368,20 +419,21 @@ if ([!await FileSystemEntity.isDirectory(path)!]) { {% endprettify %} Other interesting methods in the `FileSystemEntity` class -include `isFile()`, `exists()`, `stat()`, `delete()`, -and `rename()`, all of which also use a future to return a value. +include `isFile()`, `exists()`, `stat()`, `delete()`, and `rename()`, +all of which also use a `Future` to return a value. -`FileSystemEntity` is the superclass for the `File`, `Directory`, and `Link` classes. +`FileSystemEntity` is the superclass for the +`File`, `Directory`, and `Link` classes. ## Reading a file -`dcat` opens each file listed on the command line -with the `openRead()` method, which returns a stream. -The `await for` block waits for the file to be read -asynchronously. The data prints to stdout when it -becomes available on the stream. +The `dcat` apps opens each file listed on the command line +with the `openRead()` method, which returns a `Stream`. +The `await for` block waits for the file to be read and decoded asynchronously. +When the data becomes available on the stream, +the app prints it to stdout. - + {% prettify dart tag=pre+code %} for (final path in paths) { var lineNumber = 1; @@ -401,12 +453,12 @@ for (final path in paths) { } {% endprettify %} -The following shows the rest of the code, which uses two decoders that +The following highlights the rest of the code, which uses two decoders that transform the data before making it available in the `await for` block. The UTF8 decoder converts the data into Dart strings. `LineSplitter` splits the data at newlines. - + {% prettify dart tag=pre+code %} for (final path in paths) { var lineNumber = 1; @@ -426,22 +478,22 @@ for (final path in paths) { } {% endprettify %} -The dart:convert library contains these and other data converters, +The `dart:convert` library provides these and other data converters, including one for JSON. -To use these converters you need to import the dart:convert library: +To use these converters you need to import the `dart:convert` library: - + ```dart import 'dart:convert'; ``` -## Writing a file +## Writing to a file The easiest way to write text to a file is to create a -[File]({{ioAPI}}/File-class.html) +[`File`]({{ioAPI}}/File-class.html) object and use the `writeAsString()` method: - + ```dart final quotes = File('quotes.txt'); const stronger = 'That which does not kill us makes us stronger. -Nietzsche'; @@ -452,17 +504,19 @@ await quotes.writeAsString(stronger, mode: FileMode.append); The `writeAsString()` method writes the data asynchronously. It opens the file before writing and closes the file when done. To append data to an existing file, you can use the optional -parameter `mode` and set its value to `FileMode.append`. -Otherwise, the mode is `FileMode.write` and the previous contents of the file, -if any, are overwritten. +named parameter `mode` and set its value to `FileMode.append`. +Otherwise, the mode defaults to `FileMode.write` and +the previous contents of the file, if any, are overwritten. If you want to write more data, you can open the file for writing. -The `openWrite()` method returns an IOSink (the same type as stdin and stderr). -You can continue to write to the file until done, -at which time, you must close the file. -The `close()` method is asynchronous and returns a future. - - +The `openWrite()` method returns an `IOSink`, +which has the same type as stdin and stderr. +When using the `IOSink` returned from `openWrite()`, +you can continue to write to the file until done, +at which time, you must manually close the file. +The `close()` method is asynchronous and returns a `Future`. + + ```dart final quotes = File('quotes.txt').openWrite(mode: FileMode.append); @@ -475,15 +529,16 @@ await quotes.close(); {% assign PlatformAPI = ioAPI | append: '/Platform' -%} -Use the [Platform]({{PlatformAPI}}-class.html) class -to get information about the machine and OS that the program is running on. +Use the [`Platform`]({{PlatformAPI}}-class.html) class +to get information about the machine and operating system +that your app is running on. -[Platform.environment]({{PlatformAPI}}/environment.html) -provides a copy of the environment -variables in an immutable map. If you need a mutable map (modifiable copy) you +The static [`Platform.environment`]({{PlatformAPI}}/environment.html) property +provides a copy of the environment variables in an immutable map. +If you need a mutable map (modifiable copy) you can use `Map.of(Platform.environment)`. - + ```dart final envVarMap = Platform.environment; @@ -494,27 +549,27 @@ print('PATH = ${envVarMap['PATH']}'); `Platform` provides other useful properties that give information about the machine, OS, and currently -running program. For example: +running app. For example: -- [Platform.isMacOS()]({{PlatformAPI}}/isMacOS.html) -- [Platform.numberOfProcessors]({{PlatformAPI}}/numberOfProcessors.html) -- [Platform.script]({{PlatformAPI}}/script.html) +- [`Platform.isMacOS()`]({{PlatformAPI}}/isMacOS.html) +- [`Platform.numberOfProcessors`]({{PlatformAPI}}/numberOfProcessors.html) +- [`Platform.script`]({{PlatformAPI}}/script.html) ## Setting exit codes -The dart:io library defines a top-level property, +The `dart:io` library defines a top-level property, `exitCode`, that you can change to set the exit code for the current invocation of the Dart VM. An exit code is a number passed from -the Dart program to the parent process -to indicate the success, failure, or other state of the -execution of the program. +a Dart app to the parent process +to indicate the success, failure, or other state of +the execution of the app. -The `dcat` program sets the exit code +The `dcat` app sets the exit code in the `_handleError()` function to indicate that an error occurred during execution. - + {% prettify dart tag=pre+code %} Future _handleError(String path) async { if (await FileSystemEntity.isDirectory(path)) { @@ -525,63 +580,65 @@ Future _handleError(String path) async { } {% endprettify %} -An exit code of 2 indicates that the program encountered an error. +An exit code of `2` indicates that the app encountered an error. An alternative to using `exitCode` is to use the top-level `exit()` function, -which sets the exit code and quits the program immediately. +which sets the exit code and exits the app immediately. For example, the `_handleError()` function could call `exit(2)` instead of setting `exitCode` to 2, -but `exit()` would quit the program -and it might not process all of the files on the command line. +but `exit()` would quit the program and +it might not process all of the files specified by the running command. {{site.alert.info}} Generally speaking, you're better off using the `exitCode` property, - which sets the exit code but allows the program to continue through to its - natural completion. + which sets the exit code but allows the program to continue through to + its natural completion. {{site.alert.end}} Although you can use any number for an exit code, by convention, the codes in the table below have the following meanings: -| Code | Meaning | -|---|---| -| 0 | Success | -| 1 | Warnings | -| 2 | Errors | +| Code | Meaning | +|------|----------| +| 0 | Success | +| 1 | Warnings | +| 2 | Errors | {: .table } ## Summary -This tutorial described some basic API found in these classes from the dart:io library: +This tutorial described some basic APIs +found in the following classes from the `dart:io` library: | API | Description | |---|---| -| [IOSink]({{ioAPI}}/IOSink-class.html) | Helper class for objects that consume data from streams | -| [File]({{ioAPI}}/File-class.html) | Represents a file on the native file system | -| [Directory]({{ioAPI}}/Directory-class.html) | Represents a directory on the native file system | -| [FileSystemEntity]({{ioAPI}}/FileSystemEntity-class.html) | Superclass for File and Directory | -| [Platform]({{ioAPI}}/Platform-class.html) | Provides information about the machine and operating system | -| [stdout]({{ioAPI}}/stdout.html) | The standard output stream | -| [stderr]({{ioAPI}}/stderr.html) | The standard error stream | -| [stdin]({{ioAPI}}/stdin.html) | The standard input stream | -| [exitCode]({{ioAPI}}/exitCode.html) | Access and set the exit code | -| [exit()]({{ioAPI}}/exit.html) | Sets the exit code and quits | +| [`IOSink`]({{ioAPI}}/IOSink-class.html) | Helper class for objects that consume data from streams | +| [`File`]({{ioAPI}}/File-class.html) | Represents a file on the native file system | +| [`Directory`]({{ioAPI}}/Directory-class.html) | Represents a directory on the native file system | +| [`FileSystemEntity`]({{ioAPI}}/FileSystemEntity-class.html) | Superclass for File and Directory | +| [`Platform`]({{ioAPI}}/Platform-class.html) | Provides information about the machine and operating system | +| [`stdout`]({{ioAPI}}/stdout.html) | The standard output stream | +| [`stderr`]({{ioAPI}}/stderr.html) | The standard error stream | +| [`stdin`]({{ioAPI}}/stdin.html) | The standard input stream | +| [`exitCode`]({{ioAPI}}/exitCode.html) | Access and set the exit code | +| [`exit()`]({{ioAPI}}/exit.html) | Sets the exit code and quits | {: .table } -In addition, this tutorial covers two classes that help with command-line arguments: -[ArgParser]({{argsAPI}}/ArgParser-class.html) and -[ArgResults.]({{argsAPI}}/ArgResults-class.html) +In addition, this tutorial covered two classes from `package:args` +that help with parsing and using command-line arguments: +[`ArgParser`]({{argsAPI}}/ArgParser-class.html) and +[`ArgResults`]({{argsAPI}}/ArgResults-class.html). For more classes, functions, and properties, -consult to the API reference for -[dart:io,]({{ioAPI}}/dart-io-library.html) -[dart:convert,]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-convert/dart-convert-library.html) -and the [args]({{argsAPI}}/args-library.html) package. +consult the API docs for +[`dart:io`]({{ioAPI}}/dart-io-library.html), +[`dart:convert`]({{site.dart-api}}/{{site.data.pkg-vers.SDK.channel}}/dart-convert/dart-convert-library.html), +and [`package:args`]({{argsAPI}}/args-library.html). For another example of a command line app, -see the [command_line][] sample. +check out the [`command_line`][] sample. -[command_line]: https://github.com/dart-lang/samples/tree/main/command_line +[`command_line`]: https://github.com/dart-lang/samples/tree/main/command_line ## What next? diff --git a/src/_tutorials/server/fetch-data.md b/src/tutorials/server/fetch-data.md similarity index 99% rename from src/_tutorials/server/fetch-data.md rename to src/tutorials/server/fetch-data.md index ff135730e..386aead3c 100644 --- a/src/_tutorials/server/fetch-data.md +++ b/src/tutorials/server/fetch-data.md @@ -2,6 +2,12 @@ title: Fetch data from the internet description: Fetch data over the internet using the http package. js: [{url: 'https://dartpad.dev/inject_embed.dart.js', defer: true}] +prevpage: + url: /tutorials/server/cmdline + title: Write command-line apps +nextpage: + url: /tutorials/server/httpserver + title: Write HTTP servers --- diff --git a/src/_tutorials/server/get-started.md b/src/tutorials/server/get-started.md similarity index 97% rename from src/_tutorials/server/get-started.md rename to src/tutorials/server/get-started.md index fd66cd6f8..eb43070a8 100644 --- a/src/_tutorials/server/get-started.md +++ b/src/tutorials/server/get-started.md @@ -3,20 +3,20 @@ title: "Get started: Command-line and server apps" title: 起步教程：编写命令行和服务端应用 description: Get Dart, run and compile a small app description: 获取 Dart SDK，运行和编译一个小应用 -nextpage: - url: /tutorials/server/cmdline - title: Write command-line apps - title: 编写命令行应用 +js: [{url: 'https://dartpad.cn/inject_embed.dart.js', defer: true}] prevpage: url: /tutorials/server title: Dart command-line and server tutorials title: 教程目录：使用 Dart 编写命令行和服务端应用 -js: [{url: 'https://dartpad.cn/inject_embed.dart.js', defer: true}] +nextpage: + url: /tutorials/server/cmdline + title: Write command-line apps + title: 编写命令行应用 --- Follow these steps to start using the Dart SDK to develop command-line and server apps. -First you’ll play with the Dart language in your browser, no download required. -Then you’ll install the Dart SDK, write a small program, and run that program using the Dart VM. +First you'll play with the Dart language in your browser, no download required. +Then you'll install the Dart SDK, write a small program, and run that program using the Dart VM. Finally, you'll use an AOT (_ahead of time_) compiler to compile your finished program to native machine code, which you'll execute using the Dart runtime. diff --git a/src/_tutorials/server/httpserver.md b/src/tutorials/server/httpserver.md similarity index 92% rename from src/_tutorials/server/httpserver.md rename to src/tutorials/server/httpserver.md index 3a64d7c02..aac963939 100644 --- a/src/_tutorials/server/httpserver.md +++ b/src/tutorials/server/httpserver.md @@ -5,9 +5,9 @@ description: Communicate over the internet description: 通过网络进行通讯 toc: false prevpage: - url: /tutorials/server/cmdline - title: "Write command-line apps" - title: "编写命令行应用" + url: /tutorials/server/fetch-data + title: Fetch data from the internet + title: 从互联网获取数据 --- diff --git a/src/_tutorials/server/index.md b/src/tutorials/server/index.md similarity index 100% rename from src/_tutorials/server/index.md rename to src/tutorials/server/index.md diff --git a/src/_tutorials/web/get-started.md b/src/tutorials/web/get-started.md similarity index 95% rename from src/_tutorials/web/get-started.md rename to src/tutorials/web/get-started.md index d51f96af1..3dc8c1662 100644 --- a/src/_tutorials/web/get-started.md +++ b/src/tutorials/web/get-started.md @@ -121,7 +121,7 @@ More information: ## 3. 获取 CLI 工具或者 IDE（或两者都有） terminal -If you like to use the command line, install [webdev][]: +If you like to use the command line, install the [`webdev`][] package: 如果你想使用命令行，请安装 [webdev][]： @@ -163,7 +163,8 @@ create a project using the template named **Bare-bones Web App**. ## 5. 运行应用 terminal -To run the app from the command line, use [webdev][] to build and serve the app: +To run the app from the command line, +use [`webdev`][] to build and serve the app: 要从命令行运行应用程序，可以使用 [webdev][] 构建和运行应用程序： @@ -179,16 +180,17 @@ Or run the app from your IDE. To view your app, use the Chrome browser to visit the app's URL—for example, -[localhost:8080](localhost:8080). +[localhost:8080](http://localhost:8080). 使用 Chrome 浏览器访问应用程序的 URL 即可查看你的应用程序。 比如，[localhost:8080](localhost:8080)。 Whether you use an IDE or the command line, -[webdev serve][] builds and serves your app -using the Dart development compiler, [dartdevc][]. -Startup is slowest the first time dartdevc builds and serves your app. +[`webdev serve`][] builds and serves your app +using the development JavaScript compiler. +Startup is slowest the first time the +development compiler builds and serves your app. After that, assets are cached on disk and incremental builds are much faster. 无论使用 IDE 还是命令行， @@ -333,7 +335,6 @@ If you get stuck, find help at [Community and support.](/community) 如果你在这一步无法继续进行，可以从 [社区和帮助](/community) 中查找帮助。 -[dartdevc]: /tools/dartdevc [DartPad documentation]: /tools/dartpad [Dart language tour]: /language [Dart library tour]: /guides/libraries/library-tour @@ -342,5 +343,5 @@ If you get stuck, find help at [Community and support.](/community) [low-level HTML tutorial for Dart]: /tutorials/web/low-level-html [overview of editors & debuggers]: /tools#ides-and-editors [Tutorial introduction to using Dart for basic web programming]: /tutorials/web/low-level-html/connect-dart-html -[webdev]: /tools/webdev -[webdev serve]: /tools/webdev#serve +[`webdev`]: /tools/webdev +[`webdev serve`]: /tools/webdev#serve diff --git a/src/_tutorials/web/index.md b/src/tutorials/web/index.md similarity index 100% rename from src/_tutorials/web/index.md rename to src/tutorials/web/index.md diff --git a/src/_tutorials/web/low-level-html/add-elements.md b/src/tutorials/web/low-level-html/add-elements.md similarity index 94% rename from src/_tutorials/web/low-level-html/add-elements.md rename to src/tutorials/web/low-level-html/add-elements.md index 34cc7debd..9b8ef41b6 100644 --- a/src/_tutorials/web/low-level-html/add-elements.md +++ b/src/tutorials/web/low-level-html/add-elements.md @@ -163,7 +163,7 @@ DOM through the `Element` class. An `Element` object has a parent `Element` and maintains references to its children elements in a list. -An element with multiple child elements and a parent element An `Element` object has at most one parent `Element`. @@ -173,7 +173,7 @@ Get an `Element`'s parent with the getter `parent`. For example, if you have an `Element` with the name `anElement` you would refer to its parent element with `anElement.parent`. -Dart code reference to anElement's parent An `Element` object maintains references to its child elements in a list. @@ -200,13 +200,13 @@ The `List` class has various methods and operators whereby you can refer to each child element individually, iterate over the list, and add and remove elements. -Dart code references to anElement's list of children and individual child Elements You can change the tree structure by adding children to and removing children from an element's list of children. -Add a child element When you change an `Element` or its child elements in your Dart program, @@ -226,12 +226,12 @@ You could get the same results using Dart code, but it's usually better to define the primary page elements in HTML code (easier to read, quicker to load). -todo app and its corresponding HTML code The following diagram shows a partial DOM tree for the todo app. -The todo app and part of its DOM tree Of interest are the two-page elements that have IDs: @@ -247,7 +247,7 @@ whenever the user enters text into the input element. The following diagram shows the Dart code for the todo app. -todo app and its corresponding Dart code The top-level variables are initialized using @@ -285,14 +285,14 @@ The todo app defines a function, `addToDoItem()`, that can handle these change events. The following code connects `addToDoItem()` to the input field: -Add an event handler to the toDoInput element Rather than dissect this busy line of code, think of it as a Dart idiom for adding an event handler to an `Element` object. -Dart idiom: Add an event handler to an Element A change event is just one of many types of events @@ -333,7 +333,7 @@ The `addToDoItem()` function ignores the Event object passed to it. The change event handler has the following code: -The addToDoItem() function explained The final line of code is where the DOM gets changed. @@ -350,7 +350,7 @@ in the to do list. Let's take a look at the CSS file for this app. -The effect of CSS styles This code uses three different kinds of CSS selectors. @@ -495,7 +495,7 @@ The program adds each button to a DOM element—a simple `
          ` element identified by the CSS selector `letterpile`—with a call to `letterpile.children.add()`. -Dart code populates the letter pile with buttons Each button element in the letter pile @@ -512,7 +512,7 @@ Because an element can have only one parent, adding the button to a different parent automatically removes it from its previous parent. -The mouse click handler adds the button to the word, thus moving it The `+=` operator is a compound assignment operator, diff --git a/src/_tutorials/web/low-level-html/connect-dart-html.md b/src/tutorials/web/low-level-html/connect-dart-html.md similarity index 97% rename from src/_tutorials/web/low-level-html/connect-dart-html.md rename to src/tutorials/web/low-level-html/connect-dart-html.md index 69e041c13..70b1d2178 100644 --- a/src/_tutorials/web/low-level-html/connect-dart-html.md +++ b/src/tutorials/web/low-level-html/connect-dart-html.md @@ -98,7 +98,7 @@ and displays the document in a window. The following diagram shows a simple HTML file and the resulting web browser page in Chrome. -A simple HTML file and its resulting web page HTML uses tags to describe the document. @@ -120,7 +120,7 @@ For example, the tree has page elements, text nodes, and attribute nodes. Here is the DOM tree for the simple HTML file above. -A Dart dynamically changing the DOM Notice that some tags, such as the `

          ` paragraph tag, @@ -139,7 +139,7 @@ by adding, deleting, and modifying the nodes in the DOM tree. When the DOM is changed, the browser immediately re-renders the window. -A Dart program can dynamically change the DOM The diagram shows a small Dart program that makes @@ -340,7 +340,7 @@ the node containing the string "RipVanWinkle paragraph." is a text node. -DOM tree for a paragraph element More complex text, @@ -390,7 +390,7 @@ In DartPad, the only visible connection between the Dart code and the HTML code is the `RipVanWinkle` ID. -The RipVanWinkle ID is used by both Dart and HTML To run your app outside DartPad, @@ -499,7 +499,7 @@ Let's look at the CSS code for the mini app. The CSS file for the mini app has one CSS rule in it. A CSS rule has two main parts: a selector and a set of declarations. -The parts of a CSS rule In the mini app, the selector `#RipVanWinkle` is an ID selector, @@ -521,7 +521,7 @@ for all matching elements. The style sheet is used to set the appearance of the matching element(s) on the web page. -A declaration specifies an attribute and its value The CSS rule for the `RipVanWinkle` paragraph diff --git a/src/_tutorials/web/low-level-html/index.md b/src/tutorials/web/low-level-html/index.md similarity index 100% rename from src/_tutorials/web/low-level-html/index.md rename to src/tutorials/web/low-level-html/index.md diff --git a/src/_tutorials/web/low-level-html/remove-elements.md b/src/tutorials/web/low-level-html/remove-elements.md similarity index 94% rename from src/_tutorials/web/low-level-html/remove-elements.md rename to src/tutorials/web/low-level-html/remove-elements.md index efd8da5c4..b3716ada6 100644 --- a/src/_tutorials/web/low-level-html/remove-elements.md +++ b/src/tutorials/web/low-level-html/remove-elements.md @@ -176,7 +176,7 @@ using the element's `remove()` function is shorter and more concise than using functions from the `List` class. -Use element.remove() to remove an element from the DOM In the app, @@ -188,7 +188,7 @@ When the user clicks that new element, its event handler causes the element to remove itself from the DOM with `remove()`. -Registering an event handler to delete an item When the element removes itself from the DOM, @@ -200,7 +200,7 @@ and the item disappears from the to do list. When the user clicks the **Delete All** button, all elements are removed from the list. -Use element.children.clear() to remove all of an element's children In this case, using the `List` class's `clear()` function @@ -221,7 +221,7 @@ that implements the **Delete All** button. the handler removes all of the child elements from the to do list. Here is all the Dart code related to the **Delete All** button. - Remove all child elements from an Element ## About function expressions and => @@ -237,7 +237,7 @@ For more details, see the language tour's coverage of [functions](/language/functions). -A one-line function definition It is equivalent to writing this: diff --git a/src/web/deployment.md b/src/web/deployment.md index 61cd22830..648806a05 100644 --- a/src/web/deployment.md +++ b/src/web/deployment.md @@ -38,7 +38,6 @@ reliable and responsive. * [Follow best practices for web apps](#follow-best-practices-for-web-apps) * [Remove unneeded build files](#remove-unneeded-build-files) - #### Use the pwa package to make your app work offline The [pwa package]({{site.pub-pkg}}/pwa) simplifies the task of @@ -46,7 +45,6 @@ making your app work with limited or no connectivity. To learn more about using this package, see [Making a Dart web app offline-capable: 3 lines of code.](https://medium.com/dartlang/making-a-dart-web-app-offline-capable-3-lines-of-code-e980010a7815) - #### Use deferred loading to reduce your app's initial size You can use Dart's support for deferred loading to @@ -54,7 +52,6 @@ reduce your app's initial download size. For details, see the language tour's coverage of [deferred loading](/language/libraries#lazily-loading-a-library). - #### Follow best practices for web apps The usual advice for web apps applies to Dart web apps. @@ -66,7 +63,6 @@ Here are a few resources: * [Progressive Web Apps](https://web.dev/progressive-web-apps/) * [Lighthouse](https://developers.google.com/web/tools/lighthouse/) - #### Remove unneeded build files Web compilers can produce files that are useful during development, @@ -78,9 +74,9 @@ To remove these files, you can run a command like the following: Revise the following once https://github.com/dart-lang/angular/issues/1123 is resolved: {% endcomment %} -```bash +```terminal # From the root directory of your app: -find build -type f -name "*.js.map" -exec rm {} + +$ find build -type f -name "*.js.map" -exec rm {} + ``` ## Serving your app @@ -103,7 +99,6 @@ Its files are in the **gh-pages** branch of the [filiph/startup_namer repo](https://github.com/filiph/startup_namer) and were built using [peanut.][peanut] - ### Firebase {% comment %} TODO: Give an example of how to deploy with Firebase, which originally was shown on https://dart.academy/build-a-real-time-chat-web-app-with-dart-angular-2-and-firebase-3/ diff --git a/src/web/js-interop.md b/src/web/js-interop.md index 53c2430ef..913d716d1 100644 --- a/src/web/js-interop.md +++ b/src/web/js-interop.md @@ -43,7 +43,7 @@ For a glimpse into the next generation of JS interop, you can refactor your code to conform to the new syntax and semantics now. Doing so will likely not prevent the need to refactor again -once [Dart 3][] lands, as the features are still in development. +once these features stabilize, as the features are still in development. However, the features available for preview are much closer to future JS interop than any pattern supported today. So, there are a few reasons to try them out now: diff --git a/tool/check-dart-sdk.sh b/tool/check-dart-sdk.sh new file mode 100644 index 000000000..6349fd948 --- /dev/null +++ b/tool/check-dart-sdk.sh @@ -0,0 +1,91 @@ +#!/usr/bin/env bash +# Use this file locally to update Dart SDK checksum values in the Dockerfile +# Prints output similar to cases in Dockerfile for easy composition +# when having to update checksum values for updates dart SDK. +set -eu -o pipefail +TOOL_DIR="${TOOL_DIR:=$(dirname "$0")}" +source $TOOL_DIR/utils.sh + +VERSION="latest" +CHANNEL="stable" + +while (( "$#" )); do + case "$1" in + --version) + VERSION=$2 + shift 2 + ;; + --channel) + CHANNEL=$2 + shift 2 + ;; + *) + echo "Unsupported argument $1" >&2 + exit 1 + ;; + esac +done + +echo -e "\nPulling latest Dart SHA hashes.\n\nThis will take a moment.\n" + +BASEURL="https://storage.googleapis.com/dart-archive/channels" +CHANNELS="stable beta dev" +ARCHS="amd64 arm64" +ENDING='\\\n' +FILE=$TOOL_DIR/new-dart-hashes.txt + +true > $FILE + +for CHANNEL in $CHANNELS; do + for ARCH in $ARCHS; do + printf " ${ARCH}_${CHANNEL}) $ENDING" >> $FILE + _arch=$ARCH + if [[ "$_arch" == "amd64" ]]; then + _arch='x64' + fi + _filename="dartsdk-linux-${_arch}-release.zip" + _url="$BASEURL/$CHANNEL/release/$VERSION/sdk/$_filename" + curl -fsSLO $_url + _checksum=$(shasum -a 256 $_filename) + read -a _fname_arr <<< "${_checksum}" # Read in string output as array + _checkonly="${_fname_arr%:*}" # Remove filename portion of checksum output + printf " DART_SHA256=\"$_fname_arr\"; $ENDING" >> $FILE + printf " SDK_ARCH=\"$_arch\";; $ENDING" >> $FILE + echo "Pulled ${ARCH}_${CHANNEL}: $_fname_arr" + rm $_filename + done +done + +echo -e "\n\nPulled latest Dart SHA hashes and saved to $FILE.\n" + +lead='# BEGIN dart-sha$' +tail='# END dart-sha$' +new_file='tool/new-dart-hashes.txt' +existing_file='Dockerfile' + +new_hash=$(sed -n -e '/DART_SHA/ p' -e '/DART_SHA/ q' $new_file) +old_hash=$(sed -n -e '/DART_SHA/ p' -e '/DART_SHA/ q' $existing_file) + +echo -e "Old $old_hash" +echo -e "New $new_hash" + +# Compare the SHA hashes. +if [[ "$new_hash" == "$old_hash" ]]; then + echo -e "Current SHA hashes are the latest hashes.\n" + echo -e "No update needed.\n" + rm $new_file + echo -e "Removed $new_file.\n" + echo -e "Re-run check-dart-sdk.sh to pull the current SHA hashes.\n" +else + if [[ -f "$new_file" ]]; then + echo -e "Retrieved replacement hashes and saved to $new_file.\n" + if [[ -f "$existing_file" ]]; then + echo -e "Found Dockerfile at $existing_file.\n" + echo -e "Run tool/update-dart-sums.sh." + else + echo -e "No Dockerfile found." + fi + else + echo -e "No replacement hashes found at this time.\n" + fi +fi diff --git a/tool/check-links.sh b/tool/check-links.sh index ec31432b1..d4e91671d 100755 --- a/tool/check-links.sh +++ b/tool/check-links.sh @@ -7,7 +7,7 @@ dart pub get echo "Checking for valid link references..." # Check for invalid link references before checking for links -dart run tool/check_link_references.dart +dart run tool/dart_tools/bin/check_link_references.dart echo $'No invalid link references found!\n' trap clean_up SIGINT SIGTERM ERR EXIT diff --git a/tool/create_code_with_tooltips.dart b/tool/create_code_with_tooltips.dart deleted file mode 100644 index 59bb05ade..000000000 --- a/tool/create_code_with_tooltips.dart +++ /dev/null @@ -1,242 +0,0 @@ -import 'dart:io'; -import 'dart:convert' show HtmlEscape, HtmlEscapeMode; -import 'package:logging/logging.dart'; - -final Logger _log = Logger(''); -const repoBase = '..'; - -final warning = '''{%- comment %} -WARNING: Do NOT EDIT this file directly. It is autogenerated by - ${Platform.script.path.replaceFirst(RegExp(r'^.*site-www/'), '')} -from sources in the example folder. -{% endcomment -%} -'''; - -const sources = [ - // Entry format: [ src_path, tip_data_path, target_HTML_file_path ] - _SrcAndTipPaths( - '$repoBase/examples/misc/bin/dcat/dcat.dart', - '$repoBase/examples/misc/bin/dcat/dcat_tooltips.html', - '$repoBase/src/_tutorials/server/_dcat-example.html', - ), -]; - -void main() { - Logger.root.level = Level.OFF; - Logger.root.onRecord.listen((LogRecord rec) => print('>> ${rec.message}')); - - sources.forEach(_processSrc); -} - -void _processSrc(_SrcAndTipPaths paths) { - _log.info('Processing $paths'); - - final srcAsHtmlWithTips = - _SrcWithTips(paths.srcPath, paths.toolTipDataPath).srcHtmlWithTips(); - final html = [ - warning, - '

          \n',
-    '',
-    srcAsHtmlWithTips.join('\n'),
-    '\n'
-        '
          \n', - ].join(''); - File(paths.htmlPath).writeAsStringSync(html); -} - -class _SrcWithTips { - final HtmlEscape _htmlEscape = HtmlEscape(HtmlEscapeMode(escapeLtGt: true)); - final tipRegExp = RegExp(r'^(.*?) ?//!tip\("([^"]+)"\)$'); - final isNotBlankRegExp = RegExp(r'\S'); - final List> tooltips; - - /// Path to source code with tool tip markers - final String srcPath; - - /// Source line number (starting at 1 not 0) as lines are being processed. - int lineNum = 1; - - /// Path to file containing tool tip data - final String toolTipDataPath; - - int indexOfNextTooltip = 0; - - _SrcWithTips(this.srcPath, this.toolTipDataPath) - : tooltips = _tooltips(toolTipDataPath).toList(); - - // Side-effect: updates lineNum - List srcHtmlWithTips() { - final result = []; - final srcLines = srcLinesWithoutInitialCommentBlock(); - final tooltipAnchors = []; - - for (int i = 0; i < srcLines.length; i++, lineNum++) { - final line = srcLines[i]; - if (line.contains('//!web-only') || - line.contains('#docregion') || - line.contains('#enddocregion')) { - _log.info('Src skip web-only: $lineNum: $line'); - continue; - } - var lineWithoutTipInstructions = - extractTooltipAnchors(lineNum, line, tooltipAnchors); - if (isNotBlankRegExp.hasMatch(lineWithoutTipInstructions)) { - final lineWithMarkup = processTipInstruction( - tooltipAnchors, lineNum, lineWithoutTipInstructions); - result.add(lineWithMarkup); - tooltipAnchors.clear(); - _log.info('Src added markup #$lineNum: $line ($lineWithMarkup)'); - } else if (tooltipAnchors.isEmpty) { - // This is a blank line - result.add(line); - _log.info('Src blank line #$lineNum: $line'); - } else { - // [line] only contains tooltip instructions. Don't add it to [result]. - // The accumulated [tooltipAnchors] apply to the next line. Fall - // through. - _log.info('Src extracted tips #$lineNum: $line'); - } - // lineNum++; - } - return result; - } - - /// Return a version of [line] with each [tooltipAnchors] replaced - /// by a popover HTML anchor element. - /// - /// [tooltipAnchors] are (unescaped) tooltip anchor text strings. - /// [line] is an unescaped source line without tooltip instructions. - /// - /// Side-effect: increments [indexOfNextTooltip] as it processes tips. - String processTipInstruction( - List tooltipAnchors, int lineNum, String line /*src line*/) { - _log.fine(line); - line = htmlEscape(line); - - for (var anchorText in tooltipAnchors) { - final escapedAnchorText = htmlEscape(anchorText); - if (!line.contains(escapedAnchorText)) { - throw "Error: $srcPath:$lineNum doesn't contain " - "the tip anchor text '$anchorText': '$line'"; - } - - final tooltip = tooltips[indexOfNextTooltip]; - final tooltipAnchor = tooltip[0]; - final tooltipTitle = tooltip[1]; - final tooltipText = tooltip[2]; - - indexOfNextTooltip++; - if (tooltipAnchor != anchorText) { - throw "Error in tooltip data entry order: " - "expected tip for '$anchorText', but instead found tip for '$tooltipAnchor'. Aborting."; - } - - _log.fine(' ** Replacing "$escapedAnchorText" with tooltip'); - final anchorWithTip = - '$escapedAnchorText'; - line = line.replaceFirst(escapedAnchorText, anchorWithTip); - } - return line; - } - - /// Extracts from [line] the anchor text from tooltips in that line, and adds - /// the text to [tooltipAnchors] as (unescaped) text. Returns the portion of - /// the line without the tip instructions - String extractTooltipAnchors( - int lineNum, String line, List tooltipAnchors) { - while (line.contains('//!tip(')) { - final match = tipRegExp.firstMatch(line); - if (match == null) return line; - final lineWithoutTipInstruction = match[1]; - final tooltipAnchorText = match[2]; - - if (tooltipAnchorText != null) { - tooltipAnchors.add(tooltipAnchorText); - } - - line = lineWithoutTipInstruction ?? ''; - } - return line; - } - - // Side-effect: updates lineNum - List srcLinesWithoutInitialCommentBlock() { - final lines = File(srcPath).readAsLinesSync(); - while (!lines.first.startsWith('import')) { - // Skip initial comment block - _log.info('Src skip init comment: $lineNum: ${lines.first}'); - lineNum++; - lines.removeAt(0); - } - - return lines - // pi_monte_carlo.dart specific adjustment - .map((line) => line.replaceFirst('numIterations', '500')) - .toList(); - } - - String htmlEscape(String s) => _htmlEscape.convert(s); -} - -Iterable> _tooltips(String toolTipDataPath) sync* { - final _tooltipLineRE = - RegExp(r'^\s*
        • (.*?)(
          • )?$'); - final _tooltipLineEndRE = RegExp(r'^\s*(.*?)()?$'); - final lines = File(toolTipDataPath).readAsLinesSync().iterator; - _log.info('Reading tool tips $toolTipDataPath:'); - - while (lines.moveNext()) { - final line = lines.current; - final match = _tooltipLineRE.firstMatch(line); - _log.info(' ${match == null ? "Skipping" : "Processing"}: $line.'); - if (match == null) continue; - - final name = match[1] ?? ''; - final optionalTitle = match[3] ?? ''; - var tooltip = match[4] ?? ''; - var liClosingTag = match[5]; - _log.fine(' >> $name | $optionalTitle | $tooltip | $liClosingTag'); - - while (liClosingTag == null && lines.moveNext()) { - final line = lines.current; - final match = _tooltipLineEndRE.firstMatch(line); - if (match == null) { - _log.info('Skipping data: $line'); - } else { - _log.info('Processing data: $line'); - tooltip = _join(tooltip, match[1] ?? ''); - liClosingTag = match[2]; - } - } - - if (liClosingTag == null) { - throw 'Could not find closing
        • tag for line starting at "$tooltip"'; - } - - yield [name, optionalTitle, tooltip]; - } -} - -/// Return the concatenation of s1 and s2, separated by a space if both are -/// nonempty. -String _join(String s1, String s2) => s1.isEmpty - ? s2 - : s2.isEmpty - ? s1 - : '$s1 $s2'; - -class _SrcAndTipPaths { - final String srcPath; - final String toolTipDataPath; - - /// Path to src as HTML marked up with tool tips - final String htmlPath; - - const _SrcAndTipPaths(this.srcPath, this.toolTipDataPath, this.htmlPath); - - @override - String toString() => - 'src: "$srcPath", tool tips: "$toolTipDataPath", HTML: "$htmlPath"'; -} diff --git a/tool/dart_tools/analysis_options.yaml b/tool/dart_tools/analysis_options.yaml index 5a6734098..b9bdf805a 100644 --- a/tool/dart_tools/analysis_options.yaml +++ b/tool/dart_tools/analysis_options.yaml @@ -1,27 +1 @@ -include: package:lints/recommended.yaml - -analyzer: - language: - strict-casts: true - strict-inference: true - strict-raw-types: true - -linter: - rules: - - always_declare_return_types - - cancel_subscriptions - - close_sinks - - comment_references - - one_member_abstracts - - only_throw_errors - - package_api_docs - - prefer_expression_function_bodies - - prefer_single_quotes - - sort_child_properties_last - - sort_unnamed_constructors_first - - test_types_in_equals - - throw_in_finally - - type_annotate_public_apis - - unawaited_futures - - use_enums - - use_super_parameters +include: package:analysis_defaults/analysis.yaml diff --git a/tool/check_link_references.dart b/tool/dart_tools/bin/check_link_references.dart similarity index 100% rename from tool/check_link_references.dart rename to tool/dart_tools/bin/check_link_references.dart diff --git a/tool/dart_tools/pubspec.yaml b/tool/dart_tools/pubspec.yaml index 6bb671f9d..dfdda98bb 100644 --- a/tool/dart_tools/pubspec.yaml +++ b/tool/dart_tools/pubspec.yaml @@ -1,11 +1,14 @@ name: dart_tools -description: Dart-based tools for site-www +description: Dart-based tools for site-www. +publish_to: none environment: - sdk: ^2.19.4 + sdk: ^3.1.0 dependencies: - path: ^1.8.0 + logging: ^1.2.0 + path: ^1.8.3 dev_dependencies: - lints: ^2.1.0 + analysis_defaults: + path: ../../site-shared/packages/analysis_defaults diff --git a/tool/dartpad_picker/analysis_options.yaml b/tool/dartpad_picker/analysis_options.yaml index 5a6734098..b9bdf805a 100644 --- a/tool/dartpad_picker/analysis_options.yaml +++ b/tool/dartpad_picker/analysis_options.yaml @@ -1,27 +1 @@ -include: package:lints/recommended.yaml - -analyzer: - language: - strict-casts: true - strict-inference: true - strict-raw-types: true - -linter: - rules: - - always_declare_return_types - - cancel_subscriptions - - close_sinks - - comment_references - - one_member_abstracts - - only_throw_errors - - package_api_docs - - prefer_expression_function_bodies - - prefer_single_quotes - - sort_child_properties_last - - sort_unnamed_constructors_first - - test_types_in_equals - - throw_in_finally - - type_annotate_public_apis - - unawaited_futures - - use_enums - - use_super_parameters +include: package:analysis_defaults/analysis.yaml diff --git a/tool/dartpad_picker/lib/dartpad_picker.dart b/tool/dartpad_picker/lib/dartpad_picker.dart index dc78ba035..77615f051 100644 --- a/tool/dartpad_picker/lib/dartpad_picker.dart +++ b/tool/dartpad_picker/lib/dartpad_picker.dart @@ -20,15 +20,20 @@ class DartPadPicker { late final IFrameElement _iFrameElement; int _selected = 0; - DartPadPicker(this.iFrameHost, this.selectElement, this.snippets, - {this.dartPadUrl = 'https://dartpad.dev', this.frameId}) { + DartPadPicker( + this.iFrameHost, + this.selectElement, + this.snippets, { + this.dartPadUrl = 'https://dartpad.dev', + this.frameId, + }) { _initSelectElement(); _initDartPad(); } Snippet get _selectedSnippet => snippets[_selected]; - Map get _sourceCodeMessage => { + Map get _sourceCodeMessage => { 'sourceCode': { 'main.dart': _selectedSnippet.sourceCode, }, @@ -49,7 +54,9 @@ class DartPadPicker { void _initDartPad() { _iFrameElement = IFrameElement() - ..src = iFrameSrc(theme: 'dark', mode: 'dart'); + ..src = iFrameSrc(theme: 'dark', mode: 'dart') + ..attributes['loading'] = 'lazy'; + final id = frameId; if (id != null) { _iFrameElement.id = id; diff --git a/tool/dartpad_picker/pubspec.yaml b/tool/dartpad_picker/pubspec.yaml index bd8786660..0b898c9ad 100644 --- a/tool/dartpad_picker/pubspec.yaml +++ b/tool/dartpad_picker/pubspec.yaml @@ -1,9 +1,11 @@ name: dartpad_picker +publish_to: none environment: - sdk: ^2.19.4 + sdk: ^3.1.0 dev_dependencies: - build_runner: ^2.1.0 - build_web_compilers: ^3.2.0 - lints: ^2.1.0 + analysis_defaults: + path: ../../site-shared/packages/analysis_defaults + build_runner: ^2.4.6 + build_web_compilers: ^4.0.6 diff --git a/tool/dartpad_picker/web/dartpad_picker_main.dart b/tool/dartpad_picker/web/dartpad_picker_main.dart index e84d31518..2ed742b2d 100644 --- a/tool/dartpad_picker/web/dartpad_picker_main.dart +++ b/tool/dartpad_picker/web/dartpad_picker_main.dart @@ -5,8 +5,6 @@ import 'dart:html'; import 'package:dartpad_picker/dartpad_picker.dart'; -const tryDartIdPrefix = 'try-dart'; - void main() { if (isMobile()) { querySelector('.dash-dartpad')?.style.display = 'none'; diff --git a/tool/effective_dart_rules/analysis_options.yaml b/tool/effective_dart_rules/analysis_options.yaml index 3055d5ce6..b9bdf805a 100644 --- a/tool/effective_dart_rules/analysis_options.yaml +++ b/tool/effective_dart_rules/analysis_options.yaml @@ -1,28 +1 @@ -include: package:lints/recommended.yaml - -analyzer: - language: - strict-casts: true - strict-inference: true - strict-raw-types: true - -linter: - rules: - - always_declare_return_types - - cancel_subscriptions - - close_sinks - - comment_references - - one_member_abstracts - - only_throw_errors - - package_api_docs - - prefer_final_in_for_each - - prefer_final_locals - - prefer_single_quotes - - sort_child_properties_last - - sort_unnamed_constructors_first - - test_types_in_equals - - throw_in_finally - - type_annotate_public_apis - - unawaited_futures - - use_enums - - use_super_parameters +include: package:analysis_defaults/analysis.yaml diff --git a/tool/effective_dart_rules/bin/main.dart b/tool/effective_dart_rules/bin/main.dart index 53a9a2a39..0c3ebae72 100644 --- a/tool/effective_dart_rules/bin/main.dart +++ b/tool/effective_dart_rules/bin/main.dart @@ -35,7 +35,7 @@ void main() async { } } - final outFile = File(path.join(dirPath, 'toc.md')); + final outFile = File(path.join(dirPath, '_toc.md')); IOSink? out; try { out = outFile.openWrite(); @@ -83,7 +83,6 @@ void write(IOSink out, Section section) { } class Rule { - final String name; final String html; final String fragment; @@ -113,10 +112,10 @@ class Rule { html += '.'; - return Rule._(name, html, fragment); + return Rule._(html, fragment); } - Rule._(this.name, this.html, this.fragment); + Rule._(this.html, this.fragment); } class Section { diff --git a/tool/effective_dart_rules/pubspec.yaml b/tool/effective_dart_rules/pubspec.yaml index 9613d8ff4..f8d98d98f 100644 --- a/tool/effective_dart_rules/pubspec.yaml +++ b/tool/effective_dart_rules/pubspec.yaml @@ -1,16 +1,16 @@ name: effective_dart_rules description: > Builds a file with all the rules in the different sections of Effective Dart. -version: 0.0.4 publish_to: none environment: - sdk: ^3.0.0 + sdk: ^3.1.0 dependencies: html_unescape: ^2.0.0 - markdown: ^7.1.0 + markdown: ^7.1.1 path: ^1.8.3 dev_dependencies: - lints: ^2.1.0 + analysis_defaults: + path: ../../site-shared/packages/analysis_defaults diff --git a/tool/fetch-dart-sdk-sums.sh b/tool/fetch-dart-sdk-sums.sh index 068c35d1a..885bec68a 100755 --- a/tool/fetch-dart-sdk-sums.sh +++ b/tool/fetch-dart-sdk-sums.sh @@ -26,7 +26,7 @@ while (( "$#" )); do esac done -BASEURL="https://storage.googleapis.com/dart-archive/channels" +BASEURL="https://storage.flutter-io.cn/dart-archive/channels" CHANNELS="stable beta dev" ARCHS="amd64 arm64" ENDING='\\\n' @@ -34,7 +34,6 @@ ENDING='\\\n' printf "\n$(blue "Copy the following output and replace the existing code in the Dockerfile")\n" printf "$(blue "inside the 'set -eu' run statement:")\n\n" - for CHANNEL in $CHANNELS; do for ARCH in $ARCHS; do printf "$(yellow "${ARCH}_${CHANNEL})") $ENDING" diff --git a/tool/fetch-node-ppa-sum.sh b/tool/fetch-node-ppa-sum.sh deleted file mode 100755 index 85a9c433d..000000000 --- a/tool/fetch-node-ppa-sum.sh +++ /dev/null @@ -1,11 +0,0 @@ -#!/usr/bin/env bash -# Use this file locally to update Node PPA checksum value in the Dockerfile -set -eu -o pipefail - -NODE_PPA="node_ppa.sh" -curl -fsSL https://deb.nodesource.com/setup_lts.x -o "$NODE_PPA" -_checksum=$(shasum -a 256 $NODE_PPA) -read -a _fname_arr <<< "${_checksum}" # Read in string output as array -_checkonly="${_fname_arr%:*}" # Remove filename portion of checksum output -echo "NODE_SHA256="$_checkonly"; \\" -rm $NODE_PPA diff --git a/tool/get-dart/archive/analysis_options.yaml b/tool/get-dart/archive/analysis_options.yaml index 5a6734098..b9bdf805a 100644 --- a/tool/get-dart/archive/analysis_options.yaml +++ b/tool/get-dart/archive/analysis_options.yaml @@ -1,27 +1 @@ -include: package:lints/recommended.yaml - -analyzer: - language: - strict-casts: true - strict-inference: true - strict-raw-types: true - -linter: - rules: - - always_declare_return_types - - cancel_subscriptions - - close_sinks - - comment_references - - one_member_abstracts - - only_throw_errors - - package_api_docs - - prefer_expression_function_bodies - - prefer_single_quotes - - sort_child_properties_last - - sort_unnamed_constructors_first - - test_types_in_equals - - throw_in_finally - - type_annotate_public_apis - - unawaited_futures - - use_enums - - use_super_parameters +include: package:analysis_defaults/analysis.yaml diff --git a/tool/get-dart/archive/compile.sh b/tool/get-dart/archive/compile.sh index 65eb3405b..60040f2b7 100755 --- a/tool/get-dart/archive/compile.sh +++ b/tool/get-dart/archive/compile.sh @@ -5,7 +5,7 @@ cd -P -- "$(dirname -- "${BASH_SOURCE[0]}")" : ${TMP:=tmp} OUT_DIR="$TMP/download_archive" -DEST_DIR=../../../src/get-dart/archive/assets +DEST_DIR=../../../src/assets/js/get-dart set -x diff --git a/tool/get-dart/archive/pubspec.yaml b/tool/get-dart/archive/pubspec.yaml index 8ec61f5f0..ff4fbdaae 100644 --- a/tool/get-dart/archive/pubspec.yaml +++ b/tool/get-dart/archive/pubspec.yaml @@ -3,13 +3,14 @@ description: Display a list of downloads for dart.dev. publish_to: none environment: - sdk: ^2.19.4 + sdk: ^3.1.0 dependencies: dart_sdk_archive: path: ../dart_sdk_archive dev_dependencies: - build_runner: ^2.3.3 - build_web_compilers: ^3.2.7 - lints: ^2.1.0 + analysis_defaults: + path: ../../../site-shared/packages/analysis_defaults + build_runner: ^2.4.6 + build_web_compilers: ^4.0.5 diff --git a/tool/get-dart/archive/web/download_archive.dart b/tool/get-dart/archive/web/download_archive.dart index f0e25e5c2..574aa46f4 100644 --- a/tool/get-dart/archive/web/download_archive.dart +++ b/tool/get-dart/archive/web/download_archive.dart @@ -1,3 +1,3 @@ import 'package:dart_sdk_archive/dart_sdk_archive.dart' as sdk_archive_app; -void main() => sdk_archive_app.runApp(); +void main() async => await sdk_archive_app.runApp(); diff --git a/tool/get-dart/dart_sdk_archive/analysis_options.yaml b/tool/get-dart/dart_sdk_archive/analysis_options.yaml index 5a6734098..b9bdf805a 100644 --- a/tool/get-dart/dart_sdk_archive/analysis_options.yaml +++ b/tool/get-dart/dart_sdk_archive/analysis_options.yaml @@ -1,27 +1 @@ -include: package:lints/recommended.yaml - -analyzer: - language: - strict-casts: true - strict-inference: true - strict-raw-types: true - -linter: - rules: - - always_declare_return_types - - cancel_subscriptions - - close_sinks - - comment_references - - one_member_abstracts - - only_throw_errors - - package_api_docs - - prefer_expression_function_bodies - - prefer_single_quotes - - sort_child_properties_last - - sort_unnamed_constructors_first - - test_types_in_equals - - throw_in_finally - - type_annotate_public_apis - - unawaited_futures - - use_enums - - use_super_parameters +include: package:analysis_defaults/analysis.yaml diff --git a/tool/get-dart/dart_sdk_archive/lib/src/generator.dart b/tool/get-dart/dart_sdk_archive/lib/src/generator.dart index 6aca2218b..b71708ec1 100644 --- a/tool/get-dart/dart_sdk_archive/lib/src/generator.dart +++ b/tool/get-dart/dart_sdk_archive/lib/src/generator.dart @@ -6,13 +6,13 @@ class SvnVersionGenerator { final _downloader = DartDownloads(); Future> get svnVersions async { - var versionInfos = {}; + final versionInfos = {}; await Future.wait([ _loadVersionInfo(versionInfos, 'stable'), _loadVersionInfo(versionInfos, 'beta'), _loadVersionInfo(versionInfos, 'dev'), ]); - var result = {}; + final result = {}; versionInfos.forEach((revision, version) { result[revision] = version.toString(); }); @@ -23,7 +23,7 @@ class SvnVersionGenerator { Map versionInfos, String channel) async { final versionBaseNames = await _downloader .fetchVersionPaths(channel) - .map((s) => path.basename(s)) + .map(path.basename) .toList(); await Future.forEach(versionBaseNames, (name) async { @@ -31,7 +31,7 @@ class SvnVersionGenerator { return; } - var versionInfo = await _downloader.fetchVersion(channel, name); + final versionInfo = await _downloader.fetchVersion(channel, name); versionInfos[name] = versionInfo; }); } diff --git a/tool/get-dart/dart_sdk_archive/lib/src/run_app.dart b/tool/get-dart/dart_sdk_archive/lib/src/run_app.dart index 68975711d..6148e66d3 100644 --- a/tool/get-dart/dart_sdk_archive/lib/src/run_app.dart +++ b/tool/get-dart/dart_sdk_archive/lib/src/run_app.dart @@ -6,9 +6,9 @@ import 'package:http/browser_client.dart'; import 'package:sdk_builds/sdk_builds.dart'; Future runApp() async { - var client = DartDownloads(client: BrowserClient()); + final client = DartDownloads(client: BrowserClient()); - var stableSelector = VersionSelector( + final stableSelector = VersionSelector( 'stable', client, querySelector('#stable') as TableElement, @@ -16,7 +16,7 @@ Future runApp() async { querySelector('#stable-os') as SelectElement, ); - var betaSelector = VersionSelector( + final betaSelector = VersionSelector( 'beta', client, querySelector('#beta') as TableElement, @@ -24,7 +24,7 @@ Future runApp() async { querySelector('#beta-os') as SelectElement, ); - var devSelector = VersionSelector( + final devSelector = VersionSelector( 'dev', client, querySelector('#dev') as TableElement, diff --git a/tool/get-dart/dart_sdk_archive/lib/src/util.dart b/tool/get-dart/dart_sdk_archive/lib/src/util.dart index b00355247..369ff4196 100644 --- a/tool/get-dart/dart_sdk_archive/lib/src/util.dart +++ b/tool/get-dart/dart_sdk_archive/lib/src/util.dart @@ -6,10 +6,10 @@ import 'package:sdk_builds/sdk_builds.dart'; final _downloader = DartDownloads(); Future> fetchSdkVersions(String channel) async { - var versionPaths = await _downloader.fetchVersionPaths(channel).toList(); - var versions = []; - for (var versionPath in versionPaths) { - var basename = path.basename(versionPath); + final versionPaths = await _downloader.fetchVersionPaths(channel).toList(); + final versions = []; + for (final versionPath in versionPaths) { + final basename = path.basename(versionPath); if (basename == 'latest') { continue; } @@ -25,7 +25,7 @@ Future> fetchSdkVersions(String channel) async { bool isSvnRevision(String s) => int.tryParse(s) != null; String? svnRevisionForVersion(String svnVersion) { - for (var key in svnVersions.keys) { + for (final key in svnVersions.keys) { if (svnVersions[key] == svnVersion) { return key; } diff --git a/tool/get-dart/dart_sdk_archive/lib/src/version_selector.dart b/tool/get-dart/dart_sdk_archive/lib/src/version_selector.dart index 3b8b5dc37..8813f1b3f 100644 --- a/tool/get-dart/dart_sdk_archive/lib/src/version_selector.dart +++ b/tool/get-dart/dart_sdk_archive/lib/src/version_selector.dart @@ -29,11 +29,11 @@ class VersionSelector { _osSelector.onChange.listen((Event event) { filterTable(); }); - var versions = (await fetchSdkVersions(channel) + final versions = (await fetchSdkVersions(channel) ..sort()) .reversed - .toList(); - for (var version in versions) { + .toList(growable: false); + for (final version in versions) { addVersion(version); } @@ -54,12 +54,12 @@ class VersionSelector { } Future populateTable() async { - var selectedVersion = + final selectedVersion = _versionSelector.selectedOptions.first.attributes['value']; if (selectedVersion == null) return; clearTable(); - var svnRevision = svnRevisionForVersion(selectedVersion); - var versionInfo = + final svnRevision = svnRevisionForVersion(selectedVersion); + final versionInfo = await _client.fetchVersion(channel, svnRevision ?? selectedVersion); await findSystemLocale(); await initializeDateFormatting(Intl.systemLocale); @@ -72,18 +72,18 @@ class VersionSelector { } void clearTable() { - var rowsToRemove = List.from(_table.rows); + final rowsToRemove = List.from(_table.rows); // keep the header row rowsToRemove.removeAt(0); - for (var row in rowsToRemove) { + for (final row in rowsToRemove) { row.remove(); } } void filterTable() { - var selectedVersion = + final selectedVersion = _versionSelector.selectedOptions[0].attributes['value']; - var selectedOs = _osSelector.selectedOptions[0].attributes['value']; + final selectedOs = _osSelector.selectedOptions[0].attributes['value']; if (selectedVersion == 'all' && selectedOs == 'all') { _table.querySelectorAll('tr[data-version]').classes.remove('hidden'); } else { @@ -129,16 +129,16 @@ class VersionSelector { } void addVersion(Version version) { - var option = OptionElement() + final option = OptionElement() ..text = version.toString() ..attributes['value'] = version.toString(); _versionSelector.children.add(option); } void updateTable(VersionInfo versionInfo) { - for (var name in platforms.keys) { - var platformVariants = platforms[name] ?? const []; - for (var platformVariant in platformVariants) { + for (final name in platforms.keys) { + final platformVariants = platforms[name] ?? const []; + for (final platformVariant in platformVariants) { // ARMv7 builds only available later in 2015, ARMv8 in 03-2017 if (archiveMap[name] == 'linux') { if (platformVariant.architecture == 'ARMv7' && @@ -178,25 +178,29 @@ class VersionSelector { } } else if (name == 'Windows') { if (platformVariant.architecture == 'ARM64') { - // No Windows arm64 SDK builds before 2.18.0-41.0.dev, - // and only want to surface for dev. - // TODO: After this is marked beta or stable in 2.x, - // adjust the beta or stable check respectively. - if (versionInfo.version < Version(2, 18, 0, pre: '41.0.dev')) { + // Dev builds start at 2.18.0-41.0.dev. + if (versionInfo.channel == 'dev' && + versionInfo.version < Version(2, 18, 0, pre: '41.0.dev')) { continue; } - - if (const {'stable', 'beta'}.contains(versionInfo.channel)) { + // Beta builds start at 3.2.0-42.2.beta. + if (versionInfo.channel == 'beta' && + versionInfo.version < Version(3, 2, 0, pre: '42.2.beta')) { + continue; + } + // No stable builds yet. + if (versionInfo.channel == 'stable') { continue; } } } // Build rows for all supported builds. - var row = _table.tBodies.first.addRow() + final row = _table.tBodies.first.addRow() ..attributes['data-version'] = versionInfo.version.toString() ..attributes['data-os'] = archiveMap[name] ?? ''; - var versionCell = row.addCell()..text = versionInfo.version.toString(); + final versionCell = row.addCell() + ..text = versionInfo.version.toString(); versionCell.append(SpanElement() ..text = ' (${_prettyRevRef(versionInfo)})' ..classes.add('muted')); @@ -206,7 +210,7 @@ class VersionSelector { ..text = platformVariant.architecture; _addReleaseDateCell(versionInfo, row); const possibleArchives = ['Dart SDK', 'Debian package']; - var c = row.addCell()..classes.add('archives'); + final c = row.addCell()..classes.add('archives'); for (final pa in possibleArchives) { if (platformVariant.archives.contains(pa)) { @@ -252,10 +256,10 @@ class VersionSelector { } // Add DartDoc archive. - var row = _table.tBodies.first.addRow() + final row = _table.tBodies.first.addRow() ..attributes['data-version'] = versionInfo.version.toString() ..attributes['data-os'] = 'api'; - var rev = SpanElement() + final rev = SpanElement() ..text = ' (${_prettyRevRef(versionInfo)})' ..classes.add('muted'); row.addCell() @@ -266,15 +270,15 @@ class VersionSelector { _addReleaseDateCell(versionInfo, row); - var c = row.addCell()..classes.add('archives'); - var uri = '$_storageBase/channels/$channel/release/' + final c = row.addCell()..classes.add('archives'); + final uri = '$_storageBase/channels/$channel/release/' '${versionInfo.version}/api-docs/dartdocs-gen-api.zip'; c.append(AnchorElement() ..text = 'API docs' ..attributes['href'] = uri); - var templateRows = _table.querySelectorAll('.template'); - for (var row in templateRows) { + final templateRows = _table.querySelectorAll('.template'); + for (final row in templateRows) { row.remove(); } } diff --git a/tool/get-dart/dart_sdk_archive/pubspec.yaml b/tool/get-dart/dart_sdk_archive/pubspec.yaml index 3f238f2cd..d9959dc53 100644 --- a/tool/get-dart/dart_sdk_archive/pubspec.yaml +++ b/tool/get-dart/dart_sdk_archive/pubspec.yaml @@ -3,20 +3,21 @@ description: An absolute bare-bones web app. publish_to: none environment: - sdk: ^2.19.4 + sdk: ^3.1.0 dependencies: - http: ^0.13.5 - intl: ^0.18.0 + http: ^1.1.0 + intl: ^0.18.1 path: ^1.8.3 - pub_semver: ^2.1.3 + pub_semver: ^2.1.4 sdk_builds: path: ../sdk_builds.dart dev_dependencies: - build_runner: ^2.3.3 - build_web_compilers: ^3.2.7 - dart_style: ^2.2.4 - grinder: ^0.9.3 - lints: ^2.1.0 - test: ^1.24.2 + analysis_defaults: + path: ../../../site-shared/packages/analysis_defaults + build_runner: ^2.4.6 + build_web_compilers: ^4.0.5 + dart_style: ^2.3.2 + grinder: ^0.9.4 + test: ^1.24.6 diff --git a/tool/get-dart/dart_sdk_archive/test/svn_revisions_test.dart b/tool/get-dart/dart_sdk_archive/test/svn_revisions_test.dart index 83b6fcad2..48301ce16 100644 --- a/tool/get-dart/dart_sdk_archive/test/svn_revisions_test.dart +++ b/tool/get-dart/dart_sdk_archive/test/svn_revisions_test.dart @@ -5,7 +5,7 @@ import 'package:test/test.dart'; void main() { group('dart_sdk_archive', () { test('can get all SDK versions', () async { - var versions = await fetchSdkVersions('stable'); + final versions = await fetchSdkVersions('stable'); expect(versions, isNotEmpty); expect(versions, contains(Version.parse('1.4.0'))); expect(versions, contains(Version.parse('2.3.1'))); diff --git a/tool/get-dart/dart_sdk_archive/tool/grind.dart b/tool/get-dart/dart_sdk_archive/tool/grind.dart index ed9901b22..ecfd9b3c1 100644 --- a/tool/get-dart/dart_sdk_archive/tool/grind.dart +++ b/tool/get-dart/dart_sdk_archive/tool/grind.dart @@ -1,24 +1,26 @@ +// ignore_for_file: unreachable_from_main + import 'dart:convert'; import 'dart:io'; import 'package:dart_sdk_archive/src/generator.dart'; -import 'package:grinder/grinder.dart'; import 'package:dart_style/dart_style.dart'; +import 'package:grinder/grinder.dart'; -void main(List args) => grind(args); +Future main(List args) async => await grind(args); @DefaultTask('Build SVN Revision JSON') void buildJson() async { print('fetching SVN versions...'); - var filePath = 'lib/src/svn_versions.dart'; - var generator = SvnVersionGenerator(); - var svnVersions = await generator.svnVersions; - var file = File(filePath); - var jsonStr = json.encode(svnVersions); - var fileContents = ''' + final filePath = 'lib/src/svn_versions.dart'; + final generator = SvnVersionGenerator(); + final svnVersions = await generator.svnVersions; + final file = File(filePath); + final jsonStr = json.encode(svnVersions); + final fileContents = ''' const Map svnVersions = $jsonStr; '''; - var formatted = DartFormatter().format(fileContents); + final formatted = DartFormatter().format(fileContents); file.writeAsBytesSync(utf8.encode(formatted)); print('$filePath written'); diff --git a/tool/get-dart/dart_sdk_archive/web/main.dart b/tool/get-dart/dart_sdk_archive/web/main.dart index f0e25e5c2..574aa46f4 100644 --- a/tool/get-dart/dart_sdk_archive/web/main.dart +++ b/tool/get-dart/dart_sdk_archive/web/main.dart @@ -1,3 +1,3 @@ import 'package:dart_sdk_archive/dart_sdk_archive.dart' as sdk_archive_app; -void main() => sdk_archive_app.runApp(); +void main() async => await sdk_archive_app.runApp(); diff --git a/tool/get-dart/sdk_builds.dart/analysis_options.yaml b/tool/get-dart/sdk_builds.dart/analysis_options.yaml index 5a6734098..b9bdf805a 100644 --- a/tool/get-dart/sdk_builds.dart/analysis_options.yaml +++ b/tool/get-dart/sdk_builds.dart/analysis_options.yaml @@ -1,27 +1 @@ -include: package:lints/recommended.yaml - -analyzer: - language: - strict-casts: true - strict-inference: true - strict-raw-types: true - -linter: - rules: - - always_declare_return_types - - cancel_subscriptions - - close_sinks - - comment_references - - one_member_abstracts - - only_throw_errors - - package_api_docs - - prefer_expression_function_bodies - - prefer_single_quotes - - sort_child_properties_last - - sort_unnamed_constructors_first - - test_types_in_equals - - throw_in_finally - - type_annotate_public_apis - - unawaited_futures - - use_enums - - use_super_parameters +include: package:analysis_defaults/analysis.yaml diff --git a/tool/get-dart/sdk_builds.dart/example/print_latest_versions.dart b/tool/get-dart/sdk_builds.dart/example/print_latest_versions.dart index 6846021f8..227afacd0 100644 --- a/tool/get-dart/sdk_builds.dart/example/print_latest_versions.dart +++ b/tool/get-dart/sdk_builds.dart/example/print_latest_versions.dart @@ -1,7 +1,6 @@ -// Copyright (c) 2015, . All rights reserved. Use of this source code -// is governed by a BSD-style license that can be found in the LICENSE file. - -library sdk_builds.example; +// Copyright 2015 the Dart project authors. All rights reserved. +// Use of this source code is governed by a BSD-style license +// that can be found in the LICENSE file. import 'dart:async'; @@ -19,7 +18,7 @@ void main() async { } Future latest(String channel) async { - var info = await _dd.fetchVersion(channel, 'latest'); + final info = await _dd.fetchVersion(channel, 'latest'); print('$channel\t${info.version}'); } diff --git a/tool/get-dart/sdk_builds.dart/lib/sdk_builds.dart b/tool/get-dart/sdk_builds.dart/lib/sdk_builds.dart index c0b3f709c..b7d0ec8a9 100644 --- a/tool/get-dart/sdk_builds.dart/lib/sdk_builds.dart +++ b/tool/get-dart/sdk_builds.dart/lib/sdk_builds.dart @@ -1,4 +1,2 @@ -library sdk_builds; - export 'src/dart_downloads.dart'; export 'src/version_info.dart'; diff --git a/tool/get-dart/sdk_builds.dart/lib/src/dart_downloads.dart b/tool/get-dart/sdk_builds.dart/lib/src/dart_downloads.dart index 9ed439ebd..baf234729 100644 --- a/tool/get-dart/sdk_builds.dart/lib/src/dart_downloads.dart +++ b/tool/get-dart/sdk_builds.dart/lib/src/dart_downloads.dart @@ -1,5 +1,3 @@ -library sdk_builds.dart_downloads; - import 'dart:convert'; import 'package:googleapis/storage/v1.dart' as storage; @@ -17,8 +15,11 @@ const storageBaseUrl = 'https://storage.flutter-io.cn/'; const _dartChannel = 'dart-archive'; const _flavor = 'release'; -String _revisionPath(String channel, String revision, - [List extra = const []]) => +String _revisionPath( + String channel, + String revision, [ + List extra = const [], +]) => p.joinAll(['channels', channel, _flavor, revision, ...extra]); class DartDownloads { @@ -94,7 +95,7 @@ class DartDownloads { continue; } - for (var item in prefixes) { + for (final item in prefixes) { yield item; } } while (nextToken != null); @@ -102,16 +103,20 @@ class DartDownloads { Future fetchVersion(String channel, String revision) async { final media = await _fetchFile(channel, revision, 'VERSION'); - final creationTime = (await _fetchMetadata(channel, revision, 'VERSION')) - .timeCreated as DateTime?; + final creationTime = + (await _fetchMetadata(channel, revision, 'VERSION')).timeCreated; final json = await _jsonAsciiDecoder .bind(media.stream) - .cast>() + .cast>() .first; - return VersionInfo.parse(channel, revision, json, - creationTime: creationTime); + return VersionInfo.parse( + channel, + revision, + json, + creationTime: creationTime, + ); } void close() => _client.close(); @@ -119,14 +124,18 @@ class DartDownloads { Future _fetchFile( String channel, String revision, String path) async => await _api.objects.get( - _dartChannel, _revisionPath(channel, revision, [path]), - downloadOptions: storage.DownloadOptions.fullMedia) as storage.Media; + _dartChannel, + _revisionPath(channel, revision, [path]), + downloadOptions: storage.DownloadOptions.fullMedia, + ) as storage.Media; - Future _fetchMetadata( + Future _fetchMetadata( String channel, String revision, String path) async => await _api.objects.get( - _dartChannel, _revisionPath(channel, revision, [path]), - downloadOptions: storage.DownloadOptions.metadata); + _dartChannel, + _revisionPath(channel, revision, [path]), + downloadOptions: storage.DownloadOptions.metadata, + ) as storage.Object; } final _jsonAsciiDecoder = json.fuse(ascii).decoder; diff --git a/tool/get-dart/sdk_builds.dart/lib/src/version_info.dart b/tool/get-dart/sdk_builds.dart/lib/src/version_info.dart index c400c2e79..5d35da674 100644 --- a/tool/get-dart/sdk_builds.dart/lib/src/version_info.dart +++ b/tool/get-dart/sdk_builds.dart/lib/src/version_info.dart @@ -1,5 +1,3 @@ -library sdk_builds.version_info; - import 'package:pub_semver/pub_semver.dart'; final _oldRevisionPostfix = RegExp(r'(\d+\.\d+\.\d+)\.(\d+)_r(\d+)'); @@ -11,12 +9,20 @@ abstract class VersionInfo implements Comparable { final String revisionPath; final DateTime? creationTime; - VersionInfo(this.version, this.date, this.channel, this.revisionPath, - {this.creationTime}); + VersionInfo( + this.version, + this.date, + this.channel, + this.revisionPath, { + this.creationTime, + }); static VersionInfo parse( - String channel, String revisionPath, Map json, - {DateTime? creationTime}) { + String channel, + String revisionPath, + Map json, { + DateTime? creationTime, + }) { // Date parse magic var dateJson = json['date'] as String; DateTime date; @@ -44,12 +50,24 @@ abstract class VersionInfo implements Comparable { // assume git! assert(revision.length == 40); - return GitVersionInfo(version, date, channel, revisionPath, revision, - creationTime: creationTime); + return GitVersionInfo( + version, + date, + channel, + revisionPath, + revision, + creationTime: creationTime, + ); } - return SvnVersionInfo(version, date, channel, revisionPath, svnRevision, - creationTime: creationTime); + return SvnVersionInfo( + version, + date, + channel, + revisionPath, + svnRevision, + creationTime: creationTime, + ); } @override @@ -62,15 +80,25 @@ abstract class VersionInfo implements Comparable { class SvnVersionInfo extends VersionInfo { final int revision; - SvnVersionInfo(super.version, super.date, super.channel, super.revisionPath, - this.revision, - {super.creationTime}); + SvnVersionInfo( + super.version, + super.date, + super.channel, + super.revisionPath, + this.revision, { + super.creationTime, + }); } class GitVersionInfo extends VersionInfo { final String ref; GitVersionInfo( - super.version, super.date, super.channel, super.revisionPath, this.ref, - {super.creationTime}); + super.version, + super.date, + super.channel, + super.revisionPath, + this.ref, { + super.creationTime, + }); } diff --git a/tool/get-dart/sdk_builds.dart/pubspec.yaml b/tool/get-dart/sdk_builds.dart/pubspec.yaml index 0e30ab9d0..6d412fa60 100644 --- a/tool/get-dart/sdk_builds.dart/pubspec.yaml +++ b/tool/get-dart/sdk_builds.dart/pubspec.yaml @@ -3,14 +3,15 @@ description: Utilities for accessing builds of the Dart SDK. publish_to: none environment: - sdk: ^2.19.4 + sdk: ^3.1.0 dependencies: - googleapis: ^10.1.0 - http: ^0.13.5 + googleapis: ^11.4.0 + http: ^1.1.0 path: ^1.8.3 - pub_semver: ^2.1.3 + pub_semver: ^2.1.4 dev_dependencies: - lints: ^2.1.0 - test: ^1.24.2 + analysis_defaults: + path: ../../../site-shared/packages/analysis_defaults + test: ^1.24.6 diff --git a/tool/get-dart/sdk_builds.dart/test/sdk_builds_test.dart b/tool/get-dart/sdk_builds.dart/test/sdk_builds_test.dart index 7cfa64534..377f26920 100644 --- a/tool/get-dart/sdk_builds.dart/test/sdk_builds_test.dart +++ b/tool/get-dart/sdk_builds.dart/test/sdk_builds_test.dart @@ -1,25 +1,23 @@ -library sdk_builds.test; - import 'package:pub_semver/pub_semver.dart'; import 'package:sdk_builds/sdk_builds.dart'; import 'package:test/test.dart'; -late DartDownloads _dd; +late DartDownloads _dartDownloads; void main() async { setUp(() { - _dd = DartDownloads(); + _dartDownloads = DartDownloads(); }); tearDown(() { - _dd.close(); + _dartDownloads.close(); }); test('fetch version', () async { const revision = '31822'; const channel = 'stable'; - final version = await _dd.fetchVersion(channel, revision); + final version = await _dartDownloads.fetchVersion(channel, revision); expect(version.version, Version.parse('1.1.1')); }); @@ -27,7 +25,7 @@ void main() async { test('fetch version paths', () async { const channel = 'stable'; - final paths = await _dd.fetchVersionPaths(channel).toList(); + final paths = await _dartDownloads.fetchVersionPaths(channel).toList(); expect(paths, contains('channels/stable/release/29803/')); expect(paths, contains('channels/stable/release/latest/')); @@ -35,7 +33,7 @@ void main() async { }); test('fetchVersions', () async { - final versions = await _dd.fetchVersions('stable'); + final versions = await _dartDownloads.fetchVersions('stable'); expect(versions.length, greaterThanOrEqualTo(27)); }); @@ -45,8 +43,8 @@ void main() async { const channel = 'dev'; const revision = '1.11.0-dev.5.2'; - final content = - await _dd.fetchVersion(channel, revision) as GitVersionInfo; + final content = await _dartDownloads.fetchVersion(channel, revision) + as GitVersionInfo; expect(content.ref, '23736d3630da614c655d0569e1ba5af2021b1c61'); expect(content.version, Version.parse('1.11.0-dev.5.2')); @@ -57,8 +55,8 @@ void main() async { const channel = 'stable'; const revision = '44672'; - final content = - await _dd.fetchVersion(channel, revision) as SvnVersionInfo; + final content = await _dartDownloads.fetchVersion(channel, revision) + as SvnVersionInfo; expect(content.revision, 44672); expect(content.version, Version.parse('1.9.1')); @@ -67,7 +65,8 @@ void main() async { test('old revision with old date format', () async { // dev/release/30039 - 0.8.10.8_r30039 - final content = await _dd.fetchVersion('dev', '30039') as SvnVersionInfo; + final content = + await _dartDownloads.fetchVersion('dev', '30039') as SvnVersionInfo; expect(content.revision, 30039); expect(content.version, Version.parse('0.8.10-rev.8.30039')); @@ -79,7 +78,7 @@ void main() async { const channel = 'stable'; const revision = '44672'; - final content = await _dd.createDownloadLink( + final content = await _dartDownloads.createDownloadLink( channel, revision, 'api-docs/dart-api-docs.zip'); expect(content.pathSegments, [ 'download', diff --git a/tool/translator/build.sh b/tool/translator/build.sh index 1a6f6a1cf..1006ed2dd 100755 --- a/tool/translator/build.sh +++ b/tool/translator/build.sh @@ -1,47 +1,12 @@ -#!/usr/bin/env bash +#!/usr/bin/bash -# set -e -o pipefail +npm install -# source ./tool/shared/env-set-check.sh // shared folder no longer exists - -# while [[ "$1" == -* ]]; do -# case "$1" in -# --check-links) CHECK_LINKS=1; shift; -# # Use remaining arguments for call to check-links -# break;; -# -h|--help) echo "Usage: $(basename $0) [--help] [--check-links ...check-link-options]"; -# exit 0;; -# *) echo "ERROR: Unrecognized option: $1. Use --help for details."; -# exit 1;; -# esac -# done - -# echo "::group::build_site" - -# bundle exec jekyll --version; -# set -x; -# bundle exec jekyll build; - -# echo "::endgroup::" - -# [[ -z $CHECK_LINKS ]] && exit - -# echo "::group::check_links" - -# set -x; -# ./tool/shared/check-links.sh $*; - -# echo "::endgroup::" - -# echo "::group::english_chinese_toggle" - -bundle exec jekyll --version; -set -x; -bundle exec jekyll build; - -set -x -set -e -pwd +if [[ $JEKYLL_ENV == 'development' ]]; then + bundle exec jekyll build --config _config.yml,_config_dev.yml +else + bundle exec jekyll build --config _config.yml +fi mkdir -p _site/assets/ cp -r tool/translator/assets/* _site/assets/ @@ -51,7 +16,7 @@ cd tool/translator npm i npx gulp mark-side-toc npx nt inject '../../_site/**/!(*_cn).html' -c /assets/translator/css/translator.css -s /assets/translator/js/translator.js -m ./url-map.json -t ./text-map.json -npx nt mark '../../_site/**/!(*_cn).html' --mono +npx nt export '../../_site/**/!(*_cn).html' --mono npx gulp remove-space cd - diff --git a/tool/translator/package.json b/tool/translator/package.json index 0aca6ce2d..ab3b45ac0 100644 --- a/tool/translator/package.json +++ b/tool/translator/package.json @@ -9,7 +9,7 @@ "author": "Zhicheng WANG", "license": "MIT", "dependencies": { - "@awesome-fe/translate": "1.1.19", + "@awesome-fe/translate": "1.7.4", "gulp": "^4.0.2", "gulp-replace": "^1.0.0" } diff --git a/tool/update-dart-sums.sh b/tool/update-dart-sums.sh new file mode 100644 index 000000000..bd2333f70 --- /dev/null +++ b/tool/update-dart-sums.sh @@ -0,0 +1,34 @@ +#!/usr/bin/env bash + +# Use this file to update the Dart SHA256 hashes +# in the Dockerfile. Run after check-dart-sdk.sh + +lead='# BEGIN dart-sha$' +tail='# END dart-sha$' +new_file='tool/new-dart-hashes.txt' +existing_file='Dockerfile' + +new_hash=$(sed -n -e '/DART_SHA/ p' -e '/DART_SHA/ q' $new_file) +old_hash=$(sed -n -e '/DART_SHA/ p' -e '/DART_SHA/ q' $existing_file) + +echo -e "Old $old_hash" +echo -e "New $new_hash" + +if [[ -z "$new_hash" ]]; then + echo "No new hash found." +else [[ -z "$old_hash" ]] + echo "Comparing hashes" + if [["$new_hash" = "$old_hash"]]; then + echo "Hashes match. No changes needed." + else + echo "New hashes found. Replacing hashes.\n" + echo $(sed -i.save -e "/$lead/,/$tail/{ /$lead/{p; r $new_file + }; /$tail/p;d;}" $existing_file) + echo "Replaced hashes" + fi +fi + +rm $new_file +echo -e "Removed $new_file. Re-run check-dart-sdk.sh to pull the current SHA hashes.\n" + +echo -e "Update completed."